From 89f3bdf751f563cd5652d63edf80d68f116c0241 Mon Sep 17 00:00:00 2001 From: Jeffrey Kegler Date: Sun, 24 Feb 2013 15:31:26 -0800 Subject: [PATCH] Disallow "whatever" tokens above Thin interface: Doc changes --- r2/pod/Advanced/Models.pod | 2 +- r2/pod/Changes.pod | 38 ++++++---------------------- r2/pod/Marpa_R2.pod | 5 ++-- r2/pod/Recognizer.pod | 13 +--------- r2/pod/Semantics.pod | 51 +++----------------------------------- 5 files changed, 15 insertions(+), 94 deletions(-) diff --git a/r2/pod/Advanced/Models.pod b/r2/pod/Advanced/Models.pod index c4b230268..98fda7a0a 100644 --- a/r2/pod/Advanced/Models.pod +++ b/r2/pod/Advanced/Models.pod @@ -195,7 +195,7 @@ The first two arguments are the token type and a reference to the token value. If the reference to the token value is omitted, or is C, -the token has a "whatever" value. +the token has an undefined value. The third argument to the C method is a token length. diff --git a/r2/pod/Changes.pod b/r2/pod/Changes.pod index ec3ace236..e34cb52ff 100644 --- a/r2/pod/Changes.pod +++ b/r2/pod/Changes.pod @@ -139,7 +139,6 @@ The C<::undef> reserved action name can be used instead. =head2 Actions names beginning with "C<::>" are reserved Action names which start with "C<::>" are reserved. -"C<::whatever>" explicitly requests "whatever" semantics. "C<::undef>" is a safe way of specify a constant whose value is C. Use of a reserved name which has not yet been defined causes @@ -159,8 +158,10 @@ now causes an exception. =head2 The token value argument of read() has changed The Marpa::R2 recognizer's C method differs from its Marpa::XS -equivalent. In Marpa::R2, If C's token value argument is -omitted, then the token value will be a "whatever" value. If C's +equivalent. +In Marpa::R2, If C's token value argument is +omitted, then the token value will be an undefined value. +If C's token value is given explicitly, then that explicit value will be the value of the token. In particular, an explicit C token value argument will behave differently from an omitted token value @@ -172,8 +173,10 @@ C method|Marpa::R2::Recognizer/"read">. The Marpa::R2 recognizer's C method differs from its Marpa::XS equivalent. Its token value argument must now be a reference to the token value, not the token value itself, as in -Marpa::XS. If alternative's token value argument is omitted or a -C, then the token has a "whatever" value. If alternative's +Marpa::XS. +If alternative's token value argument is omitted or a +C, then the token has an undefined value. +If alternative's token value argument is reference to C, then the value of the token is a Perl C. For details, see L method|Marpa::R2::Advanced::Models/"alternative">. @@ -208,31 +211,6 @@ are now completely invisible to the user, even in the tools for debugging grammars. -=head2 The semantics now defaults to "whatever" values - -In Marpa::XS, the default value -for rules, null values, and token values, -was a Perl C. -In Marpa::R2, rules, null values and token values -now default to a "whatever" value. -A "whatever" value is guaranteed to be one of -the Perl values which is assignable to a scalar. -Otherwise, its value is unspecified. -"Whatever" values will usually only be appropriate -when the application simply does not care what -the value is. - -The motivation for the change is efficiency. -When Marpa::R2 knows that a value on its evaluation -stack is a "whatever" value, -it implements the logic to create it as a no-op. -Real applications allow "whatever" values surprisingly -often. -According to the author's -sense of the typical application mix, -this one change makes -Marpa::R2 20% faster than Marpa::XS. - =head2 By default, the non-LHS symbols are the terminals Traditionally, a symbol has been a terminal if diff --git a/r2/pod/Marpa_R2.pod b/r2/pod/Marpa_R2.pod index 09e846f72..3e9457b58 100644 --- a/r2/pod/Marpa_R2.pod +++ b/r2/pod/Marpa_R2.pod @@ -335,7 +335,7 @@ it can be omitted. In the calculator example, the values of the "C" and "C" tokens are never used, -and are allowed to default to a "whatever" value. +and are allowed to default to an undefined value. =head2 Marpa::R2::Recognizer::value @@ -496,8 +496,7 @@ Rules with no action specified for them take their semantics from the C named argument. If there is no default action for a grammar, rules with no action specified for them -return a "whatever" value -- -an arbitrary value which should not be used. +return a Perl C. =head1 Example 2: an ambiguous parse diff --git a/r2/pod/Recognizer.pod b/r2/pod/Recognizer.pod index 86243c831..a061d38e1 100644 --- a/r2/pod/Recognizer.pod +++ b/r2/pod/Recognizer.pod @@ -240,10 +240,7 @@ C takes two arguments: a B and a B. The token name is required. It must be the name of a valid terminal symbol. The token value is optional. -It defaults to a "whatever" value. -Here "whatever" means the value may vary from instance -to instance, -and cannot be relied on in any way. +It defaults to a Perl C. For details about terminal symbols, see L. @@ -272,14 +269,6 @@ including an attempt to C a token into an exhausted parser, Marpa throws an exception. -Note that passing an explicit C as the token value -argument is -quite different from omitting it. -If the token value is omitted, it is a "whatever" value, -one which could be anything. -If it is C, then the token value -is always a Perl C. - =head2 set() =for Marpa::R2::Display diff --git a/r2/pod/Semantics.pod b/r2/pod/Semantics.pod index b06d07e79..2763eecc2 100644 --- a/r2/pod/Semantics.pod +++ b/r2/pod/Semantics.pod @@ -153,45 +153,6 @@ To allow Marpa to help you to spot non-existent values, the "C<::undef>" reserved action name should be preferred for indicating a constant whose value is a Perl C. -=head2 ::whatever - -In informal terms, a "whatever" value -is one which does not matter -- -for example, because that value is never used. -Specifying values as "whatever" allows Marpa to make -certain optimizations. -For a more precise description, -see L. - -=head1 Valued and unvalued symbols - -An unvalued (or -"whatever") symbol can have any value -that is assignable to a Perl -scalar. -Other than that, -the value of an unvalued symbol is unspecified -and unpredictable. -It may be constant, or may vary from instance to instance. -If it varies it may do so randomly or according to a pattern. -"Whatever" values will usually only be appropriate for cases -where the application does not care what the value is. - -The semantics of unvalued symbols is very efficient to implement, -and by default symbols are unvalued. -The "C<::whatever>" reserved action name can be used -to explicitly specify that a rule's LHS, -and therefore the rule, is unvalued. - -A "whatever" value may happen to be identical to any other value, -and therefore "whatever" values cannot be reliably -disinguished from other -results. -For this reason, whenever a rule is unvalued, -all rules with the same LHS must also be unvalued. -Where this is not the case, -Marpa throws an exception. - =head1 Nodes =head2 Token nodes @@ -203,13 +164,7 @@ Tokens always have a B. At lexing time, they can be assigned a B. If no token value is assigned at lex time, -the token value has an "whatever" value. -A "whatever" value is one that -cannot be relied on. -It may, for example, -vary from instance to instance, -either randomly or according to an -arbitrary pattern. +the value of the token is a Perl C. =head2 Rule nodes @@ -234,7 +189,7 @@ If the action is a rule evaluation closure, its return value becomes the value of the node. If there is no action for a rule node, -the rule node has a "whatever" value. +the value of the rule node is a Perl C. =head2 Sequence rule nodes @@ -447,7 +402,7 @@ resolving an action based on that named argument. the C named argument of the grammar, if one is defined. -=item * Defaulting to a "whatever" value. +=item * Defaulting to a Perl C value. =back