Disallow "whatever" tokens above Thin interface: Doc changes

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<undef>,
-the token has a "whatever" value.
+the token has an undefined value.
 
 The third argument to the C<alternative> method is a token
 length.

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<undef>.
 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<read()> method differs from its Marpa::XS
-equivalent.  In Marpa::R2, If C<read()>'s token value argument is
-omitted, then the token value will be a "whatever" value.  If C<read()>'s
+equivalent.
+In Marpa::R2, If C<read()>'s token value argument is
+omitted, then the token value will be an undefined value.
+If C<read()>'s
 token value is given explicitly, then that explicit value will be
 the value of the token.  In particular, an explicit C<undef> token
 value argument will behave differently from an omitted token value
@@ -172,8 +173,10 @@ C<read> method|Marpa::R2::Recognizer/"read">.
 The Marpa::R2 recognizer's C<alternative()> 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<undef>, then the token has a "whatever" value.  If alternative's
+Marpa::XS.
+If alternative's token value argument is omitted or a
+C<undef>, then the token has an undefined value.
+If alternative's
 token value argument is reference to C<undef>, then the value
 of the token is a Perl C<undef>.  For details, see L<the documentation
 of the C<alternative> 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<undef>.
-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

r2/pod/Marpa_R2.pod

@@ -335,7 +335,7 @@ it can be omitted.
 In the calculator example, the values of the
 "C<Add>"
 and "C<Multiply>" 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<default_action> 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<undef>.
 
 =head1 Example 2: an ambiguous parse
 

r2/pod/Recognizer.pod

@@ -240,10 +240,7 @@ C<read> takes two arguments: a B<token name> and a B<token value>.
 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<undef>.
 For details about terminal symbols,
 see L<Marpa::R2::Grammar/"Terminals">.
 
@@ -272,14 +269,6 @@ including an attempt to C<read> a token
 into an exhausted parser,
 Marpa throws an exception.
 
-Note that passing an explicit C<undef> 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<undef>, then the token value
-is always a Perl C<undef>.
-
 =head2 set()
 
 =for Marpa::R2::Display

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<undef>.
 
-=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</"Valued and unvalued symbols">.
-
-=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<token symbol>.
 At lexing time,
 they can be assigned a B<token value>.
 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<undef>.
 
 =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<undef>.
 
 =head2 Sequence rule nodes
 
@@ -447,7 +402,7 @@ resolving an action based on that named argument.
 the C<default_action> named argument of the grammar,
 if one is defined.
 
-=item * Defaulting to a "whatever" value.
+=item * Defaulting to a Perl C<undef> value.
 
 =back