Summary
Creates a match-time capture
Prototype
lpeg.Cmt(patt, function)
Description
Unlike all other captures, this one is evaluated immediately when a match occurs. It forces the immediate evaluation of all its nested captures and then calls function.
The function gets as arguments the entire subject, the current position (after the match of patt), plus any capture values produced by patt.
The first value returned by function defines how the match happens. If the call returns a number, the match succeeds and the returned number becomes the new current position. (Assuming a subject s and current position i, the returned number must be in the range [i, len(s) + 1].) If the call returns false, nil, or no value, the match fails.
Any extra values returned by the function become the values produced by the capture.
For example:
A long string in Lua starts with the pattern [=*[ and ends at the first occurrence of ]=*] with exactly the same number of equal signs. If the opening brackets are followed by a newline, this newline is discharged (that is, it is not part of the string).
To match a long string in Lua, the pattern must capture the first repetition of equal signs and then, whenever it finds a candidate for closing the string, check whether it has the same number of equal signs.
equals = lpeg.P"="^0
open = "[" * lpeg.Cg(equals, "init") * "[" * lpeg.P"\n"^-1
close = "]" * lpeg.C(equals) * "]"
closeeq = lpeg.Cmt(close * lpeg.Cb("init"), function (s, i, a, b) return a == b end)
string = open * lpeg.C((lpeg.P(1) - closeeq)^0) * close / 1
print (string:match ("[===[ foo [=[ bar]=] ]===]")) -- test
The open pattern matches [=*[, capturing the repetitions of equal signs in a group named init; it also discharges an optional newline, if present. The close pattern matches ]=*], also capturing the repetitions of equal signs. The closeeq pattern first matches close; then it uses a back capture to recover the capture made by the previous open, which is named init; finally it uses a match-time capture to check whether both captures are equal. The string pattern starts with an open, then it goes as far as possible until matching closeeq, and then matches the final close. The final numbered capture simply discards the capture made by close.
See Also ...
Lua functions
lpeg.B - Matches patt n characters behind the current position, consuming no input
lpeg.C - Creates a simple capture
lpeg.Carg - Creates an argument capture
lpeg.Cb - Creates a back capture
lpeg.Cc - Creates a constant capture
lpeg.Cf - Creates a fold capture
lpeg.Cg - Creates a group capture
lpeg.Cp - Creates a position capture
lpeg.Cs - Creates a substitution capture
lpeg.Ct - Creates a table capture
lpeg.locale - Returns a table of patterns matching the current locale
lpeg.match - Matches a pattern against a string
lpeg.P - Converts a value into a pattern
lpeg.print - Outputs debugging information to stdout
lpeg.R - Returns a pattern that matches a range of characters
lpeg.S - Returns a pattern that matches a set of characters
lpeg.setmaxstack - Sets the maximum size for the backtrack stack
lpeg.type - Tests if a value is a pattern
lpeg.V - Creates a non-terminal variable for a grammar
lpeg.version - Returns the LPeg version
Topics
Lua bc (big number) functions
Lua bit manipulation functions
Lua LPEG library
Lua package functions
Lua PCRE regular expression functions
Lua script extensions
Lua string functions
Lua syntax
Lua table functions
Lua utilities
Regular Expressions
Scripting
Scripting callbacks - plugins
(Help topic: lua=lpeg.Cmt)