NAME

       Marpa::R2::Semantics::Phases - Phases of SLIF parse evaluation

Overview of the semantic phases

       Most users will not need to read this document.  Most applications will find that the
       order in which the SLIF executes its semantics "just works".  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.

Parse trees and parse series

       Because Marpa allows ambiguous parsing, each parse can produce a parse series -- a series
       of zero or more parse trees, each with its own parse result.  The first call to the SLIF
       recognizer's "value()" method after the recognizer is created is the start of the first
       parse series, and Parse Series Setup Phase takes place at this point.

       The first parse series continues until there is a call to the "series_restart()" method or
       until the recognizer is destroyed.  An application is usually interested in only one parse
       series.

       The "series_restart()" method starts a new parse series.  The Parse Series Setup Phase for
       that parse series will take place during the next call of the SLIF recognizer's "value()"
       method.

Summary of the phases

       While processing a parse series, we have:

       •   A Parse Series Setup Phase, which occurs during the first call of the SLIF
           recognizer's "value()" method for that series.  It is followed by

       •   the processing of zero or more parse trees.

       While processing a parse tree, we have:

       •   A Parse Tree Setup Phase, which occurs during the call of the recognizer's "value()"
           method for that parse tree.  It is followed by

       •   a Parse Tree Traveral Phase.

       Node Evaluation Time is the Tree Traversal Phase, as seen from the point of view of each
       rule node.  It is not a separate phase.

Parse Series Setup Phase

       During the Parse Series Setup Phase all action names are resolved to actions -- Perl
       scalars or rule evaluation closures.  The rule evaluation closures are not called in the
       Parse Series Setup Phase.  They will be called later, in the Parse Tree Traversal Phase.
       Also, during the Parse Series Setup Phase, the logic which ranks parse trees is executed.

Parse Tree Setup Phase

       In the Parse Tree Setup Phase, the per-parse argument is created.  If a per-parse
       constructor was found, it is run at this point, and the per-parse argument is its return
       value.  Exactly one Parse Tree Setup Phase occurs for each parse tree.

Parse Tree Traversal Phase

       During the Parse Tree Traversal Phase, the rule evaluation closures are called.  Node
       Evaluation Time is the Parse Tree Traversal Phase, as seen from the point of view of the
       individual nodes of the parse tree.

Copyright and License

         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/.