This is Parsing.info, produced by Macaulay2, version 1.26.06

Parsing -- a framework for building parsers
*******************************************

Description
===========

See Parsing, is a package the provides a framework for building parsers.
It introduces Parser, a type of function that parses a sequence
of tokens, and Analyzer, a type of function that accepts input
for the parser in its original form and separates it into a stream of tokens.
A parser can be combined with an analyzer: see Parser _colon_ Analyzer,
to produce a complete system for accepting input and
parsing it.

See the package Classic, for a good example of  the use of
this framework.

+-----------------------------------------------------+
|i1 : (ZZParser : charAnalyzer) "-123"                |
|                                                     |
|o1 = -123                                            |
+-----------------------------------------------------+
|i2 : (constParser "abc" : nonspaceAnalyzer) " a b c "|
|                                                     |
|o2 = abc                                             |
+-----------------------------------------------------+

Author
======

  * Daniel R. Grayson (see http://www.math.uiuc.edu/~dan/ ) <dan@math.uiuc.edu>

Version
=======

This documentation describes version 1.0 of Parsing, released June, 2006.

Citation
========

If you have used this package in your research, please cite it as follows:

+-----------------------------------------------------------------------------+
|@misc{ParsingSource,                                                         |
|  title = {{Parsing: a framework for creating recursive                      |
|  author = {Daniel R. Grayson},                                              |
|  howpublished = {A \emph{Macaulay2} package available                       |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2                      |
|}                                                                            |
|-----------------------------------------------------------------------------|
| descent parsers. Version~1.0}},                                             |
|                                                                             |
|at                                                                           |
|/Macaulay2/packages}}                                                        |
+-----------------------------------------------------------------------------+

Exports
=======

  * Types
      * Analyzer -- the class of all lexical analyzers
      * Parser -- the class of all parsers
  * Functions and commands
      * andP -- parser conjunction
      * charAnalyzer -- a lexical analyzer that provides
        characters from a string one at a time
      * constParser -- produce a parser that accepts a
        fixed string, one character at a time
      * deadParser -- a parser which accepts no tokens and
        is not in a terminal state
      * futureParser -- forward reference to a parser not
        defined yet
      * letterParser -- a parser that accepts a single
        letter and returns it
      * NNParser -- a parser that accepts (and returns) a
        natural number, one character at a time
      * nonspaceAnalyzer -- a lexical analyzer that
        provides non-white-space characters from a string one at a time
      * nullParser -- a terminal parser that returns the
        value nil
      * optionalSignParser -- a parser that accepts
        an optional plus sign or minus sign
      * optP -- making a parser optional
      * orP -- parsing alternatives
      * QQParser -- a parser that accepts (and returns) a
        rational number, one character at a time
      * terminalParser -- produce a parser in a terminal
        state
      * ZZParser -- a parser that accepts (and returns) an
        integer, one character at a time
  * Methods
      * * Parser -- repetition of a parser
      * + Parser -- repetition of a parser at least once
      * "Parser @ Parser" -- see andP, -- parser conjunction
      * "Parser @ String" -- see andP, -- parser conjunction
      * "String @ Parser" -- see andP, -- parser conjunction
      * Function % Parser -- transform the value
        returned by a parser
      * "Parser | Parser" -- see orP, -- parsing alternatives
      * "Parser | String" -- see orP, -- parsing alternatives
      * "String | Parser" -- see orP, -- parsing alternatives
      * Parser _colon_ Analyzer -- combine a parser
        with a lexical analyzer to make a complete system
  * Symbols
      * nil -- a symbol a parser may return to indicate acceptance
        of the empty string of tokens

For the programmer
==================

The object Parsing, is a package (Macaulay2Doc),
defined in Parsing.m2.

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:188:0.

Analyzer -- the class of all lexical analyzers
**********************************************

Description
===========

A function that accepts input in its original form and separates it into
tokens, will be called a lexical analyzer. These analyzers are
functional: call one with the original input, and it returns a function of 0
arguments (with changeable internal state) that keeps returning tokens each
time it is called until none are left. Actually, the analyzer is to return a
pair: (pos,token), where pos is a string indicating the position where token
was found in the input. A position will be a sort of thing which can be
converted to string with toString (Macaulay2Doc), (for printing
error messages) and can be sorted.

+-------------------------------------+
|i1 : instance(charAnalyzer, Analyzer)|
|                                     |
|o1 = true                            |
+-------------------------------------+
|i2 : a = charAnalyzer "ab";          |
+-------------------------------------+
|i3 : a()                             |
|                                     |
|o3 = (0, a)                          |
|                                     |
|o3 : Sequence                        |
+-------------------------------------+
|i4 : a()                             |
|                                     |
|o4 = (1, b)                          |
|                                     |
|o4 : Sequence                        |
+-------------------------------------+
|i5 : a() === null                    |
|                                     |
|o5 = true                            |
+-------------------------------------+

Methods that use a lexical analyzer:
====================================

  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

Protected objects of class Analyzer:
====================================

  * charAnalyzer -- a lexical analyzer that provides
    characters from a string one at a time
  * nonspaceAnalyzer -- a lexical analyzer that
    provides non-white-space characters from a string one at a time

For the programmer
==================

The object Analyzer, is a self initializing type (Macaulay2Doc),
with ancestor classes
FunctionClosure (Macaulay2Doc), < Function (Macaulay2Doc)
< Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:251:0.

charAnalyzer -- a lexical analyzer that provides characters from a string one at a time
***************************************************************************************

Description
===========

+---------------------------------------------+
|i1 : a = charAnalyzer "abc"                  |
|                                             |
|o1 = a                                       |
|                                             |
|o1 : FunctionClosure                         |
+---------------------------------------------+
|i2 : peek a()                                |
|                                             |
|o2 = (0, "a")                                |
+---------------------------------------------+
|i3 : peek a()                                |
|                                             |
|o3 = (1, "b")                                |
+---------------------------------------------+
|i4 : peek a()                                |
|                                             |
|o4 = (2, "c")                                |
+---------------------------------------------+
|i5 : peek a()                                |
|                                             |
|o5 = null                                    |
+---------------------------------------------+
|i6 : (constParser "abc" : charAnalyzer) "abc"|
|                                             |
|o6 = abc                                     |
+---------------------------------------------+

See also
========

  * constParser -- produce a parser that accepts a fixed
    string, one character at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

For the programmer
==================

The object charAnalyzer, is a lexical analyzer.

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:264:0.

nonspaceAnalyzer -- a lexical analyzer that provides non-white-space characters from a string one at a time
***********************************************************************************************************

Description
===========

+-----------------------------------------------------+
|i1 : a = nonspaceAnalyzer " a b c "                  |
|                                                     |
|o1 = a                                               |
|                                                     |
|o1 : FunctionClosure                                 |
+-----------------------------------------------------+
|i2 : peek a()                                        |
|                                                     |
|o2 = (1, "a")                                        |
+-----------------------------------------------------+
|i3 : peek a()                                        |
|                                                     |
|o3 = (3, "b")                                        |
+-----------------------------------------------------+
|i4 : peek a()                                        |
|                                                     |
|o4 = (5, "c")                                        |
+-----------------------------------------------------+
|i5 : peek a()                                        |
|                                                     |
|o5 = null                                            |
+-----------------------------------------------------+
|i6 : (constParser "abc" : nonspaceAnalyzer) " a b c "|
|                                                     |
|o6 = abc                                             |
+-----------------------------------------------------+

See also
========

  * constParser -- produce a parser that accepts a fixed
    string, one character at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

For the programmer
==================

The object nonspaceAnalyzer, is a lexical analyzer.

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:291:0.

Parser -- the class of all parsers
**********************************

Description
===========

A parser is a type of function that parses a sequence of tokens.  Tokens can be
anything except null (Macaulay2Doc). A parser p is called
repeatedly, like this: p t, one token at a time.  The return value that
indicates acceptance of the input token is a new parser, which replaces the
old, and is ready to accept the next token; the original parser p should not
change its internal state.  The return value that indicates rejection of the
input token is null (Macaulay2Doc).  Rejection may be interpreted
as a syntax error.

When the input stream is exhausted, we call p one more time like this: p null.
The return value is null (Macaulay2Doc), if the parser is not in a
terminal state.  Otherwise the return value is the parsed (and possibly
evaluated) result.

+---------------------------+
|i1 : p = constParser "abc";|
+---------------------------+
|i2 : instance(p, Parser)   |
|                           |
|o2 = true                  |
+---------------------------+
|i3 : q = p "a";            |
+---------------------------+
|i4 : instance(q, Parser)   |
|                           |
|o4 = true                  |
+---------------------------+
|i5 : (((q "b") "c") null)  |
|                           |
|o5 = abc                   |
+---------------------------+

simple parsers

making new parsers from old ones

Methods that use a parser:
==========================

  * * Parser -- repetition of a parser
  * + Parser -- repetition of a parser at least once
  * "Parser @ Parser" -- see andP, -- parser conjunction
  * "Parser @ String" -- see andP, -- parser conjunction
  * "String @ Parser" -- see andP, -- parser conjunction
  * Function % Parser -- transform the value returned
    by a parser
  * "Parser | Parser" -- see orP, -- parsing alternatives
  * "Parser | String" -- see orP, -- parsing alternatives
  * "String | Parser" -- see orP, -- parsing alternatives
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

Protected objects of class Parser:
==================================

  * deadParser -- a parser which accepts no tokens and is
    not in a terminal state
  * letterParser -- a parser that accepts a single letter
    and returns it
  * NNParser -- a parser that accepts (and returns) a natural
    number, one character at a time
  * nullParser -- a terminal parser that returns the value
    nil
  * optionalSignParser -- a parser that accepts an
    optional plus sign or minus sign
  * QQParser -- a parser that accepts (and returns) a rational
    number, one character at a time
  * ZZParser -- a parser that accepts (and returns) an
    integer, one character at a time

For the programmer
==================

The object Parser, is a self initializing type (Macaulay2Doc),
with ancestor classes
FunctionClosure (Macaulay2Doc), < Function (Macaulay2Doc)
< Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:229:0.

deadParser -- a parser which accepts no tokens and is not in a terminal state
*****************************************************************************

Description
===========

+-------------------------+
|i1 : peek deadParser "a" |
|                         |
|o1 = null                |
+-------------------------+
|i2 : peek deadParser null|
|                         |
|o2 = null                |
+-------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:57:21-57:30: --source code:
deadParser = Parser (c -> null)

For the programmer
==================

The object deadParser, is a parser.

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:309:0.

terminalParser -- produce a parser in a terminal state
******************************************************

  * Usage:
        terminalParser v
  * Inputs:
      * v
  * Outputs:
      * a parser in a terminal state with parsed value v

Description
===========

+-------------------------+
|i1 : p = terminalParser x|
|                         |
|o1 = p                   |
|                         |
|o1 : Parser              |
+-------------------------+
|i2 : p "a"               |
+-------------------------+
|i3 : p null              |
|                         |
|o3 = x                   |
|                         |
|o3 : Symbol              |
+-------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:59:17-59:69: --source code:
terminalParser = val -> new Parser from (c -> if c === null then val)

For the programmer
==================

The object terminalParser, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:322:0.

nullParser -- a terminal parser that returns the value nil
**********************************************************

Description
===========

+----------------------------+
|i1 : nullParser null        |
|                            |
|o1 = nil                    |
|                            |
|o1 : Symbol                 |
+----------------------------+
|i2 : nullParser "x" === null|
|                            |
|o2 = true                   |
+----------------------------+
|i3 : nullParser null === nil|
|                            |
|o3 = true                   |
+----------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:59:41-59:68: --source code:
terminalParser = val -> new Parser from (c -> if c === null then val)
| symbol  class   value  location of symbol
| ------  -----   -----  ------------------
| val     Symbol  nil    ../../../../../Macaulay2/packages/Parsing.m2:59:17-59:
-------------------------------------------------------------------------------

20

See also
========

  * nil -- a symbol a parser may return to indicate acceptance of
    the empty string of tokens

For the programmer
==================

The object nullParser, is a parser.

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:333:0.

futureParser -- forward reference to a parser not defined yet
*************************************************************

  * Usage:
        futureParser p
  * Inputs:
      * p, a symbol (Macaulay2Doc),
  * Outputs:
      * a parser, a parser that will pass its input to the value
        of the symbol p at that time

Description
===========

This function makes recursive parsers possible.

+--------------------------+
|i1 : p = futureParser q   |
|                          |
|o1 = p                    |
|                          |
|o1 : Parser               |
+--------------------------+
|i2 : m = p : charAnalyzer |
|                          |
|o2 = m                    |
|                          |
|o2 : FunctionClosure      |
+--------------------------+
|i3 : q = constParser "abc"|
|                          |
|o3 = q                    |
|                          |
|o3 : Parser               |
+--------------------------+
|i4 : m "abc"              |
|                          |
|o4 = abc                  |
+--------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:65:15-65:76: --source code:
futureParser = parserSymbol -> new Parser from (c -> (value parserSymbol) c)

For the programmer
==================

The object futureParser, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:358:0.

letterParser -- a parser that accepts a single letter and returns it
********************************************************************

Description
===========

+-------------------------+
|i1 : p = letterParser "a"|
|                         |
|o1 = p                   |
|                         |
|o1 : Parser              |
+-------------------------+
|i2 : p "b"               |
+-------------------------+
|i3 : p null              |
|                         |
|o3 = a                   |
+-------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:63:23-63:88: --source code:
letterParser = Parser (c -> if alpha#?c then new Parser from (b -> if b ===
-------------------------------------------------------------------------------
null then c))

For the programmer
==================

The object letterParser, is a parser.

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:343:0.

constParser -- produce a parser that accepts a fixed string, one character at a time
************************************************************************************

  * Usage:
        constParser s
  * Inputs:
      * s, a string (Macaulay2Doc),
  * Outputs:
      * a parser, a parser that accepts (and returns) the string
        s, one character at a time

Description
===========

+------------------------------------------------------------------------+
|i1 : constParser "abc"                                                  |
|                                                                        |
|o1 = Parser[../../../../../Macaulay2/packages/Parsing.m2:148:48-148:149]|
|                                                                        |
|o1 : Parser                                                             |
+------------------------------------------------------------------------+
|i2 : oo "a"                                                             |
|                                                                        |
|o2 = Parser[../../../../../Macaulay2/packages/Parsing.m2:148:48-148:149]|
|                                                                        |
|o2 : Parser                                                             |
+------------------------------------------------------------------------+
|i3 : oo "a"                                                             |
+------------------------------------------------------------------------+
|i4 : ooo "b"                                                            |
|                                                                        |
|o4 = Parser[../../../../../Macaulay2/packages/Parsing.m2:148:48-148:149]|
|                                                                        |
|o4 : Parser                                                             |
+------------------------------------------------------------------------+
|i5 : oo "c"                                                             |
|                                                                        |
|o5 = Parser[../../../../../Macaulay2/packages/Parsing.m2:148:48-148:149]|
|                                                                        |
|o5 : Parser                                                             |
+------------------------------------------------------------------------+
|i6 : oo null                                                            |
|                                                                        |
|o6 = abc                                                                |
+------------------------------------------------------------------------+
|i7 : (constParser "abc" : charAnalyzer) "abc"                           |
|                                                                        |
|o7 = abc                                                                |
+------------------------------------------------------------------------+

See also
========

  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

For the programmer
==================

The object constParser, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:464:0.

optionalSignParser -- a parser that accepts an optional plus sign or minus sign
*******************************************************************************

Description
===========

The return value is either 1 or -1, depending on the indicated sign.

+-------------------------------------------------------------------+
|i1 : (optionalSignParser @ constParser "abc" : charAnalyzer) "abc" |
|                                                                   |
|o1 = (1, abc)                                                      |
|                                                                   |
|o1 : Sequence                                                      |
+-------------------------------------------------------------------+
|i2 : (optionalSignParser @ constParser "abc" : charAnalyzer) "+abc"|
|                                                                   |
|o2 = (1, abc)                                                      |
|                                                                   |
|o2 : Sequence                                                      |
+-------------------------------------------------------------------+
|i3 : (optionalSignParser @ constParser "abc" : charAnalyzer) "-abc"|
|                                                                   |
|o3 = (-1, abc)                                                     |
|                                                                   |
|o3 : Sequence                                                      |
+-------------------------------------------------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:157:28-157:135: --source code:
optionalSignParser = Parser(c -> if c === null then 1 else if c === "-" then
-------------------------------------------------------------------------------
terminalParser(-1) else if c === "+" then terminalParser 1)

See also
========

  * Parser @ Parser -- parser conjunction
  * constParser -- produce a parser that accepts a fixed
    string, one character at a time
  * charAnalyzer -- a lexical analyzer that provides
    characters from a string one at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

For the programmer
==================

The object optionalSignParser, is a parser.

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:478:0.

NNParser -- a parser that accepts (and returns) a natural number, one character at a time
*****************************************************************************************

Description
===========

+------------------------------------------------------------------------+
|i1 : NNParser "1"                                                       |
|                                                                        |
|o1 = Parser[../../../../../Macaulay2/packages/Parsing.m2:152:37-152:103]|
|                                                                        |
|o1 : Parser                                                             |
+------------------------------------------------------------------------+
|i2 : oo null                                                            |
|                                                                        |
|o2 = 1                                                                  |
+------------------------------------------------------------------------+
|i3 : ooo "2"                                                            |
|                                                                        |
|o3 = Parser[../../../../../Macaulay2/packages/Parsing.m2:152:37-152:103]|
|                                                                        |
|o3 : Parser                                                             |
+------------------------------------------------------------------------+
|i4 : oo null                                                            |
|                                                                        |
|o4 = 12                                                                 |
+------------------------------------------------------------------------+
|i5 : ooo "3"                                                            |
|                                                                        |
|o5 = Parser[../../../../../Macaulay2/packages/Parsing.m2:152:37-152:103]|
|                                                                        |
|o5 : Parser                                                             |
+------------------------------------------------------------------------+
|i6 : oo null                                                            |
|                                                                        |
|o6 = 123                                                                |
+------------------------------------------------------------------------+
|i7 : (NNParser : charAnalyzer) "123456789123456789123456789"            |
|                                                                        |
|o7 = 123456789123456789123456789                                        |
+------------------------------------------------------------------------+
|i8 : class oo                                                           |
|                                                                        |
|o8 = ZZ                                                                 |
|                                                                        |
|o8 : Ring                                                               |
+------------------------------------------------------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:153:27-153:58: --source code:
          new Parser from (c -> if digit#?c then f digit#c)
| symbol  class            value
| ------  -----            -----
| f       FunctionClosure  FunctionClosure[../../../../../Macaulay2/packages/
-------------------------------------------------------------------------------
       location of symbol
       ------------------
Pars.  ../../../../../Macaulay2/packages/Parsing.m2:152:10-152:11

See also
========

  * charAnalyzer -- a lexical analyzer that provides
    characters from a string one at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

For the programmer
==================

The object NNParser, is a parser.

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:494:0.

ZZParser -- a parser that accepts (and returns) an integer, one character at a time
***********************************************************************************

Description
===========

+-------------------------------------------+
|i1 : (ZZParser : charAnalyzer) "123456789" |
|                                           |
|o1 = 123456789                             |
+-------------------------------------------+
|i2 : (ZZParser : charAnalyzer) "-123456789"|
|                                           |
|o2 = -123456789                            |
+-------------------------------------------+
|i3 : class oo                              |
|                                           |
|o3 = ZZ                                    |
|                                           |
|o3 : Ring                                  |
+-------------------------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:94:50-94:123: --source code:
Function % Parser := (fun,p) -> new Parser from ( c -> if (p' := p c) =!= null
| symbol  class             value
| ------  -----             -----
| p       Parser            Parser[../../../../../Macaulay2/packages/Parsing.m2
| fun     CompiledFunction  times
-------------------------------------------------------------------------------
then if c === null then fun p' else fun % p' )
      location of symbol
      ------------------
:12.  ../../../../../Macaulay2/packages/Parsing.m2:94:26-94:27
      ../../../../../Macaulay2/packages/Parsing.m2:94:22-94:25

See also
========

  * charAnalyzer -- a lexical analyzer that provides
    characters from a string one at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

For the programmer
==================

The object ZZParser, is a parser.

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:505:0.

QQParser -- a parser that accepts (and returns) a rational number, one character at a time
******************************************************************************************

Description
===========

The denominator must be present.

+-------------------------------------------------+
|i1 : (QQParser : charAnalyzer) "-123456789/54321"|
|                                                 |
|       41152263                                  |
|o1 = - --------                                  |
|         18107                                   |
|                                                 |
|o1 : QQ                                          |
+-------------------------------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:94:50-94:123: --source
Function % Parser := (fun,p) -> new Parser from ( c -> if (p' := p c
| symbol  class            value
| ------  -----            -----
| p       Parser           Parser[../../../../../Macaulay2/packages/
| fun     FunctionClosure  FunctionClosure[../../../../../Macaulay2/
-------------------------------------------------------------------------------
code:
) =!= null then if c === null then fun p' else fun % p' )
                location of symbol
                ------------------
Parsing.m2:10.  ../../../../../Macaulay2/packages/Parsing.m2:94:26-94:27
packages/Pars.  ../../../../../Macaulay2/packages/Parsing.m2:94:22-94:25

See also
========

  * charAnalyzer -- a lexical analyzer that provides
    characters from a string one at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

For the programmer
==================

The object QQParser, is a parser.

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:515:0.

optP -- making a parser optional
********************************

  * Usage:
        optP p
  * Inputs:
      * p, a parser,
  * Outputs:
      * a parser, a parser that accepts tokens accepted by p and
        returns the value returned by p, or accepts the empty sequence of
        tokens and returns the symbol nil.  It prefers to do the former.

Description
===========

After the first token, the parser is no slower than p would have been.

+--------------------------------------------------+
|i1 : (optP constParser "abc" : charAnalyzer) "abc"|
|                                                  |
|o1 = abc                                          |
+--------------------------------------------------+
|i2 : (optP constParser "abc" : charAnalyzer) ""   |
|                                                  |
|o2 = nil                                          |
|                                                  |
|o2 : Symbol                                       |
+--------------------------------------------------+

See also
========

  * constParser -- produce a parser that accepts a fixed
    string, one character at a time
  * charAnalyzer -- a lexical analyzer that provides
    characters from a string one at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

For the programmer
==================

The object optP, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:529:0.

orP -- parsing alternatives
***************************

  * Usage:
        r = orP(p,q,...)
  * Inputs:
      * (p,q,...), a sequence of parsers (of type Parser)
  * Outputs:
      * r, a parser, a parser that accepts any sequence of
        tokens acceptable to one of the parsers p,q,...

Description
===========

An abbreviation for orP(p,q) is p|q.

In case of ambiguity, the value returned by the left-most accepting parser is
provided.

If one of the arguments is a string (Macaulay2Doc), then
constParser, is used to convert it into a parser.

In an efficient grammar, the first token presented to r will be acceptable to
at most one of the input parsers, and then the parser returned by r will be the
parser returned by the single accepting input parser.

+-----------------------------------------------------------------+
|i1 : (constParser "abc" | constParser "def" : charAnalyzer) "abc"|
|                                                                 |
|o1 = abc                                                         |
+-----------------------------------------------------------------+
|i2 : (constParser "abc" | constParser "def" : charAnalyzer) "def"|
|                                                                 |
|o2 = def                                                         |
+-----------------------------------------------------------------+
|i3 : (constParser "abc" | "def" : charAnalyzer) "def"            |
|                                                                 |
|o3 = def                                                         |
+-----------------------------------------------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:84:19-89:49: --source code:
Parser | Parser := (p,q) -> new Parser from ( c -> (
          p' := p c;
          q' := q c;
          if p' === null then q'
          else if q' === null then p'
          else if c === null then p' else p'|q'))

See also
========

  * constParser -- produce a parser that accepts a fixed
    string, one character at a time
  * charAnalyzer -- a lexical analyzer that provides
    characters from a string one at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

For the programmer
==================

The object orP, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:385:0.

andP -- parser conjunction
**************************

  * Usage:
        r = andP(p,q,...)
  * Inputs:
      * (p,q,...), a sequence of parsers (of type Parser)
  * Outputs:
      * r, a parser, a parser that accepts as many tokens as p
        will accept, then as many as q will accept, and so on.  The return
        value is the sequence of values returned by each of the input parsers.

Description
===========

An abbreviation for andP(p,q) is p@q.

If one of the arguments is a string (Macaulay2Doc), then
constParser, is used to convert it into a parser.

+--------------------------------------------------------------------+
|i1 : (constParser "abc" @ constParser "def" : charAnalyzer) "abcdef"|
|                                                                    |
|o1 = (abc, def)                                                     |
|                                                                    |
|o1 : Sequence                                                       |
+--------------------------------------------------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:120:19-128:12: --source code:
Parser @ Parser := (p,q) -> new Parser from (
     c -> (
          if c =!= null then (
               if (p' := p c) =!= null
               then p' @ q
               else if (val1 := p null) =!= null then if (q' := q c) =!= null
               )
          else if (val1 = p null) =!= null and (val2 := q null) =!= null then
          ))
-------------------------------------------------------------------------------
then (val2 -> (val1,val2)) % q'

(val1,val2)

See also
========

  * constParser -- produce a parser that accepts a fixed
    string, one character at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

For the programmer
==================

The object andP, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:404:0.

* Parser -- repetition of a parser
**********************************

  * Operator: * (Macaulay2Doc),
  * Usage:
        *p
  * Inputs:
      * p, a parser,
  * Outputs:
      * a parser, a parser that will feed its tokens through p,
        and then when further tokens are not accepted, it will start over with
        a fresh copy of p.  The value returned is the sequence of values
        returned by each instance of p.

Description
===========

+-----------------------------------------------------+
|i1 : (* constParser "abc" : charAnalyzer) "abcabcabc"|
|                                                     |
|o1 = (abc, abc, abc)                                 |
|                                                     |
|o1 : Sequence                                        |
+-----------------------------------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:130:11-142:12
*Parser := p -> (
     f := (vals,current) -> new Parser from (c -> (
               if c === null then (
                    if current === null then vals
                    else if (val := current null) =!= null
                    )
               else (
                    if current === null then (f(vals,p)) c
                    else (
                         q := current c;
                         if q =!= null then return f(vals,
                         if (val = current null) =!= null
     ) ((),)
-------------------------------------------------------------------------------
: --source code:

 then append(vals,val)

q);
then (f(append(vals,val),)) c))))

See also
========

  * constParser -- produce a parser that accepts a fixed
    string, one character at a time
  * charAnalyzer -- a lexical analyzer that provides
    characters from a string one at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

Ways to use this method:
========================

  * * Parser -- repetition of a parser
-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:433:0.

+ Parser -- repetition of a parser at least once
************************************************

  * Operator: + (Macaulay2Doc),
  * Usage:
        +p
  * Inputs:
      * p, a parser,
  * Outputs:
      * a parser, a parser that will feed its tokens through p,
        and then when further tokens are not accepted, it will start over with
        a fresh copy of p.  The value returned is the sequence of values
        returned by each instance of p.

Description
===========

+-----------------------------------------------------+
|i1 : (+ constParser "abc" : charAnalyzer) "abcabcabc"|
|                                                     |
|o1 = (abc, abc, abc)                                 |
|                                                     |
|o1 : Sequence                                        |
+-----------------------------------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:144:11-144:32: --source code:
+Parser := p -> prepend % p @ *p

See also
========

  * constParser -- produce a parser that accepts a fixed
    string, one character at a time
  * charAnalyzer -- a lexical analyzer that provides
    characters from a string one at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

Ways to use this method:
========================

  * + Parser -- repetition of a parser at least once
-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:447:0.

Function % Parser -- transform the value returned by a parser
*************************************************************

  * Operator: % (Macaulay2Doc),
  * Usage:
        f % p
  * Inputs:
      * f, a function (Macaulay2Doc),
      * p, a parser,
  * Outputs:
      * a parser, a parser that feeds its tokens to p and
        filters the value returned by p through f

Description
===========

+-----------------------------------------------------------------------------+
|i1 : (* constParser "abc" : charAnalyzer) "abcabcabc"                        |
|                                                                             |
|o1 = (abc, abc, abc)                                                         |
|                                                                             |
|o1 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i2 : (concatenate % * constParser "abc" : charAnalyzer) "abcabcabc"          |
|                                                                             |
|o2 = abcabcabc                                                               |
+-----------------------------------------------------------------------------+
|i3 : (constParser "abc" : charAnalyzer) "abc"                                |
|                                                                             |
|o3 = abc                                                                     |
+-----------------------------------------------------------------------------+
|i4 : ((s -> concatenate("[",s,"]")) % constParser "abc" : charAnalyzer) "abc"|
|                                                                             |
|o4 = [abc]                                                                   |
+-----------------------------------------------------------------------------+

Code
====

../../../../../Macaulay2/packages/Parsing.m2:94:21-94:125: --source code:
Function % Parser := (fun,p) -> new Parser from ( c -> if (p' := p c) =!= null
-------------------------------------------------------------------------------
then if c === null then fun p' else fun % p' )

See also
========

  * constParser -- produce a parser that accepts a fixed
    string, one character at a time
  * charAnalyzer -- a lexical analyzer that provides
    characters from a string one at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

Ways to use this method:
========================

  * Function % Parser -- transform the value returned
    by a parser
-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:419:0.

Parser : Analyzer -- combine a parser with a lexical analyzer to make a complete system
***************************************************************************************

  * Operator: _colon_ (Macaulay2Doc),
  * Usage:
        m = p : a
  * Inputs:
      * p, a parser,
      * a, a lexical analyzer,
  * Outputs:
      * m, a function (Macaulay2Doc), a function that will
        provide its argument to a for lexical analysis and will send the
        resulting stream of tokens through p for parsing.  Appropriate error
        messages are printed as necessary.

Description
===========

+---------------------------------------------+
|i1 : (ZZParser : charAnalyzer) "123456789"   |
|                                             |
|o1 = 123456789                               |
+---------------------------------------------+
|i2 : (constParser "abc" : charAnalyzer) "abc"|
|                                             |
|o2 = abc                                     |
+---------------------------------------------+

See also
========

  * ZZParser -- a parser that accepts (and returns) an
    integer, one character at a time
  * constParser -- produce a parser that accepts a fixed
    string, one character at a time
  * charAnalyzer -- a lexical analyzer that provides
    characters from a string one at a time
  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system

Ways to use this method:
========================

  * Parser _colon_ Analyzer -- combine a parser
    with a lexical analyzer to make a complete system
-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:278:0.

nil -- a symbol a parser may return to indicate acceptance of the empty string of tokens
****************************************************************************************

Description
===========

+--------------------------------------------------+
|i1 : (optP constParser "abc" : charAnalyzer) ""   |
|                                                  |
|o1 = nil                                          |
|                                                  |
|o1 : Symbol                                       |
+--------------------------------------------------+
|i2 : (optP constParser "abc" : charAnalyzer) "abc"|
|                                                  |
|o2 = abc                                          |
+--------------------------------------------------+

See also
========

  * nullParser -- a terminal parser that returns the value
    nil

For the programmer
==================

The object nil, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Parsing.m2:300:0.