Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Documentation: t+

  • Loading branch information...
commit 82190fd0f9eae065be00d6a51f71ec3338f981b0 1 parent 4ac156d
Jeffrey Kegler authored

Showing 1 changed file with 51 additions and 69 deletions. Show diff stats Hide diff stats

  1. +51 69 r2/pod/Semantics/Null.pod
120 r2/pod/Semantics/Null.pod
Source Rendered
@@ -17,11 +17,9 @@
17 17
18 18 Marpa::R2::Semantics::Null - How Marpa evaluates null rules and symbols
19 19
20   -=head1 DESCRIPTION
  20 +=head1 OVERVIEW
21 21
22   -=head2 Nulled symbols
23   -
24   -In Marpa parses, some symbols can be nulled --
  22 +In Marpa parses, rules and symbols can be nulled --
25 23 in other words they can derive the zero-length, or null, string.
26 24 Which symbols can be, or are, nulled, depends on the grammar
27 25 and the input.
@@ -33,19 +31,37 @@ in which case the entire parse derives the null string.
33 31 A parse in which the start symbol is nulled is
34 32 called a B<null parse>.
35 33
36   -When evaluating a parse, the symbols are
  34 +When evaluating a parse, nulled rules and symbols are
37 35 assigned values as described
38 36 L<in the semantics document|Marpa::R2::Semantics>.
39 37 This document provides additional detail on the assignment
40 38 of values to nulled symbols.
41 39
42   -The B<null value of a symbol> comes from its rules.
  40 +=head1 OVERVIEW
  41 +
  42 +=head2 Null values come from rules
  43 +
  44 +All null values for symbols come from rules with that symbol
  45 +on their LHS.
  46 +For a symbol to be nulled, it must be on the LHS of at least one
  47 +nullable rule.
  48 +The action of one of these nullable rules will be the action for
  49 +the nulled symbol.
43 50
44   -Marpa optimizes for "whatever" null values.
45   -Null values often are not used for anything,
46   -and in those case applications that
47   -allow "whatever" null values
48   -can have better performance.
  51 +If the action is a constant, then that constant is the value
  52 +of the nulled symbol.
  53 +If the action is a rule evaluation closure,
  54 +then that closure is called with no child arguments,
  55 +and the closure's result is the value of the nulled symbol.
  56 +
  57 +It may be that more than one nullable rule has that symbol on
  58 +its LHS, and and these rules have different action names.
  59 +In that case, the action for the empty rule is the one which
  60 +applies.
  61 +It is a fatal error if the nullable rules for a LHS symbol
  62 +have different action names, and none of them is an empty rule.
  63 +A simple way to fix this problem is create an empty rule
  64 +that decide the semantics to be applied to nulled symbols.
49 65
50 66 =head2 Null subtrees
51 67
@@ -73,45 +89,6 @@ and even a dynamic,
73 89 "semantics of nothing",
74 90 as described below.
75 91
76   -=head2 Nullable Rules
77   -
78   -Some BNF rules and sequences may sometimes be nulled,
79   -and sometimes not.
80   -This offer some potential for suprising the programmer,
81   -because their value comes from two different sources,
82   -depending on whether they are nulled or not.
83   -
84   -When a rule is nulled, its value is the null value
85   -of its B<LHS symbol>.
86   -When a rule is not nulled,
87   -it value comes from the action for the rule.
88   -It's up to the
89   -application to ensure that
90   -the nulled value of the LHS symbol,
91   -and the semantics of the visible rule,
92   -"work together" in a way that makes sense
93   -in the context of
94   -the grammar.
95   -
96   -=head2 Nullable Sequences
97   -
98   -What was just said about nullable rules applies to nullable seqeunces.
99   -Sequence rules are nullable rules
100   -if they have a C<min> rule property of 0.
101   -When a sequence contains zero items, it must derive the zero-length string,
102   -and the sequence is a nulled rule.
103   -
104   -Nullable sequence rules behave in the same way
105   -as nullable BNF rules.
106   -When the a nullable sequence rule is nulled,
107   -its semantics comes from the null value for its left hand side symbol.
108   -When the a nullable sequence rule is not nulled,
109   -its semantics come from the rule.
110   -If a nulled sequence is in a nulled subtree,
111   -but that nulled sequence
112   -is not the topmost rule of that subtree,
113   -then its semantics will be completely ignored.
114   -
115 92 =head1 EXAMPLE
116 93
117 94 As already stated,
@@ -129,8 +106,7 @@ perltidy: '-dcsc -sil=0'
129 106 }
130 107
131 108 sub R {
132   - shift;
133   - return 'R(' . ( join q{;}, map { $_ // '[ERROR!]' } @_ ) . ')';
  109 + return 'R(): I will never be called';
134 110 }
135 111
136 112 sub S {
@@ -138,8 +114,8 @@ perltidy: '-dcsc -sil=0'
138 114 return 'S(' . ( join q{;}, map { $_ // '[ERROR!]' } @_ ) . ')';
139 115 }
140 116
141   - sub X { return $_[1]; }
142   - sub Y { return $_[1]; }
  117 + sub X { return 'X(' . $_[1] . ')'; }
  118 + sub Y { return 'Y(' . $_[1] . ')'; }
143 119
144 120 our $null_A = 'null A';
145 121 our $null_B = 'null B';
@@ -206,8 +182,8 @@ ignore: 1
206 182
207 183 0: Visible Rule: S := L R
208 184 1: Visible Rule L := A B X
209   - 1.1: Nulled Node, Symbol A
210   - 1.2: Nulled Node, Symbol B
  185 + 1.1: Nulled Symbol A
  186 + 1.2: Nulled Symbol B
211 187 1.3: Token, Value is 'x'
212 188 2: LHS of Nulled Rule, Symbol R
213 189
@@ -229,27 +205,33 @@ In the output we see
229 205 =over
230 206
231 207 =item * The null value for symbol 1.1: "C<null A>".
  208 +This comes from the empty rule for C<A>.
232 209
233 210 =item * The null value for symbol 1.2: "C<null B>".
  211 +This comes from the empty rule for C<B>.
234 212
235 213 =item * The token value for symbol 1.3: "C<x>".
236 214
237   -=item * An application of the semantic Perl closure for rule 1.
  215 +=item * An application of the semantic Perl closure for the rule
  216 +C<L := A B X>.
238 217
239 218 =item * The null value for rule 2: "C<null R>".
  219 +This comes from the empty rule for C<R>.
240 220
241   -=item * An application of the semantic Perl closure for rule 0.
  221 +=item * An application of the semantic Perl closure for the rule
  222 +C<S := L R>
242 223
243 224 =back
244 225
245 226 We do not see any output
246   -for symbols 2.1, 2.2, or 2.3 because they were not topmost
  227 +for symbols
  228 +2.1 (C<A>),
  229 +2.2 (C<B>),
  230 +or 2.3 (C<Y>)
  231 +because they were not topmost
247 232 in the pruned subtree.
248   -We B<do> see the null value for the LHS of rule 2,
249   -because it is the topmost symbol.
250   -We B<do not> see an application of the semantic Perl closure for rule 2,
251   -because nulled rules take their value from the null value of their LHS,
252   -and not from the rule semantics.
  233 +We B<do not> see an application of the rule evaluation closure for rule C<R := A B Y>,
  234 +because there is an empty rule for C<R>, and that takes priority.
253 235
254 236 =head1 ADVANCED
255 237
@@ -281,16 +263,16 @@ Determine which of the application's nullable symbols have a dynamic semantics.
281 263 Call these the B<dynamic nullables>.
282 264
283 265 =item *
284   -Let the C<null_value> property of every dynamic nullable be a hash key.
  266 +Let the action of the empty rule with the dynamic nullables on their LHS
  267 +be a constant that can be used as a hash key.
285 268
286 269 =item *
287 270 For every rule with a dynamic nullable on its right hand side,
288   -write the rule's semantic Perl closure
  271 +write the rule evaluation closure
289 272 so that it looks up that hash key
290 273 in a hash whose values are Perl closures.
291   -
292   -=item *
293   -The Perl closure can then use an arbitrarily complex semantics for
  274 +The closures found by hash lookup
  275 +can then use an arbitrarily complex semantics for
294 276 calculating the value of the dynamic nullable.
295 277
296 278 =back

0 comments on commit 82190fd

Please sign in to comment.
Something went wrong with that request. Please try again.