.\" 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::Semantics::Phases 3pm"
.TH Marpa::R2::NAIF::Semantics::Phases 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::Semantics::Phases \- Details of NAIF parse evaluation
.SH "Overview of the semantic phases"
.IX Header "Overview of the semantic phases"
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
Most applications will find that the order in which
Marpa's \s-1NAIF\s0 executes its semantics \*(L"just works\*(R".
This document describes that order in detail.
These details can matter in some applications,
for example, those which exploit side effects.
And some readers may also find this background material
to be helpful.
.PP
An advanced document,
this is written on the assumption that the more low-level \s-1NAIF\s0 interface
is in use.
The \s-1SLIF\s0 uses the same code as the \s-1NAIF\s0 for evaluation
and works in the same way,
except that it hides even more of these details from the user.
.SH "Parse trees, parse results and parse series"
.IX Header "Parse trees, parse results and parse series"
As a reminder,
when the semantics are applied to a parse tree,
they produce 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.
.SH "Summary of the phases"
.IX Header "Summary of the phases"
While processing a parse series, we have:
.IP "\(bu" 4
A Series Setup Phase, which occurs during
the first call of the recognizer's \f(CW\*(C`value\*(C'\fR method
for that series.
It is followed by
.IP "\(bu" 4
the processing of zero or more parse trees.
.PP
While processing a parse tree, we have:
.IP "\(bu" 4
A Tree Setup Phase, which occurs during
the call of the recognizer's \f(CW\*(C`value\*(C'\fR method
for that parse tree.
It is followed by
.IP "\(bu" 4
a Tree Traveral Phase.
.PP
\&\fBNode Evaluation Time\fR
is the Tree Traversal Phase, as seen from the point of view of
each rule node.  It is not a separate phase.
.SH "Series Setup Phase"
.IX Header "Series Setup Phase"
During the Series Setup Phase
all value action names are resolved to
value actions \*(--
constants
or rule evaluation closures.
The rule evaluation closures are never called in the Series Setup Phase.
They will be called later,
in the Tree Traversal Phase.
Also, during the Series Setup Phase,
the logic which
ranks parse trees is executed.
.SH "Tree Setup Phase"
.IX Header "Tree Setup Phase"
In the Tree Setup Phase,
the per-parse-tree variable is created.
If a constructor was found for the \f(CW\*(C`action_object\*(C'\fR,
it is run at this point, and the per-parse-tree variable is
its return value.
Exactly one Tree Setup Phase occurs
for each parse tree.
.SH "Tree Traversal Phase"
.IX Header "Tree Traversal Phase"
During the Tree Traversal Phase,
the rule evaluation closures are called.
Node Evaluation Time is the Tree Traversal Phase,
as seen from the point of view of the individual nodes of the parse tree.
.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