This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.
The fourth edition targets Lua 5.3 and is available at Amazon and other bookstores.
By buying the book, you also help to support the Lua project.

	Programming in Lua
	Part III. The Standard Libraries Chapter 20. The String Library

20.2 – Patterns

You can make patterns more useful with character classes. A character class is an item in a pattern that can match any character in a specific set. For instance, the class %d matches any digit. Therefore, you can search for a date in the format dd/mm/yyyy with the pattern '%d%d/%d%d/%d%d%d%d':

    s = "Deadline is 30/05/1999, firm"
    date = "%d%d/%d%d/%d%d%d%d"
    print(string.sub(s, string.find(s, date)))   --> 30/05/1999

An upper case version of any of those classes represents the complement of the class. For instance, '%A' represents all non-letter characters:

    print(string.gsub("hello, up-down!", "%A", "."))
      --> hello..up.down. 4

Some characters, called magic characters, have special meanings when used in a pattern. The magic characters are

    ( ) . % + - * ? [ ^ $

For Lua, patterns are regular strings. They have no special treatment and follow the same rules as other strings. Only inside the functions are they interpreted as patterns and only then does the `%´ work as an escape. Therefore, if you need to put a quote inside a pattern, you must use the same techniques that you use to put a quote inside other strings; for instance, you can escape the quote with a `\´, which is the escape character for Lua.

A char-set allows you to create your own character classes, combining different classes and single characters between square brackets. For instance, the char-set '[%w_]' matches both alphanumeric characters and underscores, the char-set '[01]' matches binary digits, and the char-set '[%[%]]' matches square brackets. To count the number of vowels in a text, you can write

    _, nvow = string.gsub(text, "[AEIOUaeiou]", "")

Character classes follow the current locale set for Lua. Therefore, the class '[a-z]' can be different from '%l'. In a proper locale, the latter form includes letters such as `ç´ and `ã´. You should always use the latter form, unless you have a strong reason to do otherwise: It is simpler, more portable, and slightly more efficient.

You can make patterns still more useful with modifiers for repetitions and optional parts. Patterns in Lua offer four modifiers:

+	1 or more repetitions
*	0 or more repetitions
-	also 0 or more repetitions
?	optional (0 or 1 occurrence)

The `+´ modifier matches one or more characters of the original class. It will always get the longest sequence that matches the pattern. For instance, the pattern '%a+' means one or more letters, or a word:

    print(string.gsub("one, and two; and three", "%a+", "word"))
      --> word, word word; word word

    i, j = string.find("the number 1298 is even", "%d+")
    print(i,j)   --> 12  15

The modifier `*´ is similar to `+´, but it also accepts zero occurrences of characters of the class. A typical use is to match optional spaces between parts of a pattern. For instance, to match an empty parenthesis pair, such as () or ( ), you use the pattern '%(%s*%)'. (The pattern '%s*' matches zero or more spaces. Parentheses have a special meaning in a pattern, so we must escape them with a `%´.) As another example, the pattern '[_%a][_%w]*' matches identifiers in a Lua program: a sequence that starts with a letter or an underscore, followed by zero or more underscores or alphanumeric characters.

Like `*´, the modifier `-´ also matches zero or more occurrences of characters of the original class. However, instead of matching the longest sequence, it matches the shortest one. Sometimes, there is no difference between `*´ or `-´, but usually they present rather different results. For instance, if you try to find an identifier with the pattern '[_%a][_%w]-', you will find only the first letter, because the '[_%w]-' will always match the empty sequence. On the other hand, suppose you want to find comments in a C program. Many people would first try '/%*.*%*/' (that is, a "/*" followed by a sequence of any characters followed by "*/", written with the appropriate escapes). However, because the '.*' expands as far as it can, the first "/*" in the program would close only with the last "*/":

    test = "int x; /* x */  int y; /* y */"
    print(string.gsub(test, "/%*.*%*/", "<COMMENT>"))
      --> int x; <COMMENT>

    test = "int x; /* x */  int y; /* y */"
    print(string.gsub(test, "/%*.-%*/", "<COMMENT>"))
        --> int x; <COMMENT>  int y; <COMMENT>

The last modifier, `?´, matches an optional character. As an example, suppose we want to find an integer in a text, where the number may contain an optional sign. The pattern '[+-]?%d+' does the job, matching numerals like "-12", "23" and "+1009". The '[+-]' is a character class that matches both a `+´ or a `-´ sign; the following `?´ makes that sign optional.

Unlike some other systems, in Lua a modifier can only be applied to a character class; there is no way to group patterns under a modifier. For instance, there is no pattern that matches an optional word (unless the word has only one letter). Usually you can circumvent this limitation using some of the advanced techniques that we will see later.

If a pattern begins with a `^´, it will match only at the beginning of the subject string. Similarly, if it ends with a `$´, it will match only at the end of the subject string. These marks can be used both to restrict the patterns that you find and to anchor patterns. For instance, the test

    if string.find(s, "^%d") then ...

    if string.find(s, "^[+-]?%d+$") then ...

Another item in a pattern is the '%b', that matches balanced strings. Such item is written as '%bxy', where x and y are any two distinct characters; the x acts as an opening character and the y as the closing one. For instance, the pattern '%b()' matches parts of the string that start with a `(´ and finish at the respective `)´:

    print(string.gsub("a (enclosed (in) parentheses) line",
                      "%b()", ""))
      --> a  line

Copyright © 2003–2004 Roberto Ierusalimschy. All rights reserved.