data/TWiki/TWikiInfixParserDotPm.txt,v
changeset 0 414e01d06fd5
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     1 head	1.1;
       
     2 access;
       
     3 symbols;
       
     4 locks; strict;
       
     5 comment	@# @;
       
     6 
       
     7 
       
     8 1.1
       
     9 date	2008.01.22.03.21.23;	author TWikiContributor;	state Exp;
       
    10 branches;
       
    11 next	;
       
    12 
       
    13 
       
    14 desc
       
    15 @buildrelease
       
    16 @
       
    17 
       
    18 
       
    19 1.1
       
    20 log
       
    21 @buildrelease
       
    22 @
       
    23 text
       
    24 @---+ Package =TWiki::Infix::Parser=
       
    25 
       
    26 A simple stack-based parser that parses infix expressions with nonary,
       
    27 unary and binary operators specified using an operator table.
       
    28 
       
    29 Escapes are supported in strings, using backslash.
       
    30 
       
    31 
       
    32 %TOC%
       
    33 
       
    34 ---++ new($client_class, \%options) -> parser object
       
    35 
       
    36 Creates a new infix parser. Operators must be added for it to be useful.
       
    37 
       
    38 The tokeniser matches tokens in the following order: operators,
       
    39 quotes (" and '), numbers, words, brackets. If you have any overlaps (e.g.
       
    40 an operator '<' and a bracket operator '<<') then the first choice
       
    41 will match.
       
    42 
       
    43 =$client_class= needs to be the _name_ of a _package_ that supports the
       
    44 following two functions:
       
    45    * =newLeaf($val, $type)= - create a terminal. $type will be:
       
    46       1 if the terminal matched the =words= specification (see below).
       
    47       2 if it is a number matched the =numbers= specification (see below)
       
    48       3 if it is a quoted string
       
    49    * =newNode($op, @@params) - create a new operator node. @@params
       
    50      is a variable-length list of parameters, left to right. $op
       
    51      is a reference to the operator hash in the \@@opers list.
       
    52 These functions should throw Error::Simple in the event of errors.
       
    53 TWiki::Infix::Node is such a class, ripe for subclassing.
       
    54 
       
    55 The remaining parameters are named, and specify options that affect the
       
    56 behaviour of the parser:
       
    57    1 =words=>qr//= - should be an RE specifying legal words (unquoted
       
    58      terminals that are not operators i.e. names and numbers). By default
       
    59      this is =\w+=.
       
    60      It's ok if operator names match this RE; operators always have precedence
       
    61      over atoms.
       
    62    2 =numbers=>qr//= - should be an RE specifying legal numbers (unquoted
       
    63      terminals that are not operators or words). By default
       
    64      this is =qr/[+-]?(?:\d+\.\d+|\d+\.|\.\d+|\d+)(?:[eE][+-]?\d+)?/=,
       
    65      which matches integers and floating-point numbers. Number
       
    66      matching always takes precedence over word matching (i.e. "1xy" will
       
    67      be parsed as a number followed by a word. A typical usage of this option
       
    68      is when you only want to recognise integers, in which case you would set
       
    69      this to =numbers => qr/\d+/=.
       
    70 
       
    71 
       
    72 ---++ ObjectMethod *addOperator* <tt>(%oper)</tt>
       
    73 Add an operator to the parser.
       
    74 
       
    75 =%oper= is a hash, containing the following fields:
       
    76    * =name= - operator string
       
    77    * =prec= - operator precedence, positive non-zero integer.
       
    78      Larger number => higher precedence.
       
    79    * =arity= - set to 1 if this operator is unary, 2 for binary. Arity 0
       
    80      is legal, should you ever need it.
       
    81    * =close= - used with bracket operators. =name= should be the open
       
    82      bracket string, and =close= the close bracket. The existance of =close=
       
    83      marks this as a bracket operator.
       
    84    * =casematters== - indicates that the parser should check case in the
       
    85      operator name (i.e. treat 'AND' and 'and' as different).
       
    86      By default operators are case insensitive. *Note* that operator
       
    87      names must be caselessly unique i.e. you can't define 'AND' and 'and'
       
    88      as different operators in the same parser. Does not affect the
       
    89      interpretation of non-operator terminals (names).
       
    90 Other fields in the hash can be used for other purposes; the parse tree
       
    91 generated by this parser will point to the hashes passed to this function.
       
    92 
       
    93 Field names in the hash starting with =InfixParser_= are reserved for use
       
    94 by the parser.
       
    95 
       
    96 
       
    97 
       
    98 ---++ ObjectMethod *parse* <tt>($string) -> $parseTree</tt>
       
    99 Parses =$string=, calling =newLeaf= and =newNode= in the client class
       
   100 as necessary to create a parse tree. Returns the result of calling =newNode=
       
   101 on the root of the parse.
       
   102 
       
   103 Throws TWiki::Infix::Error in the event of parse errors.
       
   104 
       
   105 
       
   106 @