.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 >0, 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::Semantics 3pm"
.TH Marpa::R2::NAIF::Semantics 3pm "2021-01-22" "perl v5.32.0" "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::Semantics \- How the NAIF evaluates parses
.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
\&                },
\&            ],
\&        }
\&    );
.Ve
.PP
.Vb 4
\&    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 "Overview"
.IX Header "Overview"
This document deals with Marpa's low-level \s-1NAIF\s0 interface.
If you are new to Marpa,
or are not sure which interface you are interested in,
or do not know what the Named Argment InterFace (\s-1NAIF\s0) is,
you probably want to look instead at
the document on semantics for the \s-1SLIF\s0
interface.
.PP
The \s-1NAIF\s0's semantics
will be
familiar
to those who have used traditional
methods to evaluate parses.
A parse is seen as a parse tree.
Nodes on the tree are evaluated recursively, bottom-up.
Once the values of all its child nodes are known,
a parent node is ready to be evaluated.
The value of a parse is the value of the top node
of the parse tree.
.PP
When a Marpa grammar is created,
its semantics
is
specified indirectly, as \fBaction names\fR.
To produce the values used in the semantics,
Marpa must do three things:
.IP "\(bu" 4
Determine the action name.
.IP "\(bu" 4
Resolve the action name to an action.
.IP "\(bu" 4
If the action is a rule evaluation closure,
call it to produce the actual result.
.PP
An action name is either reserved,
or resolves to a Perl object.
When it resolves to a Perl object,
that object is usually a Perl closure \*(-- code.
If the Perl object action is code,
it is a rule evaluation closure, and will be
called to produce the result.
When a Perl object action is some other kind of object,
its treatment is
as described
below
.PP
An action name
and action is also used
to create the per-parse-tree variable,
as described
below.
.SH "Nodes"
.IX Header "Nodes"
.SS "Token nodes"
.IX Subsection "Token nodes"
For every input token, there is an associated \fBtoken node\fR.
Token nodes are leaf nodes
in the parse tree.
Tokens always have a \fBtoken symbol\fR.
At lexing time,
they can be assigned a \fBtoken value\fR.
If no token value is assigned at lex time,
the value of the token is a Perl \f(CW\*(C`undef\*(C'\fR.
.SS "Rule nodes"
.IX Subsection "Rule nodes"
If a node is not a token node,
then it is a \fBrule node\fR.
Rule nodes are always
associated with a rule.
It a rule's action is a rule evaluation closure,
it is called at
Node Evaluation Time.
.PP
The rule evaluation closures's
arguments will be a
per-parse-tree variable followed, if the rule is not nulled,
by the values of its child nodes in lexical order.
If the rule is nulled, the child node values will be omitted.
A rule evaluation closure action is always called in scalar context.
.PP
If the action is a constant,
it becomes the value of the rule node.
If the action is a rule evaluation closure,
its return value becomes the value of the node.
If there is no action for a
rule node,
the value of the rule node is a Perl \f(CW\*(C`undef\*(C'\fR.
.SS "Sequence rule nodes"
.IX Subsection "Sequence rule nodes"
Some rules are sequence rules.
Sequence rule nodes are also rule nodes.
Everything said above about rule nodes
applies to sequence rule nodes.
Specifically,
the arguments to the value actions for sequence rules
are the
per-parse-tree variable followed by
the values of the child nodes in lexical order.
.PP
The difference (and it is a big one)
is that in an ordinary rule, the right hand side
is fixed in length, and that length is known
when you are writing the code for the value action.
In a sequence rule,
the number of right hand side symbols is not known
until node evaluation time.
The rule evaluation closure
of a sequence rule
must be capable of
dealing with
a variable number of arguments.
.PP
Sequence semantics work best when
every child node
in the sequence has the same semantics.
When that is not the case,
writing the sequence using
ordinary non-sequence rules should be considered as
an alternative.
.PP
By default, if a sequence rule has separators,
the separators are thrown away before
the value action is called.
(Separators are described in
the section introducing sequence rules.)
This means that separators do not appear in the \f(CW@_\fR array
of the rule evaluation closure which is the value action.
If the value of the \f(CW\*(C`keep\*(C'\fR rule property
is a Perl true value, separators are kept,
and do appear in the
value action's
\&\f(CW@_\fR array.
.SS "Null nodes"
.IX Subsection "Null nodes"
A null node is a special case of a rule node,
one where the rule derives the zero-length,
or empty string.
When the rule node is a null node,
the rule evaluation closure will be called with
no child value arguments.
.PP
When a node is nulled,
it must be as a result of a nullable rule,
and the action name and action are those
associated with that rule.
An ambiguity can arise if there is more
than one nullable rule with the same \s-1LHS,\s0
but a different action name.
In that case the action name for the null nodes
is that of the empty rule.
.PP
The remaining case is that of
a set of nullable rules with the same \s-1LHS,\s0
where two or more of the rules have different action names,
but none of the rules in the set is an empty rule.
When this happens, Marpa throws an exception.
To fix the issue,
the user can add an empty rule.
For more details,
see the document on
null semantics.
.SH "Action context"
.IX Header "Action context"
.Vb 12
\&    sub do_S {
\&        my ($action_object) = @_;
\&        my $rule_id         = $Marpa::R2::Context::rule;
\&        my $grammar         = $Marpa::R2::Context::grammar;
\&        my ( $lhs, @rhs ) = $grammar\->rule($rule_id);
\&        $action_object\->{text} =
\&              "rule $rule_id: $lhs ::= "
\&            . ( join q{ }, @rhs ) . "\en"
\&            . "locations: "
\&            . ( join q{\-}, Marpa::R2::Context::location() ) . "\en";
\&        return $action_object;
\&    } ## end sub do_S
.Ve
.PP
In addition to the per-parse-tree variable
and their child arguments,
rule evaluation closures also have access
to \fBcontext variables\fR.
.IP "\(bu" 4
\&\f(CW$Marpa::R2::Context::grammar\fR is set to
the grammar being parsed.
.IP "\(bu" 4
\&\f(CW$Marpa::R2::Context::rule\fR is the \s-1ID\s0 of the
current rule.
Given the rule \s-1ID,\s0 an application can find
its \s-1LHS\s0 and \s-1RHS\s0 symbols using
the grammar's \f(CW\*(C`rule()\*(C'\fR method.
.IP "\(bu" 4
\&\f(CW\*(C`Marpa::R2::Context::location()\*(C'\fR returns the start
and end locations of the current rule.
.SH "Bailing out of parse evaluation"
.IX Header "Bailing out of parse evaluation"
.Vb 1
\&    my $bail_message = "This is a bail out message!";
\&
\&    sub do_bail_with_message_if_A {
\&        my ($action_object, $terminal) = @_;
\&        Marpa::R2::Context::bail($bail_message) if $terminal eq \*(AqA\*(Aq;
\&    }
\&
\&    sub do_bail_with_object_if_A {
\&        my ($action_object, $terminal) = @_;
\&        Marpa::R2::Context::bail([$bail_message]) if $terminal eq \*(AqA\*(Aq;
\&    }
.Ve
.PP
The \f(CW\*(C`Marpa::R2::Context::bail()\*(C'\fR static method is used to
\&\*(L"bail out\*(R" of the evaluation of a parse tree.
It will cause an exception to be thrown.
If its first and only argument is a reference,
that reference is the exception object.
Otherwise, an exception message is created
by converting the method's arguments to strings,
concatenating them,
and prepending them with a message indicating
the file and line number at which the
\&\f(CW\*(C`Marpa::R2::Context::bail()\*(C'\fR method was called.
.SH "Parse trees, parse results and parse series"
.IX Header "Parse trees, parse results and parse series"
When the semantics are applied to a parse tree,
it produces a value called a \fBparse result\fR.
Because Marpa allows ambiguous parsing,
each parse can produce a \fBparse series\fR \*(--
a series of zero or more parse trees,
each with its own parse result.
The first call to the
the recognizer's \f(CW\*(C`value\*(C'\fR
method
after the recognizer is created is the
start of the first parse series.
The first parse series continues until there is
a call to the
the \f(CW\*(C`reset_evaluation\*(C'\fR
method
or until the recognizer is destroyed.
Usually, an application is only interested in a single
parse series.
.PP
When the
\&\f(CW\*(C`reset_evaluation\*(C'\fR
method
is called
for a recognizer, it begins a new parse series.
The new parse series continues until
there is another
call to the
the \f(CW\*(C`reset_evaluation\*(C'\fR
method,
or until the recognizer is destroyed.
.PP
Most applications will find that the order in which
Marpa executes its semantics \*(L"just works\*(R".
A separate
document
describes that order
in detail.
The details can matter in some applications,
for example, those which exploit side effects.
.SH "Finding the action for a rule"
.IX Header "Finding the action for a rule"
Marpa finds the action for each rule based on
rule and symbol properties and on the grammar named arguments.
Specifically, Marpa attempts the following,
in order:
.IP "\(bu" 4
Resolving an action based on the \f(CW\*(C`action\*(C'\fR property of the rule,
if one is defined.
.IP "\(bu" 4
If the rule is empty,
and the \f(CW\*(C`default_empty_action\*(C'\fR named argument of the grammar
is defined,
resolving an action based on that named argument.
.IP "\(bu" 4
Resolving an action based on
the \f(CW\*(C`default_action\*(C'\fR named argument of the grammar,
if one is defined.
.IP "\(bu" 4
Defaulting to a Perl \f(CW\*(C`undef\*(C'\fR value.
.PP
Resolution of action names is described
below.
If the \f(CW\*(C`action\*(C'\fR property,
the \f(CW\*(C`default_action\*(C'\fR named argument,
or the \f(CW\*(C`default_empty_action\*(C'\fR named argument
is defined,
but does not resolve successfully, Marpa
throws an exception.
Marpa prefers to \*(L"fast fail\*(R" in these cases,
because they usually indicate a mistake
that the application's author
will want to correct.
.SH "Resolving action names"
.IX Header "Resolving action names"
Action names come from these sources:
.IP "\(bu" 4
The \f(CW\*(C`default_action\*(C'\fR named argument of Marpa's grammar.
.IP "\(bu" 4
The \f(CW\*(C`default_empty_action\*(C'\fR named argument of Marpa's grammar.
.IP "\(bu" 4
The \f(CW\*(C`action\*(C'\fR property of Marpa's rules.
.IP "\(bu" 4
The \f(CW\*(C`new\*(C'\fR constructor in the package specified by the
\&\f(CW\*(C`action_object\*(C'\fR named argument of the Marpa grammar.
.SS "Reserved action names"
.IX Subsection "Reserved action names"
Action names that begin with a double colon ("\f(CW\*(C`::\*(C'\fR") are reserved.
At present only the \f(CW\*(C`::undef\*(C'\fR reserved action is documented for
use outside of the DSL-based interfaces.
.PP
\fI::undef\fR
.IX Subsection "::undef"
.PP
A constant whose value is a Perl \f(CW\*(C`undef\*(C'\fR.
Perl is unable to distinguish reliably between a
non-existent value and scalars with an \f(CW\*(C`undef\*(C'\fR value.
This makes it impossible to reliably distinguish
resolutions
to a Perl \f(CW\*(C`undef\*(C'\fR from resolution problems.
The "\f(CW\*(C`::undef\*(C'\fR" reserved action name should 
be preferred for
indicating a constant whose value is a Perl \f(CW\*(C`undef\*(C'\fR.
.SS "Explicit resolution"
.IX Subsection "Explicit resolution"
The recognizer's \f(CW\*(C`closures\*(C'\fR named argument
allows the user to directly control the mapping from action names
to actions.
The value of the \f(CW\*(C`closures\*(C'\fR named argument
is a reference to a hash whose keys are
action names and whose hash values are references.
Typically (but not always) these will be \f(CW\*(C`CODE\*(C'\fR refs.
.PP
If an action name is the key of an entry in the \f(CW\*(C`closures\*(C'\fR hash,
it resolves to the closure referenced by the value part of that hash entry.
Resolution via the \f(CW\*(C`closures\*(C'\fR named argument is
called \fBexplicit resolution\fR.
.PP
When explicit resolution is the only kind of resolution that is wanted,
it is best to pick a name that is very unlikely to be the name
of a Perl object.
Many of
Marpa::HTML's action names
are intended for explicit resolution only.
In Marpa::HTML those action names
begin with
an exclamation mark (\*(L"!\*(R"),
and that convention is recommended.
.SS "Fully qualified action names"
.IX Subsection "Fully qualified action names"
If explicit resolution fails,
Marpa transforms the action name into a
\&\fBfully qualified\fR Perl name.
An action name that
contains a double colon ("\f(CW\*(C`::\*(C'\fR\*(L") or a single quote (\*(R"\f(CW\*(C`\*(Aq\*(C'\fR")
is considered to be a fully qualified name.
Any other action name is considered to be a \fBbare action name\fR.
.PP
If the action name to be resolved is already a fully qualified name,
it is not further transformed.
It will be resolved in the form it was received,
or not at all.
.PP
For bare action names,
Marpa tries to qualify them by adding a package name.
If the \f(CW\*(C`actions\*(C'\fR grammar named argument is defined,
Marpa uses it as the package name.
Otherwise,
if the
\&\f(CW\*(C`action_object\*(C'\fR grammar named argument is defined,
Marpa uses it as the package name.
Once Marpa has fully qualified the action name,
Marpa looks for a Perl object with that name.
.PP
Marpa will not attempt to resolve an action name
that it cannot fully qualify.
This implies that,
for an action name to resolve successfully,
one of these five things must be the case:
.IP "\(bu" 4
The action name is one of the reserved action names.
.IP "\(bu" 4
The action name resolves explicitly.
.IP "\(bu" 4
The action name is fully qualified to begin with.
.IP "\(bu" 4
The \f(CW\*(C`actions\*(C'\fR named argument is defined.
.IP "\(bu" 4
The \f(CW\*(C`action_object\*(C'\fR named argument is defined.
.PP
Marpa's philosophy
is to require that the programmer be specific about action names.
This can be an inconvenience, but Marpa prefers this to
silently executing unintended code.
.PP
If the user wants to leave the
rule evaluation closures in the \f(CW\*(C`main\*(C'\fR namespace,
she can specify
\&\f(CW"main"\fR
as the value of the \f(CW\*(C`actions\*(C'\fR named argument.
But
it can be good practice to keep
the rule evaluation closures
in their own namespace,
particularly if the application is not small.
.SS "Types of Perl actions"
.IX Subsection "Types of Perl actions"
Actions resolve in three ways:
to reserved actions, to Perl rule evaluation closures and to Perl variable actions.
The following are tried, in order.
.IP "\(bu" 4
If an action name begins with a double colon ("\f(CW\*(C`::\*(C'\fR"),
it will resolve to a reserved action, or not at all.
.IP "\(bu" 4
If the fully qualified form of an action name is the name of a Perl
subroutine in the symbol table,
the action name resolves to the Perl subroutine.
That subroutine then becomes a Perl rule evaluation closure.
.IP "\(bu" 4
If the fully qualified form of an action name is the name of a Perl
scalar variable in the symbol table,
the action name resolves to the Perl variable.
Note that, for this purpose, a Perl reference variable is considered as one type of Perl scalar.
.IP "\(bu" 4
Other kinds of Perl objects in the symbol table that match the fully qualified name,
such as arrays and hashes, are ignored.
Note that, while resolution to arrays and hashes is not allowed,
resolution to references to arrays and hashes is permitted.
.PP
Resolution to a
Perl rule evaluation closure
or to a Perl variable
may came from explicit resolution.
Explicit resolution always takes place via a reference,
and requires an extra level of indirection.
For resolution to a rule evaluation closure,
the closure must be provided in the form of a reference to the closure.
For resolution to a Perl variable,
the variable has to be provided in the form of a reference to the variable.
If the Perl variable is a reference, that means adding another level of
indirection.
.SS "Modifying Perl variable actions"
.IX Subsection "Modifying Perl variable actions"
When resolution is to a
Perl variable,
it is possible to modify the value of the variable.
In practice, this will usually be a bad idea.
The Perl variable reference actions should be treated
as read-only constants, and never modified.
.PP
This is because multiple resolutions
to a Perl variable will
always point to the same contents.
Any modification to those contents will be
seen by other users of that Perl variable.
In other words, the modification will have global
effect.
For this reason modifying the referents of
reference actions is almost always bad practice
at the least, and is often an error.
.PP
For example,
assume that actions are in a package named \f(CW\*(C`My_Nodes\*(C'\fR,
which contains a hash reference named \f(CW\*(C`empty_hash\*(C'\fR,
.PP
.Vb 2
\&        package My_Nodes;
\&        our $empty_hash = {};
.Ve
.PP
It can be tempting, in building objects which are hashes,
to start with a leaf node whose action is \f(CW\*(C`empty_hash\*(C'\fR
and to add contents to it as the object is passed up the evaluation
tree.
But \f(CW$empty_hash\fR points to a single hash object.
This single hash object will shared by all nodes,
with all nodes seeing each other's changes.
Worse, all Marpa parsers which use the same \f(CW\*(C`My_Nodes\*(C'\fR
namespace will share the same hash object.
An application which needs an action which produces
an empty hash should have the action resolve to a Perl rule
evaluation closure
that returns \f(CW\*(C`{}\*(C'\fR.
.SS "Visibility and resolution"
.IX Subsection "Visibility and resolution"
When Perl closures and variables are used for the semantics,
they must be visible in the scope where the semantics are
\&\fBresolved\fR.
The action names are usually \fBspecified\fR with the grammar,
but action \fBresolution\fR takes place
in the recognizer's
\&\f(CW\*(C`value\*(C'\fR method.
This can sometimes be a source of confusion.
For example, if a Perl closure is visible when the
action is specified,
but goes out of scope before the action name is resolved,
resolution will fail.
.SH "The per-parse-tree variable"
.IX Header "The per-parse-tree variable"
In the Tree Setup Phase,
Marpa creates a per-parse-tree variable.
This becomes the first argument of the rule evaluation closures for
the rule nodes.
If the grammar's \f(CW\*(C`action_object\*(C'\fR named argument is not defined,
the per-parse-tree variable is initialized to an empty hash ref.
.PP
Most data for
the value actions of the rules
will be passed up the parse tree.
The actions will see the values of the rule node's child nodes
as arguments,
and will return their own value to be seen as an argument
by their parent node.
The per-parse-tree variable can be used for data which does not
conveniently fit this model.
.PP
The lifetime of the per-parse-tree variable
extends into the Tree Traversal Phase.
During the Tree Traversal Phase,
Marpa's internals never alter the per-parse-tree variable \*(--
it is reserved for use by the application.
.SS "Action object constructor"
.IX Subsection "Action object constructor"
If the grammar's \f(CW\*(C`action_object\*(C'\fR named argument has a defined value,
that value is treated as the name of a class.
The \fBaction object constructor\fR is
the \f(CW\*(C`new\*(C'\fR method
in the \f(CW\*(C`action_object\*(C'\fR class.
.PP
The action object constructor is called
in the Tree Setup Phase.
The return value of the
action object constructor becomes the per-parse-tree variable.
It is a fatal error if the
grammar's \f(CW\*(C`action_object\*(C'\fR named argument is defined,
but does not name a class with a \f(CW\*(C`new\*(C'\fR method.
.PP
Resolution of the action object constructor is
resolution of the \fBaction object constructor name\fR.
The action object constructor name is
formed by concatenating
the literal string "\f(CW\*(C`::new\*(C'\fR" to
the value of the \f(CW\*(C`action_object\*(C'\fR named argument.
.PP
All standard rules apply when resolving the action
object constructor name.
In particular, bypass via
explicit resolution applies to
the action object constructor.
If the action object constructor name is
a hash key in the
evaluator's \f(CW\*(C`closures\*(C'\fR named argument,
then
the value referred to by
that hash entry becomes the
action object constructor.
.PP
If a grammar has both the \f(CW\*(C`actions\*(C'\fR and the
\&\f(CW\*(C`action_object\*(C'\fR named arguments defined,
all action names \fBexcept\fR
for the action object constructor will be
resolved in the \f(CW\*(C`actions\*(C'\fR package or not at all.
The action object constructor is always in
the \f(CW\*(C`action_object\*(C'\fR class, if it is anywhere.
.SH "Parse order"
.IX Header "Parse order"
If a parse is ambiguous, all parses are returned,
with no duplication.
By default, the order is arbitrary, but
it is also possible to control the order.
Details are in the document
on parse order.
.SH "Infinite loops"
.IX Header "Infinite loops"
Grammars with infinite loops (cycles)
are generally regarded as useless in practical applications,
but Marpa allows them.
Marpa can accurately
claim to support \fBevery grammar\fR that can be written in \s-1BNF.\s0
.PP
If a grammar with cycles is ambiguous,
it can produce cycle-free parses
and parses with finite-length cycles,
as well as parses with infinite length cycles.
Marpa will parse with grammars that contain cycles,
and Marpa's evaluator will iterate through
the values from the grammar's
cycle-free parses.
For those who want to know more,
the details are in a separate
document.
.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