The Book

Class: Parser

BNF~ Parser

Wraps a method parser.parse() which recognizes input and calls on an observer, if any. Unlike grammar.parser().parse(), here input can be presented in pieces, i.e., the method throws true if it should be called with more input.

new Parser(grammar [, skip])

Creates a parser; see parser() factory method.

Parameters:
Name Type Argument Description
grammar module:BNF~Grammar

represents grammar and states.
skip RegExp <optional>

a pattern to define ignorable character sequences, by default white space, must not accept empty input, must not use d, g, or y flag, should not be anchored, should use (:? )rather than ( ) for grouping.
Properties:
Name Type Argument Description
scanner module:Base~Scanner <nullable>

tokenizes input.
parsing boolean

true while recognition is in progress.
building boolean

true if recognition calls build().
stack Array.<number>

stack of state numbers.
state module:BNF~State

current state.
values Array.<object>

parallels state stack, nested lists or action results.
input function | Array.<module:Base~Tuple> | boolean <nullable>

provides input as tuples. null, an empty array, or a null array element act as $eof. false is set to request more input.
current module:Base~Tuple <nullable>

current input tuple, if any.
tuples Array.<module:Base~Tuple>

available tuples.
index number

index of next tuple.
grammar module:BNF~Grammar

represents the grammar and states, counts errors; concurrent recognition will trash error counting.
actions Object <nullable>

maps rule names to action methods during recognition.
Source:

Extends

Methods

act(name, result)

Calls an action method. Checks argument count unless grammar.config.noargs is set or the method expects no arguments, i.e., has a rest parameter.

Parameters:
Name Type Description
name string

rule name to match.
result Array

list of arguments.
Inherited From:
Overrides:
Source:
Returns:

action method result or unchanged result.

<private> build(tuple, verb, info)

List builder, part of parse(). Manages the value stack to collect nested lists of all terminal values and applies action methods matching rule names which can restructure the list of values collected for a rule.

If the grammar is created from an EBNF grammar the generated rules $-#: $-# other; and $-#: ; have implicit actions to support transparency for actions.

An action should throw an Error to abort recognition or a string to report an error and return null as result.

verb effect
'shift' pushes the tuple's terminal's value onto the value stack; returns null.
'reduce' pops one value per symbol, presents the list to an action function if any; returns the list or the result.
'goto' the result of the preceding 'reduce' is on top of the value stack; returns null.
'accept' returns the top-level value.
'error' if there is no info pops one value and returns null.
Parameters:
Name Type Description
tuple module:Base~Tuple

current input.
verb string

'shift', 'reduce', 'goto', 'accept', or 'error'.
info module:BNF~Rule | module:Base~T | number | string

a reference to the relevant rule, terminal, or state number, or an error message.
Source:
Throws:

with an error message to abort recognition.

Type
Error
Returns:

anything on success.

Type
object

call(target, method, args)

Checks if argument and parameter count of a method match unless the method expects no parameters, or has a rest parameter or grammar.config.noargs is true.

Parameters:
Name Type Argument Description
target object

to apply method to.
method function

to check.
args Object <repeatable>

arguments to pass.
Inherited From:
Overrides:
Source:
Returns:

method result.

Type
Object
Example

super.method(arg1, .. argn) 

this.parser.call(this, super.method, arg1, .. argn)

error(s)

Displays a message; lets grammar count it as an error.

Parameters:
Name Type Argument Description
s Array.<object> <repeatable>

message, to be displayed; prefixed by .current and joined by blanks.
Source:
Returns:

the message.

Type
string

<private> next()

Part of parse(). Sets .current to a new tuple, but not past $eof.

Source:
Throws:

true to ask for more input.

<private> observe(tuple, verb, info)

Recognition observer, part of parse(). Calls build() to create a result, if any; calls trace() if configured; reports info from an error message, if any,

Parameters:
Name Type Description
tuple module:Base~Tuple

current input.
verb string

of message.
info module:BNF~Rule | number | string

of message.
Source:
Returns:

the result.

Type
Object

parse(input [, actions], arg)

Parses (some more) input. actions can only be supplied with the first input; however, the function is serially reusable. Resets and reports .errors for the grammar.

Parameters:
Name Type Argument Description
input string | Array.<module:Base~Tuple> | function <nullable>

a string is scanned into tuples with null appended as end of input; can be a function which returns an array of tuples. null, an empty array, or a null array element act like a tuple containing $eof.
actions function | Object <optional>

a function is assumed to be a class and a singleton is created with this as constructor argument. The object maps rule names to action methods.
arg Object <repeatable>

used as further constructor arguments.
Overrides:
Source:
Throws:

true for more input, Error or error message otherwise — terminates one recognition.

Type
boolean | Error | string
Returns:

result from observer, if any; ends one recognition.

Type
Object

<private> process(tuple)

Part of parse(). processes an expected input: sends message to observe() and handles the state stack and the result, if any.

Parameters:
Name Type Description
tuple module:Base~Tuple

to be processed.
Source:
Throws:

fatal error message or [ result ] if accept message.

Type
string | Array.<Object>
Returns:

true if tuple is consumed (shift), false if not (reduce).

Type
boolean

<private> recover()

Part of parse(). Attempts error recovery within the current input sequence. Sends one 'error' with an error message, works on input and stack until a shift $error and shift current are done. Sends 'error' with null message every time the stack is popped. Returns when current was consumed to resume normal processing.

Source:
Throws:

  • true to ask for more input, i.e., abandons recovery.

  • [ result ] for $accept.

  • 'irrecoverable error' if the stack is empty.

toString()

Displays the current state stack and value stack, if any.

Source:
Returns:
Type
string

<private> trace(tuple, verb, info, the)

Formats and displays trace, part of parse().

Parameters:
Name Type Description
tuple module:Base~Tuple

current input.
verb string

of message.
info module:BNF~Rule | number | string

of message.
the Object

result.
Source: