Lua4z
A binary distribution of Lua for z/OS, with batteries

Module lpeg

A pattern-matching extension library based on parsing expression grammars (PEGs).

For more information, see the original LPeg documentation.

Functions

match (pattern, subject, init) The matching function.
type (value) If the given value is a pattern, returns the string "pattern".
version () Returns a string with the running version of LPeg.
setmaxstack (max) Sets the maximum size for the backtrack stack used by LPeg to track calls and choices.
P (value) Converts the given value into a proper pattern, according to the following rules: * If the argument is a pattern, it is returned unmodified.
R ({) Returns a pattern that matches any single character belonging to one of the given ranges.
S (string) Returns a pattern that matches any single character that appears in the given string.
V (v) This operation creates a non-terminal (a variable) for a grammar.
locale (table) Returns a table with patterns for matching some character classes according to the current locale.
C (patt) Creates a simple capture, which captures the substring of the subject that matches patt.
Carg (n) Creates an argument capture.
Cb (name) Creates a back capture.
Cc (...) Creates a constant capture.
Cf (patt, func) Creates a fold capture.
Cg (patt, name) Creates a group capture.
Cp () Creates a position capture.
Cs (patt) Creates a substitution capture, which captures the substring of the subject that matches patt, with substitutions.
Ct (patt) Creates a table capture.
Cmt (patt, function) Creates a match-time capture.

Functions

match (pattern, subject, init)
The matching function. It attempts to match the given pattern against the subject string. If the match succeeds, returns the index in the subject of the first character after the match, or the captured values (if the pattern captured any value).

An optional numeric argument init makes the match starts at that position in the subject string. As usual in Lua libraries, a negative value counts from the end.

Unlike typical pattern-matching functions, match works only in anchored mode; that is, it tries to match the pattern with a prefix of the given subject string (at position init), not with an arbitrary substring of the subject. So, if we want to find a pattern anywhere in a string, we must either write a loop in Lua or write a pattern that matches anywhere. This second approach is easy and quite efficient; see examples.

Parameters:

  • pattern
  • subject
  • init
type (value)
If the given value is a pattern, returns the string "pattern". Otherwise returns nil.

Parameters:

  • value
version ()
Returns a string with the running version of LPeg.
setmaxstack (max)
Sets the maximum size for the backtrack stack used by LPeg to track calls and choices. Most well-written patterns need little backtrack levels and therefore you seldom need to change this maximum; but a few useful patterns may need more space. Before changing this maximum you should try to rewrite your pattern to avoid the need for extra space.

Parameters:

  • max
P (value)

Converts the given value into a proper pattern, according to the following rules: * If the argument is a pattern, it is returned unmodified. * If the argument is a string, it is translated to a pattern that matches

literally the string.

* If the argument is a non-negative number n, the result is a pattern that

matches exactly n characters.

* If the argument is a negative number -n, the result is a pattern that

succeeds only if the input string does not have n characters: lpeg.P(-n)
is equivalent to -lpeg.P(n) (see the unary minus operation).

* If the argument is a boolean, the result is a pattern that always

succeeds or always fails (according to the boolean value), without
consuming any input.

* If the argument is a table, it is interpreted as a grammar (see

Grammars).

* If the argument is a function, returns a pattern equivalent to a

match-time capture over the empty string.

Parameters:

  • value
R ({)
Returns a pattern that matches any single character belonging to one of the given ranges. Each range is a string xy of length 2, representing all characters with code between the codes of x and y (both inclusive). As an example, the pattern lpeg.R("09") matches any digit, and `lpeg.R("az", "AZ")` matches any ASCII letter.

Parameters:

  • {
S (string)
Returns a pattern that matches any single character that appears in the given string. (The S stands for Set.) As an example, the pattern lpeg.S("+-*/") matches any arithmetic operator. Note that, if s is a character (that is, a string of length 1), then lpeg.P(s) is equivalent to lpeg.S(s) which is equivalent to lpeg.R(s..s). Note also that both lpeg.S("") and lpeg.R() are patterns that always fail.

Parameters:

  • string
V (v)
This operation creates a non-terminal (a variable) for a grammar. The created non-terminal refers to the rule indexed by v in the enclosing grammar. (See Grammars for details.)

Parameters:

  • v
locale (table)
Returns a table with patterns for matching some character classes according to the current locale. The table has fields:

  • alnum
  • alpha
  • cntrl
  • digit
  • graph
  • lower
  • print
  • punct
  • space
  • upper
  • xdigit

each one containing a correspondent pattern. Each pattern matches any single character that belongs to its class.

If called with an argument table, then it creates those fields inside the given table and returns that table.

Parameters:

  • table
C (patt)
Creates a simple capture, which captures the substring of the subject that matches patt. The captured value is a string. If patt has other captures, their values are returned after this one.

Parameters:

  • patt
Carg (n)
Creates an argument capture. This pattern matches the empty string and produces the value given as the nth extra argument given in the call to lpeg.match.

Parameters:

  • n
Cb (name)
Creates a back capture. This pattern matches the empty string and produces the values produced by the most recent group capture named name. Most recent means the last complete outermost group capture with the given name. A Complete capture means that the entire pattern corresponding to the capture has matched. An Outermost capture means that the capture is not inside another complete capture.

Parameters:

  • name
Cc (...)
Creates a constant capture. This pattern matches the empty string and produces all given values as its captured values.

Parameters:

  • ...
Cf (patt, func)

Creates a fold capture. If patt produces a list of captures C1 C2 ... Cn, this capture will produce the value func(...func(func(C1, C2), C3)..., Cn), that is, it will fold (or accumulate, or reduce) the captures from patt using function func.

This capture assumes that patt should produce at least one capture with at least one value (of any type), which becomes the initial value of an accumulator. (If you need a specific initial value, you may prefix a constant capture to patt.) For each subsequent capture LPeg calls func with this accumulator as the first argument and all values produced by the capture as extra arguments; the value returned by this call becomes the new value for the accumulator. The final value of the accumulator becomes the captured value.

As an example, the following pattern matches a list of numbers separated by commas and returns their addition:

-- matches a numeral and captures its value
number = lpeg.R"09"^1 / tonumber
-- matches a list of numbers, captures their values
list = number * ("," * number)^0
-- auxiliary function to add two numbers
function add (acc, newvalue) return acc + newvalue end
-- folds the list of numbers adding them
sum = lpeg.Cf(list, add)
-- example of use
print(sum:match("10,30,43"))   --> 83

Parameters:

  • patt
  • func
Cg (patt, name)
Creates a group capture. It groups all values returned by patt into a single capture. The group may be anonymous (if no name is given) or named with the given name. An anonymous group serves to join values from several captures into a single capture. A named group has a different behavior. In most situations, a named group returns no values at all. Its values are only relevant for a following back capture or when used inside a table capture.

Parameters:

  • patt
  • name
Cp ()
Creates a position capture. It matches the empty string and captures the position in the subject where the match occurs. The captured value is a number.
Cs (patt)
Creates a substitution capture, which captures the substring of the subject that matches patt, with substitutions. For any capture inside patt with a value, the substring that matched the capture is replaced by the capture value (which should be a string). The final captured value is the string resulting from all replacements.

Parameters:

  • patt
Ct (patt)
Creates a table capture. This capture creates a table and puts all values from all anonymous captures made by patt inside this table in successive integer keys, starting at 1. Moreover, for each named capture group created by patt, the first value of the group is put into the table with the group name as its key. The captured value is only the table.

Parameters:

  • patt
Cmt (patt, function)
Creates a match-time capture. 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 given 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 true, the match succeeds without consuming any input. (So, to return true is equivalent to return i.) 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.

Parameters:

  • patt
  • function