internal package
Foswiki::Infix::Parser
internal package
Foswiki::Infix::Parser
A simple
LL(1) parser that parses infix expressions with nonary,
unary and binary operators specified using an operator table.
The parser works by examining each token in the input stream from left to right, and constructs
parse nodes as soon as they are identified. The parser doesn't dictate the type of the parse nodes,
instead using a
factory to generate them. the output from the parser is a
parse tree built using nodes generated by the node factory.
Escapes are supported in strings, using backslash.
ClassMethod
new($node_factory, \%options) → $parser_object
Creates a new infix parser. Operators must be added for it to be useful.
The tokeniser matches tokens in the following order: operators,
quotes (" and '), numbers, words, brackets. If you have any overlaps (e.g.
an operator '<' and a bracket operator '<<') then the first choice
will match.
$node_factory
needs to be ( the name of a package | an object ) that supports the
following two functions:
-
newLeaf($val, $type)
- create a terminal. $type will be:
- if the terminal matched the
words
specification (see below).
- if it is a number matched the
numbers
specification (see below)
- if it is a quoted string
-
newNode($op, @params)
- create a new operator node. @params is a variable-length list of parameters, left to right. $op is a reference to the operator hash in the \@opers list.
These functions should throw Error::Simple in the event of errors.
Foswiki::Infix::Node is such a class, ripe for subclassing.
The remaining parameters are named, and specify options that affect the
behaviour of the parser:
-
words=>qr//
- should be an RE specifying legal words (unquoted terminals that are not operators i.e. names and numbers). By default this is \w+
. It's ok if operator names match this RE; operators always have precedence over names.
-
numbers=>qr//
- should be an RE specifying legal numbers (unquoted terminals that are not operators or words). By default this is qr/[+-]?(?:\d+\.\d+|\d+\.|\.\d+|\d+)(?:[eE][+-]?\d+)?/
, which matches integers and floating-point numbers. Number matching always takes precedence over word matching (i.e. "1xy" will be parsed as a number followed by a word. A typical usage of this option is when you only want to recognise integers, in which case you would set this to numbers => qr/\d+/
.
Strings should always be surrounded by 'single-quotes'. Single quotes in values may
be escaped using backslash (\).
ObjectMethod
addOperator($oper)
Add an operator to the parser.
$oper
is an object that implements the
Foswiki::Infix::OP interface.
ObjectMethod
parse($string) → $parseTree
Parses
$string
, calling
newLeaf
and
newNode
in the client class
as necessary to create a parse tree. Returns the result of calling
newNode
on the root of the parse.
Throws
Foswiki::Infix::Error in the event of parse errors.
ObjectMethod
onCloseExpr($@opands)
Designed to be overridden by subclasses that need to perform an action on the
operand stack (such as pushing) when a sub-expression is closed. Also called
when the root expression is closed. The default is a no-op.