Scribunto: An Introduction/Strings

Most of the time in Scribunto, you will probably be working with text. As you may recall, a chunk of text is known as a string to programmers. Luckily, Lua gives programmers a great deal of flexibility in inputting and manipulating strings. In this chapter, we will introduce some string basics.

String input

In our first program in the debug console, we surrounded the text we wanted to display with double quotes.

Code:

= "Hello, world!"

Output:

Hello, world!

The double quotes tell Lua that we are inputting a string, not other Lua commands. However, it is not only double quotes that can make strings. You can do exactly the same thing with single quotes.

Code:

= 'Hello, world!'

Output:

Hello, world!

If your text contains a double quote or a single quote, you can get around it by using the other kind of quote.

Code:

= 'Susan said, "Hello!"'

Output:

Susan said, "Hello!"

Code:

= "This is Jim's book."

Output:

This is Jim's book.

If you try and use the same kind of quote you will get an error, as Lua doesn't know which quotes are part of the text and which should be the end of the string.

Code:

= "Susan said, "Hello!""

Output:

Lua error in console input at line 7: ')' expected near 'Hello'.

Escape sequences

It is quite convenient to be able to use either single quotes or double quotes to make a string. But what happens if the text we want to input contains both single and double quotes? One way of dealing with this is by using an escape sequence. With strings in single or double quotes, we can use the backslash \ to tell Lua that quote marks should be interpreted as quote marks in the text, not as quote marks that mark the end of the string.

Code:

= 'Susan said, "Jim said, \'Hello!\'"'

Output:

Susan said, "Jim said, 'Hello!'"

If you use backslashes with some letters, then they can have special meanings. For example, \n inserts a newline character.

Code:

= 'Hello, world!\nHello, Jim!\nHello, Susan!'

Output:

Hello, world!
Hello, Jim!
Hello, Susan!

You can also insert literal newlines into a string by adding a backslash at the end of a line. When you try this out in the debug console, you will need to press Shift + Enter at the end of each line. If you just press Enter, your code will be run, and Lua will raise an error as it can't find the end of the string.

Code:

= 'Hello, world!\
Hello, Jim!\
Hello, Susan!'

Output:

Hello, world!
Hello, Jim!
Hello, Susan!

Lua also provides other escape sequences, such as \t for a horizontal tab and \v for a vertical tab. It is also possible to specify a character by number by using a backslash followed by a number between 0 and 255; for example, \65 is the letter "A". However, it is unlikely that you will need need to use any of these.

To insert a backslash character as part of the text, without giving it any special meaning, you need to escape it with another backslash.

Code:

= 'C:\\Windows'

Output:

C:\Windows

Long brackets

We have seen that escape sequences allow us to create strings with both single and double quotes. But in fact, there is another way that we can do this: with long brackets. To create a long-bracket string, you surround your text with double square brackets.

Code:

= [[Susan said, "Jim said, 'Hello!'"]]

Output:

Susan said, "Jim said, 'Hello!'"

Long-bracket strings can stretch over multiple lines with no special formatting. For this reason, they are also known as multi-line strings. Again, remember to type Shift + Enter when you want to start a new line in the debug console, not just Enter.

Code:

= [[Hello, world!
Hello, Jim!
Hello, Susan!]]

Output:

Hello, world!
Hello, Jim!
Hello, Susan!

To aid the formatting of module code, if a long-bracket string starts with a new line, then that new line doesn't appear in the output. (This only works for the start of the string, not the end, however; if you add an extra newline to the end of the string, it will be interpreted as being part of the string.)

Code:

= [[
Hello, world!
Hello, Jim!
Hello, Susan!]]

Output:

Hello, world!
Hello, Jim!
Hello, Susan!

It is not possible to use escape sequences with long-bracket strings. All such sequences will be interpreted literally.

Code:

= [[Hello, world!\nHello, Jim!\nHello, Susan!]]

Output:

Hello, world!\nHello, Jim!\nHello, Susan!

You might have noticed that this double-square-bracket syntax is the same as the syntax for creating wikilinks in MediaWiki. Because of this coincidence, it is easy to find situations in which a string contains both single quotes, double quotes, and double square brackets. However, Lua still has a trick up its sleeves to deal with this.

This particular problem can be solved by using equals signs in between the two square brackets. In Lua, you can differentiate between levels of long brackets using equals signs. For example, [=[Hello, world!]=], [==[Hello, world!]==] and [=====[Hello, world!]=====] all produce the string "Hello, world!" Just make sure that you use the same number of equals signs to start and end the long brackets.

Code:

= [=[Sally said, "He was reading the [[Schrödinger's cat]] article."]=]

Output:

Sally said, "He was reading the [[Schrödinger's cat]] article."

You can include double brackets inside a string inside a long-bracket string, as long as they don't clash with the starting and ending brackets.

Code:

= [=[The [[Wikipedia]] article]=]

Output:

The [[Wikipedia]] article

Code:

= [[The [[Wikipedia]] article]]

Output:

Lua error in console input at line 7: nesting of [[...]] is deprecated near '['.

Also, double square brackets aren't treated specially if they appear inside a normal string. Because of this, it will probably be easiest to use normal strings for everyday use, and reserve long-bracket strings for working on multiple lines or situations where you would otherwise have to use a lot of escape sequences.

Code:

= "The [[Wikipedia]] article"

Output:

The [[Wikipedia]] article

Joining strings together

You might often find yourself wanting to join two strings together. This can be done with the concatenation operator, ...

Code:

= "Hello, " .. "Fred!"

Output:

Hello, Fred!