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

=head1 NAME

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

=head1 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.

=head1  Parse trees and parse series

Because Marpa allows ambiguous parsing,
each parse can produce a B<parse series> --
a series of zero or more parse trees,
each with its own parse result.
The first call to the
L<SLIF recognizer's C<value()>
method|Marpa::R2::Scanless::R/"value()">
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
L<C<series_restart()>
method|Marpa::R2::Scanless::R/"series_restart()">
or until the recognizer is destroyed.
An application is usually interested in only one
parse series.

The C<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 C<value()> method.

=head1 Summary of the phases

While processing a parse series, we have:

=over

=item * A Parse Series Setup Phase, which occurs during
the first call of the SLIF recognizer's C<value()> method
for that series.
It is followed by

=item * the processing of zero or more parse trees.

=back

While processing a parse tree, we have:

=over

=item * A Parse Tree Setup Phase, which occurs during
the call of the recognizer's C<value()> method
for that parse tree.
It is followed by

=item * a Parse Tree Traveral Phase.

=back

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

=head1 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.

=head1 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.

=head1 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.

=head1 Copyright and License

=for Marpa::R2::Display
ignore: 1

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

=for Marpa::R2::Display::End

=cut

# Local Variables:
#   mode: cperl
#   cperl-indent-level: 4
#   fill-column: 100
# End:
# vim: expandtab shiftwidth=4: