We use cookies on this site to enhance your user experience

5 min

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:

print( string.match("Welcome to Roblox!", "Roblox") )
print( string.match("Welcome to my awesome game!", "Roblox") )

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
%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!)

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


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!

print( string.match("The Cloud Kingdom has 25 power gems", "%d") )

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+").

print( string.match("Hello!!! I am another string.", "[%l%p]+") )  -- Set
print( string.match("Hello!!! I am another string.", "%l%p+") )    -- Non-set

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 (!!!).

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:

local pattern = "(%a+)%s?=%s?(%d+)"

local key1, val1 = string.match( "TwentyOne = 21", pattern)
print(key1, val1)

local key2, val2 = string.match( "TwoThousand= 2000", pattern)
print(key2, val2)

local key3, val3 = string.match( "OneMillion=1000000", pattern)
print(key3, val3)