Marpa::R2::NAIF::Semantics::Phases - Details of NAIF parse evaluation

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

perl v5.40.0                                       2024-12-07             Marpa::R2::NAIF...mantics::Phases(3pm)

       Marpa::R2::NAIF::Semantics::Phases - Details of NAIF parse evaluation

       This document deals with Marpa's low-level NAIF 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 (NAIF) is, you
       probably want to look instead at the document on semantics for the SLIF interface.

       Most applications will find that the order in which Marpa's NAIF 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.

       An advanced document, this is written on the assumption that the more low-level NAIF interface is in use.
       The SLIF uses the same code as the NAIF for evaluation and works in the same way, except that it hides
       even more of these details from the user.

       As a reminder, when the semantics are applied to a parse tree, they produce a value called a parseresult.  Because Marpa allows ambiguous parsing, each parse can produce a parseseries -- a series of
       zero or more parse trees, each with its own parse result.  The first call to the the recognizer's "value"
       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 "reset_evaluation" method or until the recognizer is
       destroyed.  Usually, an application is only interested in a single parse series.

       When the "reset_evaluation" 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 "reset_evaluation" method, or until the
       recognizer is destroyed.

       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.

       While processing a parse series, we have:

       •   A  Series Setup Phase, which occurs during the first call of the 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 Tree Setup Phase, which occurs during the call of the recognizer's "value" method  for  that  parse
           tree.  It is followed by

       •   a Tree Traveral Phase.

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

       In  the  Tree  Setup  Phase,  the per-parse-tree variable is created.  If a constructor was found for the
       "action_object", 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.

       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.