Module regex

Regular expressions.

The standard Lua library provides a handful of functions to deal with strings using “patterns”. Lua patterns, however, aren’t as powerful as the Regular Expressions many programmers have come to expect.

To fill this void, we also provide real, Perl-compatible regular expressions (henceforth: PCRE) for you to use in your Lua code. The API for this facility mimics the standard Lua API so you don’t need to learn anything new. These regex-compatible functions have p_ prefixed to their names. They're also available under the regexp namespace without this prefix.

For example, instead of:

local first, last = s:match "(%w+) (%w+)"
-- also available as:
-- local first, last = string.match(s, "(%w+) (%w+)")

do:

local first, last = s:p_match "(\\w+) (\\w+)"
-- also available as:
-- local first, last = regex.match(s, "(\\w+) (\\w+)")

for the PCRE version.

You can use Lua’s long literal string syntax to make your regular expressions more readable: you won’t have to escape your backslashes then. For example, the previous line of code would look like:

local first, last = s:p_match [[(\w+) (\w+)]]

Specifying regular expressions

There are three ways to specify a regular expression:

(1) As a string:

if file_extension:p_match "jpe?g" then ...

(2) As a table whose first element is a string and whose second element is a flags string:

if file_extension:p_match {"jpe?g","i"} then ...

The flags string may contain any of these letters (the order doesn’t matter):

“i” Case insensitive matching.

“u” Enable UTF-8 handling (makes … match three characters, not three bytes, and \w match non-English too).

“x” Extended regexp, which means you can use whitespaces and comments for readability.

“s” Makes dot match newline as well.

“m” Makes ^ and $ match newline boundaries as well.

For a regex that uses “smx”, see luafs_markdown.lua.

(3) As a compiled regex object:

local picture = regex.compile {"jpe?g","i"}
...
if file_extension:p_match(picture) then ...

Using a string (or a table) instead of a compiled regex isn’t inefficient: the string is compiled and kept in an internal cache. The next time you use the string the cache will be examined and the compiled regex be pulled out. This cache lookup, however, has some cost which you can save, especially in tight loops, by supplying the compiled regex directly.

Functions

regex.compile(regex) Compiles a regular expression.
find(s, regex[, init]) Searches in a string.
gmatch(s, regex) Matches globally.
gsub(s, regex, repl) Performs a global search/replace on a string.
match(s, regex[, init]) Searches in a string.
split(s, regex[, limit]) Splits a string.
tsplit(s, regex[, limit]) Splits a string into a table.


Functions

regex.compile(regex)
Compiles a regular expression.

The regex parameter may be in any of the three forms specified in “Specifying regular expressions”. If regex is already a compiled regex object, the function simply returns the same object.

as explained above, you don’t have to compile your regular expressions.

find(s, regex[, init])
Searches in a string.

Like string.find but uses a regular expression.

gmatch(s, regex)
Matches globally.

Like string.gmatch but uses a regular expression.

gsub(s, regex, repl)
Performs a global search/replace on a string.

Like string.gsub but uses a regular expression.

match(s, regex[, init])
Searches in a string.

Like string.match but uses a regular expression.

split(s, regex[, limit])
Splits a string.

If regex contains captures, these are returned as well.

local s = "flavor = sweet"
local name, value = s:p_split "\\s*=\\s*"

Use limit to set the maximum number of fields returned. The maximum possible value for limit is 12; use tsplit instead if this maximum restricts you.

tsplit(s, regex[, limit])
Splits a string into a table.

Like split but the results are returned as a table. There’s no restriction on limit.

generated by LDoc 1.4.3 Last updated 2016-08-23 17:29:40