[Home] [Downloads] [Search] [Help/forum]

lpeg.P

Summary

Converts a value into a pattern

Prototype

lpeg.P (value)


Description

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.

eg.

lpeg.P ("You gain") --> matches "You gain"

If the argument is a non-negative number n, the result is a pattern that matches exactly n characters.

eg.

lpeg.P (5) --> matches 5 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: It is equivalent to the unary minus operation applied over the pattern corresponding to the (non-negative) value n.

eg.

lpeg.P (-2) --> matches if there are not 2 more characters

lpeg.P (-1) --> matches if there are no more characters (ie. the end of the string)

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.

eg.

lpeg.P (true) --> matches always
lpeg.P (false) --> matches never

If the argument is a function, returns a pattern equivalent to a match-time capture over the empty string.

If the argument is a table, it is interpreted as a grammar (see below).


-- Grammars --

With the use of Lua variables, it is possible to define patterns incrementally, with each new pattern using previously defined ones. However, this technique does not allow the definition of recursive patterns. For recursive patterns, we need real grammars.

LPeg represents grammars with tables, where each entry is a rule.

The call lpeg.V(v) creates a pattern that represents the nonterminal (or variable) with index v in a grammar. Because the grammar still does not exist when this function is evaluated, the result is an open reference to the respective rule.

A table is fixed when it is converted to a pattern (either by calling lpeg.P or by using it wherein a pattern is expected). Then every open reference created by lpeg.V(v) is corrected to refer to the rule indexed by v in the table.

When a table is fixed, the result is a pattern that matches its initial rule. The entry with index 1 in the table defines its initial rule. If that entry is a string, it is assumed to be the name of the initial rule. Otherwise, LPeg assumes that the entry 1 itself is the initial rule.

As an example, the following grammar matches strings of a's and b's that have the same number of a's and b's:

equalcount = lpeg.P{
"S"; -- initial rule name
S = "a" * lpeg.V"B" + "b" * lpeg.V"A" + "",
A = "a" * lpeg.V"S" + "b" * lpeg.V"A" * lpeg.V"A",
B = "b" * lpeg.V"S" + "a" * lpeg.V"B" * lpeg.V"B",
} * -1


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.Cmt - Creates a match-time 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.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.P)

Documentation contents page


Search ...

Enter a search string to find matching documentation.

Search for:   

Quick links: MUSHclient. MUSHclient help. Forum shortcuts. Posting templates. Lua modules. Lua documentation.

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.

[Home]


Written by Nick Gammon - 5K   profile for Nick Gammon on Stack Exchange, a network of free, community-driven Q&A sites   Marriage equality

Comments to: Gammon Software support
[RH click to get RSS URL] Forum RSS feed ( https://gammon.com.au/rss/forum.xml )

[Best viewed with any browser - 2K]    [Hosted at FutureQuest]