MUSHclient documentation: lpeg.Cmt

lpeg.Cmt

lpeg.Cmt
Lua function lpeg.Cmt 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. open = "[" * lpeg.Cg(lpeg.P"="^0, "init") * "[" * lpeg.P"\n"^-1 close = "]" * lpeg.C(lpeg.P"="^0) * "]" closeeq = lpeg.Cmt(close * lpeg.Cb("init"), function (s, i, a, b) return a == b end) string = open * m.C((lpeg.P(1) - closeeq)^0) * close / function (o, s) return s end 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 ]=]. 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 function capture simply consumes the captures made by open and close and returns only the middle capture, which is the string contents. See Also ... 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 table functions Lua utilities Regular Expressions Scripting Lua functions 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.type (Tests if a value is a pattern) lpeg.V (Creates a non-terminal variable for a grammar) lpeg.version (Returns the LPeg version) (Help topic: lua=lpeg.Cmt) Documentation contents page

Lua function

lpeg.Cmt

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.



open = "[" * lpeg.Cg(lpeg.P"="^0, "init") * "[" * lpeg.P"\n"^-1

close = "]" * lpeg.C(lpeg.P"="^0) * "]"

closeeq = lpeg.Cmt(close * lpeg.Cb("init"), function (s, i, a, b) return a == b end)

string = open * m.C((lpeg.P(1) - closeeq)^0) * close /

  function (o, s) return s end



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 ]=*]. 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 function capture simply consumes the captures made by open and close and returns only the middle capture, which is the string contents.