Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 32 ยท Standard Library and Tools

String Patterns

Learn Lua string patterns: character classes, quantifiers, captures, anchors, %b and %f, and the find, match, gmatch and gsub functions. How they differ from regex.

Lua's standard library has no regular-expression engine. Instead, the string library ships with patterns: a compact matching language that handles most day-to-day text jobs in a few hundred lines of C. Patterns look a little like regular expressions, but they are simpler and a few things work differently, so it pays to learn them on their own terms.

In this lesson you will learn the pattern building blocks (character classes, sets, quantifiers and anchors), how captures pull parts out of a match, the four functions that use patterns (find, match, gmatch and gsub), the special items %b and %f, and what patterns cannot do. You should know strings first.

Lua is not installed on this site, so the Lua listings are read-only and show what real Lua prints. The runnable examples use a small JavaScript helper that translates the subset of Lua patterns used here into JavaScript regular expressions. It is a stand-in for learning, not a complete implementation.

Patterns versus regex

Smaller A handful of items, easy to remember.
% escapes Not a backslash.
No alternation There is no | operator.
Quantifiers Only apply to one character item.
1 / 2

Character classes

A pattern is a sequence of items. The simplest item is an ordinary character, which matches itself. A character class matches any one character from a group. Classes are written with a percent sign and a letter:

Class Matches
. any character
%a a letter
%d a digit
%l / %u lowercase / uppercase letter
%s white space
%w a letter or digit
%x a hexadecimal digit
%p a punctuation character

The uppercase form is the complement: %D matches anything that is not a digit, %S anything that is not white space. The characters ^$()%.[]*+-? have special meaning. To match one literally, put a % in front: %. is a dot and %% is a percent sign. Note the escape character is %, not a backslash, which makes patterns pleasant to write inside Lua strings.

A set in square brackets matches one character from a list: [aeiou] is a vowel, [a-f] is a range, [%w_] is a letter, digit or underscore, and [^%s] is anything but white space.

Quantifiers and anchors

A single character item can be followed by a quantifier:

Item Meaning
x* zero or more, as many as possible
x+ one or more, as many as possible
x- zero or more, as few as possible (lazy)
x? zero or one

So %d+ matches a whole number and %s* matches any amount of white space (including none). The lazy - is how you write what regular expressions call *?; it is the most useful difference to remember, because .- means "anything, but stop as soon as the rest of the pattern matches".

Quantifiers only apply to a single character, class or set. You cannot write (ab)+, and there is no count; repeat the item (%d%d%d) or build the pattern with string.rep.

A ^ at the start of a pattern anchors it to the start of the string, and a $ at the end anchors it to the end. Anywhere else they are ordinary characters. So ^%d+$ matches only if the whole string is digits.

find and match

string.find(s, pattern, init, plain) returns the start and end positions of the first match, followed by any captures, or nil if there is no match. string.match(s, pattern, init) returns the captures instead (or the whole match if there are none).

LUA
print(("hello world"):find("o w"))
print(("hello world"):find("xyz"))
print(("key = value"):match("(%w+)%s*=%s*(%w+)"))
print(("2024-05-17"):match("(%d+)-(%d+)-(%d+)"))
print(("1.5"):find(".", 1, true))
TEXT
5	7
nil
key	value
2024	05	17
2	2

The parentheses define captures: the parts of the match you want back. Notice that the digits come back as strings, so convert with tonumber when you need numbers. The last line passes true as the fourth argument, which switches find to a plain text search with no pattern characters, so the dot matches only a real dot, at position 2. Use plain searches whenever you search for text you did not write yourself.

Anchors and trimming

LUA
print(("  trim me  "):match("^%s*(.-)%s*$"))
print(("0x1F"):match("^0x(%x+)$"))
print(("abc"):match("^%d+$"))
TEXT
trim me
1F
nil

The first line is the classic trim idiom. ^%s* eats leading space, (.-) lazily captures the text, and %s*$ consumes trailing space up to the end. The lazy quantifier is essential: a greedy (.*) would capture the trailing spaces as well.

JS find, match and the lazy quantifier

Press Run (or Ctrl + Enter) to see the console output here.

No output.

gmatch: every match

string.gmatch(s, pattern) returns an iterator for use in a generic for loop. Each step gives the captures of the next match, or the whole match when the pattern has no captures.

LUA
for key, value in ("name=Ann, age=30"):gmatch("(%w+)=(%w+)") do
  print(key, value)
end

for word in ("a,b,,c"):gmatch("[^,]+") do
  io.write(word, " ")
end
print()
TEXT
name	Ann
age	30
a b c 

The set [^,] means "any character except a comma", so [^,]+ splits a string on commas. It skips empty fields, which is why ,, produced nothing. This "match the stuff between separators" style replaces the split function that Lua does not have.

gsub: replace

string.gsub(s, pattern, repl, n) replaces matches and returns the new string and the number of replacements. The replacement can be a string, a table or a function:

  • A string: %1 to %9 insert captures, %0 the whole match, and %% a literal percent sign.
  • A table: the first capture (or the whole match) is looked up as a key. If the value is nil or false, the original text stays.
  • A function: it is called with the captures, and its return value is used. Return nil or false to keep the original text.
LUA
print(("hello world"):gsub("o", "0"))
print(("john smith"):gsub("(%a+) (%a+)", "%2, %1"))
print(("$name is $age"):gsub("%$(%w+)", {name = "Ann", age = 30}))
print(("a1b22"):gsub("%d+", function(d) return "<" .. d .. ">" end))
print(("aaa"):gsub("a", "b", 2))
TEXT
hell0 w0rld	2
smith, john	1
Ann is 30	2
a<1>b<22>	2
bba	2

The fourth argument limits the number of replacements. If you only want the new string, wrap the call in parentheses, (s:gsub(...)), so the second result is dropped.

More captures, %b and %f

An empty pair of parentheses, (), captures a position instead of text. A %1 in the pattern itself matches whatever capture 1 matched, which is useful for paired quotes:

LUA
print(("hello"):find("()ll()"))
print(("say 'hi' or \"yo\""):match("(['\"])(.-)%1"))
TEXT
3	4	3	5
'	hi

The first line gives the match positions 3 and 4, then the two position captures 3 and 5. The second finds a quoted word, whichever quote character opened it, because %1 must match the same character again.

Two special items handle jobs that plain character classes cannot:

  • %bxy matches a balanced run that starts with x and ends with y, counting nested pairs. ("f(a(b)c) d"):match("%b()") returns (a(b)c).
  • %f[set] is the frontier: it matches an empty spot where the previous character is not in the set but the next one is. It marks word boundaries, for example %f[%a]%a+%f[%A] finds a whole word. ("one two"):gsub("%f[%w]%w+", string.upper) gives ONE TWO and 2.

What patterns cannot do

There is no alternation: cat|dog does not work. Use two searches, or look the matched word up in a table. There are no groups with quantifiers, no counted repeats like {2,4}, and no lookahead or lookbehind. For anything that complicated, write a small parser with a loop, or use a library such as LPeg. Fortunately most tasks (trimming, splitting, extracting numbers, simple formats) fit patterns well.

JS Words, balanced text and alternatives

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common mistakes

  • Using a backslash instead of %. The escape character in patterns is %.
  • Forgetting to escape magic characters. ("a.b"):find(".") matches the first character, position 1, not the dot. Write %. or pass true as the fourth argument.
  • Using - for a literal hyphen. Outside a set, - is a lazy quantifier. Write %-.
  • Greedy captures. .* takes as much as possible; prefer .- when you want the shortest match.
  • Expecting numbers. Captures are always strings.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the pattern %d+ match in the string "abc 123 def"?

    %d is a digit and + means one or more, as many as possible, so the match is the whole run of digits.
  2. 2. How do you write a lazy 'zero or more of any character' in a Lua pattern?

    In Lua patterns the minus sign is the lazy quantifier. There is no *? and no brace counts.
  3. 3. What does ("John Smith"):gsub("(%a+) (%a+)", "%2 %1") return?

    %1 and %2 in the replacement insert the captures. gsub also returns the number of replacements, here 1.
  4. 4. Which of these can a Lua pattern do?

    %b matches balanced pairs. Alternation, group quantifiers and lookahead are not supported.
  5. 5. What is the type of the captures returned by ("2024-05"):match("(%d+)-(%d+)")?

    Captures are substrings, so you must call tonumber if you want numbers.

Summary

  • Patterns use % escapes, character classes such as %a, %d, %s, %w, and sets in [...].
  • *, +, ? and lazy - apply to one character item; ^ and $ anchor the pattern.
  • find returns positions, match returns captures, gmatch loops over matches, gsub replaces them.
  • Captures are strings; () captures positions and %1 matches a repeat.
  • %b() matches balanced text and %f[set] matches word boundaries.
  • There is no alternation, group repetition or lookaround.

Finally, learn how to find and fix problems in Debugging, Performance and Common Mistakes.