Marpa::R3::Semantics::Phases - SLIF recognizer phases
This document describes in detail the sequence of events in the SLIF recognizer. It serves two purposes.
Full detail of the sequence of events inside the SLIF recognizer is not usually necessary. Applications usually find that things "just work". But some application do depend on the details. These include
Because Marpa allows ambiguous parsing, each parse can produce a a series of zero or more parse trees, -- a parse series. Each parse tree has its own parse result. Because the parse may fail, there may be zero parse trees in a parse series. Because a parse may be ambiguous, there may be more than one parse tree in a parse series.
The SLIF allows the recognizer to be run several times on the same virtual input stream. Each of these runs is a separate parse series. Most applications use only one parse series.
The call to the SLIF recognizer's
read() method is the start of the first parse series.
The first parse series continues until there is a call to the
series_restart() method or until the recognizer is destroyed.
Each call of the
series_restart() method starts a new parse series.
Few applications need to use more than a single parse series. But they are useful in some specialized applications. Starting a new parse series allows the applications to change some settings and to extend the input. Specifically,
endsetting. For details, see "Recognizer settings" in Marpa::R3::Scanless::R.
A SLIF recognizer is always in one of three phases:
In these documents, phase and subphase names are capitalized for clarity.
Reading and Evaluation Phases are always part of a parse series. The Initial Phase is never part of any parse series.
The Initial Phase of a SLIF recognizer begins when the recognizer is created with the a call of the
It ends when the
read() method is called.
It will also end,
if the recognizer is destroyed,
but most applications will want to continue into the next phases.
There is always exactly one Initial Phase for every recognizer.
The Initial Phase is not part of any parse series.
Very little can happen in the Initial Phase,
but it is possible to change some recognizer settings using the
The Reading Phase starts when a parse series starts,
with either a call to the
read() method or a call to the
The Reading Phase ends when the first of the following occurs:
value()method is called for this SLIF recognizer. This is the most common case.
The last two cases are unusual.
Applications almost always want to continue the parse series into the Evaluation Phase by calling the
read() method can be called only once for a SLIF recognizer.
while a Reading Phase continues,
resume() method may be called multiple times to continue reading input.
resume() method should only be called during the Reading Phase of a parse series.
A Reading Phase is always part of a parse series. There is always exactly one Reading Phase for every parse series.
The Evaluation Phase begins with a recognizer's first call to the SLIF's
It ends when the recognizer is destroyed,
or when the SLIF's
series_restart() method is called for that recognizer.
If a parse series ends before the
value() method is called,
there is no Evaluation Phase.
value() method may be called more than once during the Evaluation Phase.
The second and later calls of the
value() method will return the result of the next parse tree,
if there is one.
When there are no more parse trees,
value() method will return a Perl
If you call the
resume() method during an Evaluation Phase,
the behavior of Marpa::R3 is not defined.
You should not do this.
When it occurs, an Evaluation Phase is always part of a parse series. But the Evaluation Phase is optional -- a parse series may end without entering into an Evalution Phase.
The Evaluation Phase has two subphases:
Node Evaluation Time is the Tree Traversal Subphase, as seen from the point of view of each rule node. It is not a separate phase.
The Parse Tree Setup Subphase occurs during during the first call to the
value() method of every series.
If a per-parse argument was not supplied in the
the default per-parse argument is created.
in the Parse Tree Setup Subphase,
Exactly one Parse Tree Setup Subphase occurs for each parse tree.
During the Parse Tree Traversal Subphase, the rule evaluation closures are called.
Marpa::R3 is Copyright (C) 2017, Jeffrey Kegler. This module is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.1. For more details, see the full text of the licenses in the directory LICENSES. This program 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.