Debian Codegraph @

pod/Deprecated/NAIF/Semantics/Phases.pod

raw
1 # Copyright 2022 Jeffrey Kegler
2 # This file is part of Marpa::R2. Marpa::R2 is free software: you can
3 # redistribute it and/or modify it under the terms of the GNU Lesser
4 # General Public License as published by the Free Software Foundation,
5 # either version 3 of the License, or (at your option) any later version.
6 #
7 # Marpa::R2 is distributed in the hope that it will be useful,
8 # but WITHOUT ANY WARRANTY; without even the implied warranty of
9 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10 # Lesser General Public License for more details.
11 #
12 # You should have received a copy of the GNU Lesser
13 # General Public License along with Marpa::R2. If not, see
14 # http://www.gnu.org/licenses/.
15
16 =head1 NAME
17
18 Marpa::R2::Deprecated::NAIF::Semantics::Phases - Details of NAIF parse evaluation
19
20 =head1 THE NAIF INTERFACE IS DEPRECATED
21
22 This document describes the NAIF interface,
23 which is deprecated.
24 PLEASE DO NOT USE IT FOR NEW DEVELOPMENT.
25
26 =head1 Overview of the semantic phases
27
28 This document deals with Marpa's low-level NAIF interface.
29 If you are new to Marpa,
30 or are not sure which interface you are interested in,
31 or do not know what the Named Argment InterFace (NAIF) is,
32 you probably want to look instead at
33 L<the document on semantics for the SLIF
34 interface|Marpa::R2::Semantics>.
35
36 Most applications will find that the order in which
37 Marpa's NAIF executes its semantics "just works".
38 This document describes that order in detail.
39 These details can matter in some applications,
40 for example, those which exploit side effects.
41 And some readers may also find this background material
42 to be helpful.
43
44 An advanced document,
45 this is written on the assumption that the more low-level NAIF interface
46 is in use.
47 The SLIF uses the same code as the NAIF for evaluation
48 and works in the same way,
49 except that it hides even more of these details from the user.
50
51 =head1 Parse trees, parse results and parse series
52
53 As a reminder,
54 when the semantics are applied to a parse tree,
55 they produce a value called a B<parse result>.
56 Because Marpa allows ambiguous parsing,
57 each parse can produce a B<parse series> --
58 a series of zero or more parse trees,
59 each with its own parse result.
60 The first call to the
61 L<the recognizer's C<value>
62 method|Marpa::R2::Deprecated::NAIF::Recognizer/"value()">
63 after the recognizer is created is the
64 start of the first parse series.
65 The first parse series continues until there is
66 a call to the
67 L<the C<reset_evaluation>
68 method|Marpa::R2::Deprecated::NAIF::Recognizer/"reset_evaluation()">
69 or until the recognizer is destroyed.
70 Usually, an application is only interested in a single
71 parse series.
72
73 When the
74 L<C<reset_evaluation>|Marpa::R2::Deprecated::NAIF::Recognizer/"reset_evaluation()">
75 method
76 is called
77 for a recognizer, it begins a new parse series.
78 The new parse series continues until
79 there is another
80 call to the
81 L<the C<reset_evaluation>
82 method|Marpa::R2::Deprecated::NAIF::Recognizer/"reset_evaluation()">,
83 or until the recognizer is destroyed.
84
85 =head1 Summary of the phases
86
87 While processing a parse series, we have:
88
89 =over
90
91 =item * A Series Setup Phase, which occurs during
92 the first call of the recognizer's C<value> method
93 for that series.
94 It is followed by
95
96 =item * the processing of zero or more parse trees.
97
98 =back
99
100 While processing a parse tree, we have:
101
102 =over
103
104 =item * A Tree Setup Phase, which occurs during
105 the call of the recognizer's C<value> method
106 for that parse tree.
107 It is followed by
108
109 =item * a Tree Traveral Phase.
110
111 =back
112
113 B<Node Evaluation Time>
114 is the Tree Traversal Phase, as seen from the point of view of
115 each rule node. It is not a separate phase.
116
117 =head1 Series Setup Phase
118
119 During the Series Setup Phase
120 all value action names are resolved to
121 value actions --
122 constants
123 or rule evaluation closures.
124 The rule evaluation closures are never called in the Series Setup Phase.
125 They will be called later,
126 in the Tree Traversal Phase.
127 Also, during the Series Setup Phase,
128 the logic which
129 ranks parse trees is executed.
130
131 =head1 Tree Setup Phase
132
133 In the Tree Setup Phase,
134 the per-parse-tree variable is created.
135 If a constructor was found for the C<action_object>,
136 it is run at this point, and the per-parse-tree variable is
137 its return value.
138 Exactly one Tree Setup Phase occurs
139 for each parse tree.
140
141 =head1 Tree Traversal Phase
142
143 During the Tree Traversal Phase,
144 the rule evaluation closures are called.
145 Node Evaluation Time is the Tree Traversal Phase,
146 as seen from the point of view of the individual nodes of the parse tree.
147
148 =head1 Copyright and License
149
150 =for Marpa::R2::Display
151 ignore: 1
152
153 Copyright 2022 Jeffrey Kegler
154 This file is part of Marpa::R2. Marpa::R2 is free software: you can
155 redistribute it and/or modify it under the terms of the GNU Lesser
156 General Public License as published by the Free Software Foundation,
157 either version 3 of the License, or (at your option) any later version.
158
159 Marpa::R2 is distributed in the hope that it will be useful,
160 but WITHOUT ANY WARRANTY; without even the implied warranty of
161 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
162 Lesser General Public License for more details.
163
164 You should have received a copy of the GNU Lesser
165 General Public License along with Marpa::R2. If not, see
166 http://www.gnu.org/licenses/.
167
168 =for Marpa::R2::Display::End
169
170 =cut
171
172 # Local Variables:
173 # mode: cperl
174 # cperl-indent-level: 4
175 # fill-column: 100
176 # End:
177 # vim: expandtab shiftwidth=4: