.\" 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 3pm"
.TH Marpa::R2::NAIF 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 \- Marpa named argument interface (NAIF)
.SH "Synopsis"
.IX Header "Synopsis"
.Vb 1
\&    use Marpa::R2;
\&
\&    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();
\&
\&    my $recce = Marpa::R2::Recognizer\->new( { grammar => $grammar } );
\&
\&    $recce\->read( \*(AqNumber\*(Aq, 42 );
\&    $recce\->read(\*(AqMultiply\*(Aq);
\&    $recce\->read( \*(AqNumber\*(Aq, 1 );
\&    $recce\->read(\*(AqAdd\*(Aq);
\&    $recce\->read( \*(AqNumber\*(Aq, 7 );
\&
\&    sub My_Actions::do_add {
\&        my ( undef, $t1, undef, $t2 ) = @_;
\&        return $t1 + $t2;
\&    }
\&
\&    sub My_Actions::do_multiply {
\&        my ( undef, $t1, undef, $t2 ) = @_;
\&        return $t1 * $t2;
\&    }
\&
\&    sub My_Actions::first_arg { shift; return shift; }
\&
\&    my $value_ref = $recce\->value;
\&    my $value = $value_ref ? ${$value_ref} : \*(AqNo Parse\*(Aq;
.Ve
.SH "About this document"
.IX Header "About this document"
This document contains a top-level overview of,
and tutorial for,
the named argument inteface (\s-1NAIF\s0) for the Marpa parse engine.
If you are a new to Marpa, you want to start with
the tutorial for the
the Scanless interface (\s-1SLIF\s0)
instead.
.PP
The \s-1NAIF\s0 is a middle level interface.
It is more low level than
the Scanless interface
(\s-1SLIF\s0),
which uses a domain-specific language.
But it is higher level,
and provides more features, than
the thin
interface,
which provides direct access to the underlying
Libmarpa C library.
.PP
The two examples in this document
show the typical flows of \s-1NAIF\s0 Marpa method calls.
This document will use these examples
to describe the basic features of Marpa
in semi-tutorial fashion.
More advanced features, and full reference details of all features,
can be found in the other Marpa \s-1API\s0 documents.
.SS "The three phases"
.IX Subsection "The three phases"
A parser needs to:
.IP "\(bu" 4
Accept a grammar.
.IP "\(bu" 4
Read input.
.IP "\(bu" 4
Return values from the parses,
according to a semantics.
.PP
In Marpa these three tasks
are, for the most part, distinct phases.
Grammars are
\&\f(CW\*(C`Marpa::R2::Grammar\*(C'\fR objects.
The reading of input and the evaluation of the parse
according to the semantics is performed by
\&\f(CW\*(C`Marpa::R2::Recognizer\*(C'\fR objects.
.SH "Example 1: a simple calculator"
.IX Header "Example 1: a simple calculator"
The synopsis shows the code for a very simple calculator.
It handles only
addition and multiplication of integers.
This section explains, line by line, how it works.
.SS "Marpa::R2::Grammar::new"
.IX Subsection "Marpa::R2::Grammar::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
Marpa grammars are
\&\f(CW\*(C`Marpa::R2::Grammar\*(C'\fR objects.
They are created
with the
Marpa::R2::Grammar::new
constructor.
The arguments to
Marpa::R2::Grammar::new
are references to
hashes of named arguments.
In the key/value pairs of these hashes,
the
hash key
is the
name of the argument,
and the
hash value
is the
value of the named argument.
.PP
\fIThe start named argument\fR
.IX Subsection "The start named argument"
.PP
.Vb 1
\&    start => \*(AqExpression\*(Aq,
.Ve
.PP
The \f(CW\*(C`start\*(C'\fR named argument is required.
Its value is
a string containing the name of the grammar's start symbol.
.PP
\fINamed arguments for the semantics\fR
.IX Subsection "Named arguments for the semantics"
.PP
.Vb 2
\&            actions => \*(AqMy_Actions\*(Aq,
\&            default_action => \*(Aqfirst_arg\*(Aq,
.Ve
.PP
The \f(CW\*(C`actions\*(C'\fR and \f(CW\*(C`default_action\*(C'\fR named arguments specify
semantics.
Their argument values are strings,
which acquire their semantics during evaluation.
.PP
Evaluation will be described later.
Peeking ahead,
\&\f(CW\*(C`actions\*(C'\fR provides the name
of a Perl package where Marpa will look for
its \fBactions\fR.
The \f(CW\*(C`default_action\*(C'\fR named argument
will be interpreted
as an \fBaction name\fR in that package.
This action name will resolve to an action \*(--
a Perl closure that implements semantics.
The action specified by \f(CW\*(C`default_action\*(C'\fR
is used as the action for rules
with no action of their own.
.PP
\fIThe rules named argument\fR
.IX Subsection "The rules named argument"
.PP
.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
.PP
The value of the
\&\f(CW\*(C`rules\*(C'\fR named argument is a reference to an array of
\&\fBrule descriptors\fR.
In this example, all the rule descriptors are in the \*(L"long\*(R" form \*(--
they are references to hashes of \fBrule properties\fR.
In each key/value pair of a rule descriptor hash, the key is
the name of a rule property, and the hash value is the value of
that rule property.
.PP
The lhs property
.IX Subsection "The lhs property"
.PP
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.
.PP
The rhs property
.IX Subsection "The rhs property"
.PP
The value of the \f(CW\*(C`rhs\*(C'\fR property is a reference to
an array of strings containing
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.
There are no empty rules in this example.
.PP
The action property
.IX Subsection "The action property"
.PP
The value of the \f(CW\*(C`action\*(C'\fR rule property is a string.
Peeking ahead, each \f(CW\*(C`action\*(C'\fR property string
will be interpreted
as an action name.
This action name will be resolved
to a Perl closure that
implements
the rule's semantics.
.SS "Marpa::R2::Grammar::precompute"
.IX Subsection "Marpa::R2::Grammar::precompute"
.Vb 1
\&    $grammar\->precompute();
.Ve
.PP
Before a Marpa grammar object can be used by a Marpa recognizer,
it must be \fBprecomputed\fR.
Precomputation compiles data structures that the recognizer will need.
.SS "Marpa::R2::Recognizer::new"
.IX Subsection "Marpa::R2::Recognizer::new"
.Vb 1
\&    my $recce = Marpa::R2::Recognizer\->new( { grammar => $grammar } );
.Ve
.PP
\&\f(CW\*(C`Marpa::R2::NAIF::Recognizer::new\*(C'\fR creates a new recognizer.
Its arguments are references to hashes of named arguments.
In this example the only named argument is
the required argument: "\f(CW\*(C`grammar\*(C'\fR".
The value of the
\&\f(CW\*(C`grammar\*(C'\fR
named argument must be a precomputed Marpa
grammar.
.SS "Marpa::R2::Recognizer::read"
.IX Subsection "Marpa::R2::Recognizer::read"
.Vb 5
\&    $recce\->read( \*(AqNumber\*(Aq, 42 );
\&    $recce\->read(\*(AqMultiply\*(Aq);
\&    $recce\->read( \*(AqNumber\*(Aq, 1 );
\&    $recce\->read(\*(AqAdd\*(Aq);
\&    $recce\->read( \*(AqNumber\*(Aq, 7 );
.Ve
.PP
The \f(CW\*(C`Marpa::R2::NAIF::Recognizer::read\*(C'\fR method takes two arguments,
a \fBtoken name\fR and a \fBtoken value\fR.
The token name must be the name
of a valid terminal symbol in the grammar.
By default symbols are valid as terminal symbols,
if and only if they do \s-1NOT\s0 occur on the \s-1LHS\s0 of
any rule.
.PP
The \fBtoken value\fR
must be a Perl scalar, but otherwise its form
and semantics
are entirely up to the application.
If the token value is never used,
it can be omitted.
In the calculator example, the values of the
"\f(CW\*(C`Add\*(C'\fR\*(L"
and \*(R"\f(CW\*(C`Multiply\*(C'\fR" tokens are never used,
and are allowed to default to an undefined value.
.SS "Marpa::R2::Recognizer::value"
.IX Subsection "Marpa::R2::Recognizer::value"
.Vb 2
\&    my $value_ref = $recce\->value;
\&    my $value = $value_ref ? ${$value_ref} : \*(AqNo Parse\*(Aq;
.Ve
.PP
The \f(CW\*(C`Marpa::R2::NAIF::Recognizer::value\*(C'\fR method returns
a reference to the parse result's value,
if there was a parse result.
If there was no parse result,
\&\f(CW\*(C`Marpa::R2::NAIF::Recognizer::value\*(C'\fR
returns
\&\f(CW\*(C`undef\*(C'\fR.
.SS "Resolving the semantics"
.IX Subsection "Resolving the semantics"
The first thing \f(CW\*(C`Marpa::R2::NAIF::Recognizer::value\*(C'\fR needs to do is
to resolve the semantics.
\&\fBResolving the semantics\fR means
mapping the action names into actions.
\&\fBActions\fR are Perl
closures which directly implement semantics.
In this example,
the \f(CW\*(C`actions\*(C'\fR named argument is specified.
\&\f(CW\*(C`actions\*(C'\fR is a Perl package name.
Marpa will look for actions
in that package.
.PP
.Vb 1
\&    actions => \*(AqMy_Actions\*(Aq,
.Ve
.PP
.Vb 1
\&    { lhs => \*(AqFactor\*(Aq, rhs => [qw/Factor Multiply Factor/], action => \*(Aqdo_multiply\*(Aq },
.Ve
.PP
For example, the \f(CW\*(C`action\*(C'\fR property for the above rule
is "\f(CW\*(C`do_multiply\*(C'\fR" and the \f(CW\*(C`actions\*(C'\fR named argument to the grammar
was "\f(CW\*(C`My_Actions\*(C'\fR".
So Marpa looks for a closure whose fully qualified name is \f(CW\*(C`My_Actions::do_multiply\*(C'\fR,
which it finds:
.PP
.Vb 4
\&    sub My_Actions::do_multiply {
\&        my ( undef, $t1, undef, $t2 ) = @_;
\&        return $t1 * $t2;
\&    }
.Ve
.PP
Rules do not always have \f(CW\*(C`action\*(C'\fR properties.
That is the case with these rules in this example:
.PP
.Vb 3
\&    { lhs => \*(AqExpression\*(Aq, rhs => [qw/Term/] },
\&    { lhs => \*(AqTerm\*(Aq, rhs => [qw/Factor/] },
\&    { lhs => \*(AqFactor\*(Aq, rhs => [qw/Number/] },
.Ve
.PP
The rules in the above display have no action names.
When a rule has no action name,
Marpa will fall back to trying to use
the default action,
as described next.
.PP
.Vb 1
\&    default_action => \*(Aqfirst_arg\*(Aq,
.Ve
.PP
The \f(CW\*(C`default_action\*(C'\fR named argument is resolved in the same way
as are the \f(CW\*(C`action\*(C'\fR properties of the
rules.
In this example,
default_action is specified as "\f(CW\*(C`first_arg\*(C'\fR"
and resolves to
\&\f(CW\*(C`My_Actions::first_arg\*(C'\fR.
.SS "Actions"
.IX Subsection "Actions"
.Vb 1
\&    sub My_Actions::first_arg { shift; return shift; }
.Ve
.PP
.Vb 4
\&    sub My_Actions::do_add {
\&        my ( undef, $t1, undef, $t2 ) = @_;
\&        return $t1 + $t2;
\&    }
.Ve
.PP
Value actions are Perl closures used as callbacks.
Value actions are called when nodes in a parse tree are evaluated.
A value action receives one or more arguments.
The first argument to a value action is always a per-parse-tree
object, which the callbacks can use as a scratchpad.
In these examples, the per-parse-tree object is not used.
.PP
For a non-empty rule,
the second and any subsequent arguments to the callback are
the values,
in lexical order,
of the symbols on the right hand side of
the rule.
If the action is for an empty rule,
the per-parse-tree object will be its only argument.
.PP
Every value action is expected to return a value.
With one exception,
this value is passed up to a parent node
as an argument.
The exception is the value for the start rule.
The return value for the start rule becomes
the parse result.
.PP
Rules with no action specified for them take their
semantics from the \f(CW\*(C`default_action\*(C'\fR named argument.
If there is no default action for a grammar,
rules with no action specified for them
return a Perl \f(CW\*(C`undef\*(C'\fR.
.SH "Example 2: an ambiguous parse"
.IX Header "Example 2: an ambiguous parse"
This is the same calculator as before,
rewritten to be ambiguous.
Rather than give multiplication precedence over
addition,
the rewritten calculator allows any order of operations.
In this example,
the actions (\f(CW\*(C`My_Actions::do_add\*(C'\fR, etc.)
and the \f(CW@tokens\fR array remain
the same as before.
.PP
Eliminating precedence makes the grammar shorter,
but it also means there can be multiple parse trees,
and that the different parse trees can have different parse results.
In this application we decide, for each input,
to return every one of the parse results.
.PP
.Vb 1
\&    use Marpa::R2;
\&
\&    my $ambiguous_grammar = Marpa::R2::Grammar\->new(
\&        {   start   => \*(AqE\*(Aq,
\&            actions => \*(AqMy_Actions\*(Aq,
\&            rules   => [
\&                [ \*(AqE\*(Aq, [qw/E Add E/],      \*(Aqdo_add\*(Aq ],
\&                [ \*(AqE\*(Aq, [qw/E Multiply E/], \*(Aqdo_multiply\*(Aq ],
\&                [ \*(AqE\*(Aq, [qw/Number/],       ],
\&            ],
\&            default_action => \*(Aqfirst_arg\*(Aq,
\&        }
\&    );
\&
\&    $ambiguous_grammar\->precompute();
\&
\&    my $ambiguous_recce =
\&        Marpa::R2::Recognizer\->new( { grammar => $ambiguous_grammar } );
\&
\&    $ambiguous_recce\->read( \*(AqNumber\*(Aq, 42 );
\&    $ambiguous_recce\->read(\*(AqMultiply\*(Aq);
\&    $ambiguous_recce\->read( \*(AqNumber\*(Aq, 1 );
\&    $ambiguous_recce\->read(\*(AqAdd\*(Aq);
\&    $ambiguous_recce\->read( \*(AqNumber\*(Aq, 7 );
\&
\&    my @values = ();
\&    while ( defined( my $ambiguous_value_ref = $ambiguous_recce\->value() ) ) {
\&        push @values, ${$ambiguous_value_ref};
\&    }
.Ve
.SS "Short form rule descriptors"
.IX Subsection "Short form rule descriptors"
.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
The rule descriptors in the
ambiguous example demonstrate the \*(L"short\*(R" or array form of rule
descriptors.
Array form rule descriptors are references to arrays.
Here the elements are, in order,
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.
.SS "Marpa::R2::Recognizer::value"
.IX Subsection "Marpa::R2::Recognizer::value"
.Vb 4
\&    my @values = ();
\&    while ( defined( my $ambiguous_value_ref = $ambiguous_recce\->value() ) ) {
\&        push @values, ${$ambiguous_value_ref};
\&    }
.Ve
.PP
When called more than once,
the \f(CW\*(C`Marpa::R2::NAIF::Recognizer::value\*(C'\fR method iterates through the parse results.
For each call,
it returns a reference to the parse result.
At the end of the iteration, after
all parse results have been returned,
\&\f(CW\*(C`Marpa::R2::NAIF::Recognizer::value\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR.
If there were no parse results,
\&\f(CW\*(C`Marpa::R2::NAIF::Recognizer::value\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR the first
time that it is called.
.SH "Errors and exceptions"
.IX Header "Errors and exceptions"
As a general rule,
methods in the Marpa \s-1NAIF API\s0 do not return errors.
When there are errors,
Marpa \s-1NAIF API\s0 methods throw an exception.
.SH "Inheritance"
.IX Header "Inheritance"
Classes in the Marpa \s-1API\s0 are not designed to
be inherited.
.SH "The Marpa:: namespace"
.IX Header "The Marpa:: namespace"
The \f(CW\*(C`Marpa::\*(C'\fR top-level namespace is reserved.
For extensions to Marpa,
one appropriate place is the \f(CW\*(C`MarpaX::\*(C'\fR namespace.
This practice helps avoid namespace collisions,
and follows a \s-1CPAN\s0 standard, as exemplified by
the
\&\f(CW\*(C`DBIx::\*(C'\fR
\&\f(CW\*(C`LWPx::\*(C'\fR
and
\&\f(CW\*(C`MooseX::\*(C'\fR
which are for extensions of, respectively,
\&\s-1DBI, LWP\s0 and Moose.
.SH "Other documents"
.IX Header "Other documents"
This document gives a semi-tutorial overview of the entire Marpa \s-1NAIF API.\s0
For full details on Marpa's grammar objects and their methods,
see the
Marpa::R2::NAIF::Grammar document.
For full details on Marpa's recognizer objects and their methods,
see the
Marpa::R2::NAIF::Recognizer document.
.PP
Marpa::R2::Vocabulary is intended as a quick refresher in
parsing terminology,
emphasizing how the standard terms are used
in the Marpa context.
the \s-1NAIF\s0's standard semantics are fully described in the
Marpa::R2::NAIF::Semantics document.
Techniques for tracing and for debugging your Marpa grammars
are described in the
Marpa::R2::NAIF::Tracing document and the
Marpa::R2::NAIF::Progress document.
For those with a theoretical bent,
my sources, and other useful references, are described in
Marpa::R2::Advanced::Bibliography.
.SH "Support"
.IX Header "Support"
Marpa::R2 comes without warranty.
Support is provided
on a volunteer basis
through the standard mechanisms for \s-1CPAN\s0 modules.
The Support document has details.
.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