String Patterns
String Patterns
A string pattern is a combination of characters that can be used to find very specific pieces (often called substrings) that exist inside a longer string. String patterns are used with several string functions provided by Lua.
Direct Matches
Direct matches can be done for any non-magic characters by simply using them literally in a Lua function like string.match(). For example, these commands look for the word Roblox within a string and output the result:
A match is found in the first string, so Roblox is output to the console. However, a match is not found in the second string and the output is nil.
Character Classes
Character classes are essential for more advanced string searches. They’re a way to search for something that isn’t specific, but it fits within a known category (class). In Lua, you can search a string for letters, digits (numbers), spaces, punctuation, and more.
The following table shows the official character classes for Lua string patterns:
| Class | Represents | Example Match |
|---|---|---|
. |
Any character | 32kasGJ1%fTlk?@94 |
%a |
An uppercase or lowercase letter | aBcDeFgHiJkLmNoPqRsTuVwXyZ |
%l |
A lowercase letter | abcdefghijklmnopqrstuvwxyz |
%u |
An uppercase letter | ABCDEFGHIJKLMNOPQRSTUVWXYZ |
%d |
Any digit (number) | 0123456789 |
%p |
Any punctuation character | !@#;,. |
%w |
An alphanumeric character (either a letter or a number) | aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789 |
%s |
A space or whitespace character | _, \n, and \r |
%c |
A special control character | |
%x |
A hexadecimal character | 0123456789ABCDEF |
%z |
The NULL character (\0) |
|
%bxy |
The balanced capture, matching x, y, and everything between (for example, %b() captures a pair of parentheses and everything between them) |
(I'm in parentheses!) |
%a, %s, etc. — the corresponding uppercase letter represents the “opposite” of the class. For instance, %p represents a punctuation character while %P represents all characters except punctuation.
Magic Characters
There are 12 “magic characters” which are reserved for special purposes in patterns:
$ |
% |
^ |
* |
( |
) |
. |
[ |
] |
+ |
- |
? |
These magic characters can not be searched for literally in a pattern. For instance, if you want to search for a . (period) inside a string, you cannot use "." as the pattern:
string.match("String ending with period.", ".") -- "." is the string pattern
Instead, you must precede the . (or any magic character) with a % symbol, for example %.. This tells Lua to search for the actual magic character:
string.match("String ending with period.", "%.") -- "%." is the string pattern
Quantifiers
By itself, a character class will only match one character in a string. For instance, the pattern below ("%d") starts reading the string from left to right, finds the first digit (2), and stops!
Fortunately, you can add a quantifier symbol after any character class. This lets you match a specific amount of characters defined by the class.
| Quantifier | Meaning |
|---|---|
+ |
Match 1 or more of the preceding character class |
- |
Match as few of the preceding character class as possible |
* |
Match 0 or more of the preceding character class |
? |
Match 1 or less of the preceding character class |
Character Class Sets
Sets should be used when a single character class can’t do the whole job. For instance, you might want to match both lowercase letters (%l) and punctuation characters (%p) using a single pattern.
Sets are defined by brackets [] around them. In the following example, notice the difference between using a set ("[%l%p]+") and not using a set ("%l%p+").
The first command (set) tells Lua to find both lowercase characters and punctuation. With the + quantifier added after the entire set, it finds all of those characters (ello!!!), stopping when it reaches the space.
In the second command (non-set), the + quantifier only applies to the %p class before it, so Lua grabs only the first lowercase character (o) before the series of punctuation (!!!).
^ character at the beginning of the set, directly after the opening [. For instance, "[%p%s]+" represents both punctuation and spaces, while "[^%p%s]+" represents all characters except punctuation and spaces.
String Captures
String captures are used to get specific pieces of a string and save them to variables. You can capture almost anything — a single character class, multiple characters (class with a quantifier), or even character class sets.
Captures are defined by parentheses () around them. Consider this example:
? quantifier that follows both of the %s classes. This is a smart addition because it makes the space on either side of the = sign optional. That means the match will succeed if one (or both) spaces are missing around the equal sign!