.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Marpa::R2::NAIF::Grammar 3pm"
.TH Marpa::R2::NAIF::Grammar 3pm "2015-03-06" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Marpa::R2::NAIF::Grammar \- NAIF grammars
.SH "Synopsis"
.IX Header "Synopsis"
.Vb 10
\&    my $grammar = Marpa::R2::Grammar\->new(
\&        {   start   => \*(AqExpression\*(Aq,
\&            actions => \*(AqMy_Actions\*(Aq,
\&            default_action => \*(Aqfirst_arg\*(Aq,
\&            rules   => [
\&                { lhs => \*(AqExpression\*(Aq, rhs => [qw/Term/] },
\&                { lhs => \*(AqTerm\*(Aq, rhs => [qw/Factor/] },
\&                { lhs => \*(AqFactor\*(Aq, rhs => [qw/Number/] },
\&                { lhs => \*(AqTerm\*(Aq, rhs => [qw/Term Add Term/], action => \*(Aqdo_add\*(Aq },
\&                {   lhs    => \*(AqFactor\*(Aq,
\&                    rhs    => [qw/Factor Multiply Factor/],
\&                    action => \*(Aqdo_multiply\*(Aq
\&                },
\&            ],
\&        }
\&    );
\&
\&    $grammar\->precompute();
.Ve
.SH "Description"
.IX Header "Description"
This document describes grammars for Marpa's
named argument interface (\s-1NAIF\s0).
If you are a beginner,
or are not sure which interface you are interested in,
or do not know what the \s-1NAIF\s0 interfaces is,
you probably are looking for
the document on grammars for the \s-1SLIF\s0
interface.
.PP
To create a Marpa grammar object,
use the \f(CW\*(C`new\*(C'\fR method.
Rules and symbols may be specified when the grammar is created.
.PP
To change a Marpa grammar object,
use the \f(CW\*(C`set\*(C'\fR method.
New rules may be added until a grammar is precomputed.
.PP
A grammar cannot be used for parsing until it is precomputed.
To precompute a Marpa grammar object,
use the \f(CW\*(C`precompute\*(C'\fR method.
After precomputation,
no new rules may added and
most other changes are forbidden.
.SS "Symbol names"
.IX Subsection "Symbol names"
Marpa reserves, for its internal use, all symbol names
ending with one of these four symbols:
the right square bracket ("\f(CW\*(C`]\*(C'\fR\*(L"),
the right parenthesis (\*(R"\f(CW\*(C`)\*(C'\fR\*(L"),
the right angle bracket (\*(R"\f(CW\*(C`>\*(C'\fR\*(L"),
and the right curly bracket (\*(R"\f(CW\*(C`}\*(C'\fR").
Any other valid Perl string is an acceptable
symbol name.
.SS "Terminal symbols"
.IX Subsection "Terminal symbols"
Marpa defines a \fBterminal\fR as a symbol which is valid as an
input token symbol.
By default, the terminals are those symbols who do not
appear on the \s-1LHS\s0 of any rule.
.PP
Marpa will allow any non-nulling symbol to be a terminal,
even those which appear on the \s-1LHS\s0 of one or more rules.
To allow (or disallow) use of a symbol as a terminal,
the application can use
the \f(CW\*(C`terminals\*(C'\fR named argument,
and the \f(CW\*(C`terminal\*(C'\fR property.
An attempt to use a nulling symbol as a terminal
is a fatal error.
.SS "Sequence rules"
.IX Subsection "Sequence rules"
It is very common in a grammar for one symbol to produce a
repeating sequence.
Marpa allows a shorthand for this:
sequence rules.
The \s-1RHS\s0 of a sequence rule will be repeated,
as specified by the \f(CW\*(C`min\*(C'\fR rule property.
In sequence rules the \s-1RHS\s0 must always be one symbol
in length,
and that symbol may not be a nullable symbol.
.PP
A rule is a sequence rule if the \f(CW\*(C`min\*(C'\fR rule property is defined.
\&\f(CW\*(C`min\*(C'\fR can be 0 or 1, and specifies the minimum number of times
that the sequence is allowed to repeat.
As of this writing,
the maximum number of repetitions is always infinite.
.PP
.Vb 1
\&    { lhs => \*(Aqsequence\*(Aq, rhs => [\*(Aqitem\*(Aq], min => 0, action => \*(Aqdo_sequence\*(Aq }
.Ve
.PP
A \f(CW\*(C`min\*(C'\fR of zero indicates a sequence that repeats zero or more times.
This is the equivalent of using the star quantifier
("\f(CW\*(C`*\*(C'\fR") in the
standard regular expression notation.
.PP
.Vb 1
\&    { lhs => \*(Aqsequence\*(Aq, rhs => [\*(Aqitem\*(Aq], min => 1, action => \*(Aqdo_sequence\*(Aq }
.Ve
.PP
A \f(CW\*(C`min\*(C'\fR of one indicates a sequence that repeats one or more times.
This is the equivalent of using the plus quantifier
("\f(CW\*(C`+\*(C'\fR") in the
standard regular expression notation.
.PP
Sequences can have a separator, specified
with the \f(CW\*(C`separator\*(C'\fR rule property.
By default, separation is Perl-style:
trailing separators are allowed.
In "\f(CW\*(C`proper\*(C'\fR\*(L" separation,
a separator must actually separate
two sequence items
and therefore is not allowed
after the last item of a sequence.
If you prefer \*(R"\f(CW\*(C`proper\*(C'\fR" separation,
you can set
the \f(CW\*(C`proper\*(C'\fR rule property.
.PP
\fIAdvantages of sequence rules\fR
.IX Subsection "Advantages of sequence rules"
.PP
You are never forced to use sequence rules,
but it's usually better if you do.
When a sequence is written as a sequence rule,
Marpa optimizes it.
.PP
When a sequence is written using non-sequence
rules, the semantics typically wind up being spread
over two or three Perl closures.
The semantic action for a sequence rule
is a single Perl closure.
Putting the semantics into
a single Perl closure often results in
simpler and more
natural code.
See the section on sequences in the semantics
document.
.PP
\fICaveats\fR
.IX Subsection "Caveats"
.PP
Marpa throws an exception if you try to use a nullable symbol
as the right hand side of a sequence rule,
or as the separator for a sequence rule.
The ban on nullables in sequences only applies to sequences
when they are written using sequence rules.
Nothing prevents you from specifying a sequence of nullables using non-sequence rules.
But usually there is no good reason to do this,
and sequences of nullables can be highly ambiguous
which,
for efficiency reasons,
makes them
a good thing to avoid.
.PP
To keep things simple,
the right hand side of a sequence rule must be a single symbol.
Of course, applications will often want to repeat sequences of multiple symbols.
That is easy to do indirectly:
.PP
.Vb 2
\&    { lhs => \*(Aqsequence\*(Aq, rhs => [qw(item)], min => 0, action => \*(Aqdo_sequence\*(Aq },
\&    { lhs => \*(Aqitem\*(Aq, rhs => [qw(part1 part2)], action => \*(Aqdo_item\*(Aq },
.Ve
.SH "Constructor"
.IX Header "Constructor"
.SS "\fInew()\fP"
.IX Subsection "new()"
.Vb 10
\&    my $grammar = Marpa::R2::Grammar\->new(
\&        {   start   => \*(AqExpression\*(Aq,
\&            actions => \*(AqMy_Actions\*(Aq,
\&            default_action => \*(Aqfirst_arg\*(Aq,
\&            rules   => [
\&                { lhs => \*(AqExpression\*(Aq, rhs => [qw/Term/] },
\&                { lhs => \*(AqTerm\*(Aq, rhs => [qw/Factor/] },
\&                { lhs => \*(AqFactor\*(Aq, rhs => [qw/Number/] },
\&                { lhs => \*(AqTerm\*(Aq, rhs => [qw/Term Add Term/], action => \*(Aqdo_add\*(Aq },
\&                {   lhs    => \*(AqFactor\*(Aq,
\&                    rhs    => [qw/Factor Multiply Factor/],
\&                    action => \*(Aqdo_multiply\*(Aq
\&                },
\&            ],
\&        }
\&    );
.Ve
.PP
\&\f(CW\*(C`Marpa::R2::NAIF::Grammar::new\*(C'\fR
returns a new Marpa grammar object or throws an exception.
The arguments to
\&\f(CW\*(C`Marpa::R2::NAIF::Grammar::new\*(C'\fR are
references to hashes of named arguments.
In each key/value pair of this hash,
the hash key is the argument name
and the hash value is the value of
the named argument.
The available named arguments are described
below.
.SH "Mutators"
.IX Header "Mutators"
.SS "\fIprecompute()\fP"
.IX Subsection "precompute()"
.Vb 1
\&    $grammar\->precompute();
.Ve
.PP
The \f(CW\*(C`precompute\*(C'\fR method
compiles data structures that the recognizer will need.
It
returns the grammar object or throws an exception.
.SS "\fIset()\fP"
.IX Subsection "set()"
.Vb 1
\&    $grammar\->set( { trace_file_handle => $trace_fh } );
.Ve
.PP
The arguments to the
\&\f(CW\*(C`set\*(C'\fR method are
references to hashes of named arguments.
The available named arguments are described
below.
\&\f(CW\*(C`set\*(C'\fR either returns true or throws an exception.
.SH "Accessors"
.IX Header "Accessors"
.SS "\fIcheck_terminal()\fP"
.IX Subsection "check_terminal()"
Returns a Perl true when its argument is the name of a terminal symbol.
Otherwise, returns a Perl false.
Not often needed,
but a lexer may find this
the most convenient way to determine if a symbol is a terminal.
.SS "\fIrule()\fP"
.IX Subsection "rule()"
.Vb 1
\&    my ( $lhs, @rhs ) = $grammar\->rule($rule_id);
.Ve
.PP
Given a rule \s-1ID\s0 as its argument,
returns an array containing the symbols of the rule.
The \f(CW\*(C`rule()\*(C'\fR method
returns a Perl false if no rule with that rule \s-1ID\s0 exists.
If the rule \s-1ID\s0 exists,
the rule's \s-1LHS\s0 symbol is the first symbol in the array,
and rest of the array contains the rule's
\&\s-1RHS\s0 symbols in order.
Situations where
Rule \s-1ID\s0's are encountered include
callbacks and
use of the progress method.
.SS "\fIrule_ids()\fP"
.IX Subsection "rule_ids()"
.Vb 1
\&    my @rule_ids = $grammar\->rule_ids();
.Ve
.PP
Returns an array containing the valid rule IDs.
Situations where
Rule \s-1ID\s0's are encountered include
callbacks and
use of the progress method.
.SH "Trace accessors"
.IX Header "Trace accessors"
.SS "\fIshow_problems()\fP"
.IX Subsection "show_problems()"
.Vb 2
\&    print $grammar\->show_problems()
\&        or die "print failed: $ERRNO";
.Ve
.PP
Usually the application does not call this method
directly.
Returns a string describing any serious but non-fatal
problems a grammar had in the precomputation phase.
A serious problem is one that will prevent parsing.
Warnings are not serious problems in this sense.
If there were no serious problems, returns a string saying so.
This method is not useful before precomputation.
.PP
In Marpa, most serious grammar problems are
not immediately thrown as exceptions.
This is because there can be a number of serious
problems in a grammar, particularly one that is large
or in an early draft.
If each serious problem
caused an immediate exception,
the user would have to
fix them one at a time
\&\*(-- very tedious.
.PP
The recognizer
throws an exception
when the user attempts
to create a parse from
a grammar with serious problems.
When that happens,
the string returned by \f(CW\*(C`show_problems\*(C'\fR is part of the
error message.
.SS "\fIshow_rules()\fP"
.IX Subsection "show_rules()"
.Vb 2
\&    print $grammar\->show_rules()
\&        or die "print failed: $ERRNO";
.Ve
.PP
Returns a string listing the rules.
Each rule is shown with \fBcomments\fR which
indicate rule properties.
\&\f(CW\*(C`show_rules\*(C'\fR is useful in debugging grammars.
.PP
Marpa does extensive rewriting of its grammars,
and both the original rules and the rewritten rules
appear in the \f(CW\*(C`show_rules\*(C'\fR list.
When a rule is rewritten, the original rule is
often not used.
In that case, "\f(CW\*(C`!used\*(C'\fR\*(L" will be one of the comments
for the original rule.
The \*(R"\f(CW\*(C`!used\*(C'\fR\*(L" comment also marks rules not used
for reasons other than rewrites.
For example,
inaccessible and unproductive rules are also
marked \*(R"\f(CW\*(C`!used\*(C'\fR".
.PP
The "\f(CW\*(C`discard_sep"\*(C'\fR comment indicates that the rule
discards separators
This is only
relevant in sequence rules.
Other comments indicate
whether rules
were nullable, unproductive, inaccessible, or empty.
.SS "\fIshow_symbols()\fP"
.IX Subsection "show_symbols()"
.Vb 2
\&    print $grammar\->show_symbols()
\&        or die "print failed: $ERRNO";
.Ve
.PP
Returns a string listing the symbols, along with comments
indicating whether they were
terminal, nulling, nullable, unproductive or inaccessible.
Useful for debugging grammars.
.SH "Named arguments"
.IX Header "Named arguments"
.SS "action_object"
.IX Subsection "action_object"
The \f(CW\*(C`action_object\*(C'\fR named argument
specifies a Perl class name to be used
in resolving action names to Perl closures.
A \f(CW\*(C`new\*(C'\fR constructor must be defined
in the \f(CW\*(C`action_object\*(C'\fR package.
It will be used to create the per-parse-tree variables.
The per-parse-tree variable is passed
to rule evaluation closures,
as their first argument.
Details are in
the document on semantics.
.SS "actions"
.IX Subsection "actions"
.Vb 1
\&            actions => \*(AqMy_Actions\*(Aq,
.Ve
.PP
The \f(CW\*(C`actions\*(C'\fR named argument specifies
the Perl package that Marpa will use when resolving
action names to Perl closures.
If both an
\&\f(CW\*(C`actions\*(C'\fR named argument and an
\&\f(CW\*(C`action_object\*(C'\fR named argument are specified,
the
package from the \f(CW\*(C`actions\*(C'\fR named argument
is the only one used to resolve action names.
The \f(CW\*(C`actions\*(C'\fR package is treated only as a package,
and not as a class.
Any \f(CW\*(C`new\*(C'\fR constructor in the \f(CW\*(C`actions\*(C'\fR package is ignored.
Details are given in
the document on semantics.
.SS "default_action"
.IX Subsection "default_action"
.Vb 1
\&            default_action => \*(Aqfirst_arg\*(Aq,
.Ve
.PP
The \f(CW\*(C`default_action\*(C'\fR named argument specifies
the value action name
for rules without an \f(CW\*(C`action\*(C'\fR property.
Details are given in
the document on semantics.
.SS "default_empty_action"
.IX Subsection "default_empty_action"
The \f(CW\*(C`default_empty_action\*(C'\fR named argument specifies
the action for empty (zero length) rules
which have no action specified explicitly.
Details are given in
the document on semantics.
.SS "inaccessible_ok"
.IX Subsection "inaccessible_ok"
The value must be a reference to an array of symbol names.
By default, Marpa warns if a symbol is inaccessible, but
the warning is suppressed for any symbol named in the array.
Setting the \f(CW\*(C`inaccessible_ok\*(C'\fR named argument
after grammar precomputation is useless,
and itself results in a warning.
.PP
Inaccessible symbols are symbols which cannot be derived from
the start symbol, and which therefore can never be part of a
successful parse.
Inaccessible symbols often indicate errors in grammar
design.
But a user may have plans for these symbols,
may wish to keep them as notes,
or may simply wish to deal with them later.
.SS "infinite_action"
.IX Subsection "infinite_action"
Takes as its value a string specifying what Marpa
should do if it discovers that
its grammar is infinitely
ambiguous.
The value must be one of
"\f(CW\*(C`fatal\*(C'\fR\*(L",
\&\*(R"\f(CW\*(C`warn\*(C'\fR\*(L" or
\&\*(R"\f(CW\*(C`quiet\*(C'\fR".
A grammar is \fBinfinitely ambiguous\fR if there
is some input for which it produces
an endless number of parses.
.PP
If the value is "\f(CW\*(C`fatal\*(C'\fR",
Marpa throws an exception when it encounters
an infinitely ambiguous grammar.
This is the default and
will usually be what the user wants.
In most cases,
an infinitely ambiguous grammar is simply a mistake.
.PP
"\f(CW\*(C`quiet\*(C'\fR\*(L" indicates that
the user wants to allow
infinitely ambiguous grammars.
\&\*(R"\f(CW\*(C`warn\*(C'\fR" indicates that
the user wants to allow
infinitely ambiguous grammars, but
wants a warning message to be printed
to the trace file handle.
.SS "rules"
.IX Subsection "rules"
The value of the
\&\f(CW\*(C`rules\*(C'\fR named argument is a reference to an array of
\&\fBrule descriptors\fR.
The \f(CW\*(C`rules\*(C'\fR named argument may be specified multiple times,
adding new rules to the grammar each time.
New rules may be added until the grammar is precomputed.
The format of rule descriptors is explained
below.
.SS "source"
.IX Subsection "source"
The value of the
\&\f(CW\*(C`source\*(C'\fR named argument is a reference to string
that contains a description of the grammar in \s-1BNF\s0 format.
The format of this string is described in
the document on the \s-1BNF\s0 format.
The \f(CW\*(C`source\*(C'\fR named argument may only be specified once,
and it cannot be used together with the \f(CW\*(C`rules\*(C'\fR
named argument.
.SS "start"
.IX Subsection "start"
.Vb 1
\&    start => \*(AqExpression\*(Aq,
.Ve
.PP
The value of the \f(CW\*(C`start\*(C'\fR named argument must be a symbol name.
It will be used as the start symbol for the grammar.
The \f(CW\*(C`start\*(C'\fR named argument is required.
.SS "symbols"
.IX Subsection "symbols"
The value of the \f(CW\*(C`symbols\*(C'\fR named
arguments must be a reference to a hash.
In each key/value pair of this hash,
the hash key is the symbol property name
and the hash value is the
symbol descriptor.
Symbol descriptors are described below.
.PP
Note that the value of \f(CW\*(C`symbols\*(C'\fR named argument is a hash,
but the value of the \f(CW\*(C`rules\*(C'\fR named argument is an array.
This is because symbol names make convenient hash keys.
For rules, there is no equally natural choice for a hash key.
.SS "terminals"
.IX Subsection "terminals"
The value of the \f(CW\*(C`terminals\*(C'\fR named argument
must be a reference to an array of symbol names.
All the symbols in the array
will be allowed as terminals.
See
the discussion of terminals above.
.SS "trace_file_handle"
.IX Subsection "trace_file_handle"
The value is a file handle.
Trace output and warning messages
go to the trace file handle.
By default the trace file handle is \f(CW\*(C`STDERR\*(C'\fR.
.SS "unproductive_ok"
.IX Subsection "unproductive_ok"
The value must be a reference to an array of symbol names.
By default, Marpa warns if a symbol is unproductive, but
the warning is suppressed for any symbol named in the array.
Setting the \f(CW\*(C`unproductive_ok\*(C'\fR named argument
after grammar precomputation is useless,
and itself results in a warning.
.PP
Unproductive symbols are symbols which can never derive
a sentence.
(A sentence is a string of zero or more terminals.)
That means that unproductive symbols can never be part
of a successful parse.
Unproductive symbols often indicate errors in grammar
design.
But a user may have plans for these symbols,
may wish to keep them as notes,
or may simply wish to deal with them later.
.SS "warnings"
.IX Subsection "warnings"
The value is a boolean.
Warnings are written to the trace file handle.
By default, warnings are on.
Usually, an application will want to leave them on.
If warnings are turned off,
turning them back on
after grammar precomputation is useless,
and itself results in a warning.
.SH "Rule descriptors"
.IX Header "Rule descriptors"
.Vb 10
\&    rules => [
\&        { lhs => \*(AqExpression\*(Aq, rhs => [qw/Term/] },
\&        { lhs => \*(AqTerm\*(Aq,       rhs => [qw/Factor/] },
\&        { lhs => \*(AqFactor\*(Aq,     rhs => [qw/Number/] },
\&        { lhs => \*(AqTerm\*(Aq, rhs => [qw/Term Add Term/], action => \*(Aqdo_add\*(Aq },
\&        {   lhs    => \*(AqFactor\*(Aq,
\&            rhs    => [qw/Factor Multiply Factor/],
\&            action => \*(Aqdo_multiply\*(Aq
\&        },
\&    ],
.Ve
.SS "Rule descriptors as hashes"
.IX Subsection "Rule descriptors as hashes"
The long form descriptor of a rule is a
reference to a hash
of \fBrule properties\fR.
In each key/value pair of this hash,
the hash key is the rule property name
and the hash value is the value of
that property.
.SS "action"
.IX Subsection "action"
The value of the \f(CW\*(C`action\*(C'\fR rule property is a string which
specifies the semantics for the rule.
For details, see
the document on semantics.
.PP
The semantics of nulling symbols are dealt with on a per-symbol
basis, rather than a per-rule basis.
For this reason the
\&\f(CW\*(C`action\*(C'\fR rule property is useless
for empty rules.
An exception is thrown if an \f(CW\*(C`action\*(C'\fR property
is defined for an empty rule.
.SS "keep"
.IX Subsection "keep"
Separators in sequence rules
are usually not semantically
significant.
By default,
Marpa throws away
separators during parse tree traversal and
before node evaluation time,
so that the semantic actions
do not see the separators.
.PP
If the value of the \f(CW\*(C`keep\*(C'\fR rule property
is a Perl true, Marpa keeps separators.
This allows the semantic actions to examine them.
The downside
is that the
work of distinguishing
sequence separators from sequence items
is pushed into the semantic actions.
For details about the semantics, see
the document on semantics.
.SS "lhs"
.IX Subsection "lhs"
The value of the \f(CW\*(C`lhs\*(C'\fR rule property must be a string containing
the name of the rule's left hand side symbol.
Every Marpa rule must have a left hand side symbol.
.SS "min"
.IX Subsection "min"
\&\f(CW\*(C`min\*(C'\fR must be 0, 1, or undefined.
If \f(CW\*(C`min\*(C'\fR is 0 or 1,
the rule is a \fBsequence rule\fR.
If \f(CW\*(C`min\*(C'\fR is undefined, the rule is an ordinary \fB\s-1BNF\s0 rule\fR.
.PP
Only one symbol,
called the \fBsequence item\fR,
is allowed on the right hand side of a sequence rule.
The sequence item
may not be a nullable symbol.
The input will be required to match
the sequence item
at least \f(CW\*(C`min\*(C'\fR times
and will be allowed to match
the sequence item
an unlimited number of times.
.SS "null_ranking"
.IX Subsection "null_ranking"
\&\f(CW\*(C`null_ranking\*(C'\fR is ignored unless
the recognizer's \f(CW\*(C`ranking_method\*(C'\fR named argument
is set to something other than its default.
The \f(CW\*(C`null_ranking\*(C'\fR named argument allows the application
to control the order in which rules with nullable symbols
are returned by the \f(CW\*(C`value\*(C'\fR method.
Such rules can match the same input in several ways
depending on which symbols are nulled.
These different ways of nulling symbols in a rule
are called its null variants.
.PP
If \f(CW\*(C`null_ranking\*(C'\fR is undefined,
the order of the null variants will be arbitrary.
This is the default,
and is acceptable to most applications.
For details on using the
\&\f(CW\*(C`null_ranking\*(C'\fR named argument,
see the document on parse order.
.SS "proper"
.IX Subsection "proper"
By default, sequence rules with separators allow trailing
separators,
Perl-style.
If the \f(CW\*(C`proper\*(C'\fR rule property is a Perl true,
"\f(CW\*(C`proper\*(C'\fR" separation is enforced.
In proper separation,
separation must actually separate sequence items,
and trailing separators are not allowed.
.SS "rank"
.IX Subsection "rank"
\&\f(CW\*(C`rank\*(C'\fR is ignored unless
the recognizer's \f(CW\*(C`ranking_method\*(C'\fR named argument
is set to something other than its default.
The range allowed for \f(CW\*(C`rank\*(C'\fR is implementation-defined,
but numbers in the range
between \-134,217,727 and 134,217,727
will always be allowed.
\&\f(CW\*(C`rank\*(C'\fR is 0 by default.
For details on using the
\&\f(CW\*(C`rank\*(C'\fR named argument,
see the document on parse order.
.SS "rhs"
.IX Subsection "rhs"
The value of the \f(CW\*(C`rhs\*(C'\fR property is a reference to
an array of strings containing
the names of the rule's right hand symbols,
in order.
This array may be zero length, in which case
this is an \fBempty rule\fR \*(--
a rule with no symbols on the right hand side.
A rule is also empty if
there is no \f(CW\*(C`rhs\*(C'\fR specifier in its descriptor.
.SS "separator"
.IX Subsection "separator"
Any sequence rule may have a \f(CW\*(C`separator\*(C'\fR defined.
The value must be a symbol name.
By default, Marpa allows trailing separators.
This is the usual style in Perl.
The separator must not be a nullable symbol.
.SS "Rule descriptors as arrays"
.IX Subsection "Rule descriptors as arrays"
.Vb 5
\&    rules => [
\&        [ \*(AqE\*(Aq, [qw/E Add E/],      \*(Aqdo_add\*(Aq ],
\&        [ \*(AqE\*(Aq, [qw/E Multiply E/], \*(Aqdo_multiply\*(Aq ],
\&        [ \*(AqE\*(Aq, [qw/Number/], ],
\&    ],
.Ve
.PP
Rule descriptors may be given in \*(L"short form\*(R" \*(--
as a reference to an array.
The elements of the array,
in order,
are
the \f(CW\*(C`lhs\*(C'\fR property,
the \f(CW\*(C`rhs\*(C'\fR property,
and the \f(CW\*(C`action\*(C'\fR property.
The last two are optional.
Omission of an optional
property in a short form descriptor
has the same effect
that omitting the same optional property would have
in the long form.
.SS "Duplicate rules"
.IX Subsection "Duplicate rules"
Marpa throws an exception if a duplicate rule is added.
Two \s-1BNF\s0 rules are considered duplicates if
.IP "\(bu" 4
Both rules have the same left hand symbol.
.IP "\(bu" 4
Both rules have the same right hand symbols in the same order.
.PP
Sequence rules are even more restricted.
The \s-1LHS\s0 of a sequence rule
may not be the \s-1LHS\s0 of another sequence rule.
The \s-1LHS\s0 of a sequence rule
also may not be the \s-1LHS\s0 of any \s-1BNF\s0 rule.
.PP
This restriction on the \s-1LHS\s0 of sequence rules is
intended to make the definition of duplicate rules
intuitive and their detection easy.
It does not limit the expressiveness of Marpa grammars,
because it is very easy to work around.
One workaround to create an
intermediate rule of length one,
whose \s-1RHS\s0 is the sequence \s-1LHS\s0 symbol.
The \s-1LHS\s0 of the intermediate rule can then be used,
without restriction, as the \s-1LHS\s0 of other rules.
.SH "Symbol descriptors"
.IX Header "Symbol descriptors"
.Vb 5
\&    symbols => {
\&        MinusMinus => { terminal => 1 },
\&        Minus      => { terminal => 1 },
\&        Number     => { terminal => 1 },
\&    },
.Ve
.PP
A symbol descriptor is a hash.
In the key/value pairs of this hash,
the hash key is the symbol property name
and the hash value is the value of
that property.
The available symbol properties are as follows:
.SS "terminal"
.IX Subsection "terminal"
A boolean.
If true, it allows the symbol to be used as a terminal.
If false, it disallows use of
the symbol as a terminal.
For details, see
the section on terminals.
.SH "Copyright and License"
.IX Header "Copyright and License"
.Vb 5
\&  Copyright 2014 Jeffrey Kegler
\&  This file is part of Marpa::R2.  Marpa::R2 is free software: you can
\&  redistribute it and/or modify it under the terms of the GNU Lesser
\&  General Public License as published by the Free Software Foundation,
\&  either version 3 of the License, or (at your option) any later version.
\&
\&  Marpa::R2 is distributed in the hope that it will be useful,
\&  but WITHOUT ANY WARRANTY; without even the implied warranty of
\&  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
\&  Lesser General Public License for more details.
\&
\&  You should have received a copy of the GNU Lesser
\&  General Public License along with Marpa::R2.  If not, see
\&  http://www.gnu.org/licenses/.
.Ve