Permalink
Browse files

Documentation

  • Loading branch information...
1 parent 3a9d6d2 commit 9a5a2e14223ad5ed78018e3c7f5af413600450bf Jeffrey Kegler committed May 23, 2012
Showing with 32 additions and 64 deletions.
  1. +32 −64 r2/pod/Changes.pod
View
@@ -25,8 +25,8 @@ and Marpa::R2.
(Differences that do not give rise to incompatibility
are outside of its scope.)
It is intended for readers already familiar with Marpa::XS,
-who are either writing new applications for Marpa::R2.
-It is also intended to help readers migrating Marpa::XS applications
+who are writing new applications for Marpa::R2,
+and for readers migrating Marpa::XS applications
and tools to Marpa::R2.
=head1 CHANGES
@@ -49,15 +49,17 @@ of the nulled rules.
This requires rule evaluation closures to be aware
they might be called for nulled rules.
But it greatly simplifies the semantics conceptually.
+For more detail, see L<Marpa::R2::Semantics::Null>.
=head2 Actions can now be constants
If an action name resolves to a constant, that constant is the action.
The effect is the same as if the action name resolved to a function
-that returned the same constant, except that it is more efficient.
+that returned that constant, except that it is more efficient.
Perl cannot reliably distinguish between non-existent symbols and symbols
-whose value is C<undef>, so constants whose value C<undef> are not allowed.
+whose value is C<undef>,
+so constants whose value is C<undef> are not allowed.
The C<::undef> reserved action name can be used instead.
=head2 Actions names beginning with "C<::>" are reserved
@@ -76,29 +78,30 @@ named argument of grammars has been removed.
=head2 The "symbols" named argument for grammars has been removed
-In Marpa::XS the "symbols" named argument was used to specify null
+In Marpa::XS the C<symbols> named argument was used to specify null
values for symbols. It was also an alternate way of marking symbols
-as terminals. Symbols no longer have null values and, as an alternate
+as terminals. Symbols no longer have null values,
+and an alternate
and more cumbersome way to marking terminals is not worth cluttering
-the documentation. Use of the "symbols" named argument now causes
+the documentation. Use of the C<symbols> named argument now causes
an exception.
=head2 The token value argument of read() has changed
-The Marpa::R2 recognizer's read() method differs from its Marpa::XS
-equivalent. In Marpa::R2, If read()'s token value argument is
-omitted, then the token value will be a "whatever" value. If read()'s
+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
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
argument. For details, see L<the documentation of recognizer's
C<read> method|Marpa::R2::Recognizer/"read">.
-=head2 The token value argument of alternative() has changed
+=head2 The token value argument of C<alternative()> has changed
-The Marpa::R2 recognizer's alternative() method differs from its
+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
+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
token value argument is reference to C<undef>, then the value
@@ -107,22 +110,22 @@ of the C<alternative> method|Marpa::R2::Advanced::Models/"alternative">.
=head2 Marpa::R2::Recognizer::value() does not accept named arguments
-n the Marpa::XS recognizer, the new(), set() and value() methods
-all accepted named arguments. As of Marpa::R2, the value() method
+n the Marpa::XS recognizer, the C<new()>, C<set()> and value() methods
+all accepted named arguments. As of Marpa::R2, the C<value()> method
will no longer do so.
-Allowing named arguments for the value() was a holdover from a
+Allowing named arguments for the C<value()> was a holdover from a
previous interface, which also seemed like it might be a convenience.
-But, since it was even more important that the value() method be
+But, since it was even more important that the C<value()> method be
convenient as the termination test controlling a loop over the parse
results, a lot of special logic was added to deal with arguments
which only made sense before the first pass of the loop, etc., etc.
-Eliminating named arguments from the value() method eliminates a
+Eliminating named arguments from the C<value()> method eliminates a
variety of special cases and, as a result, the documentation of the
-value() method is now simpler, shorter and clearer. Anything that
-could be done by providing named arguments to the value() method
-can be done more using the recognizer's set() method, and the code
+C<value()> method is now simpler, shorter and clearer. Anything that
+could be done by providing named arguments to the C<value()> method
+can be done more using the recognizer's C<set()> method, and the code
will be clearer for it.
=head2 Marpa's grammar rewriting is now invisible
@@ -141,18 +144,10 @@ 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.
-In this context, a "whatever" value is arbitrary,
-in one of the senses of that word.
-Specifically,
-a "whatever" value cannot be relied on
-to exhibit any property.
-For example, a "whatever" value
-may be constant,
-or it may vary from instance to instance.
-If and when it varies, it may do so randomly
-or according to an arbitrary pattern.
+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.
@@ -164,38 +159,10 @@ 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,
+sense of the typical application mix,
this one change makes
Marpa::R2 20% faster than Marpa::XS.
-Users need to make sure that Marpa::R2 code does not
-expect that the default semantics will produce an
-Perl C<undef>.
-
-=head2 A token value of undefined now means "whatever"
-
-Similarly,
-if the token value of a
-L<C<read>|Marpa::R2::Recognizer/"read">
-call or an
-L<C<alternative>|Marpa::R2::Recognizer/"alternative">
-call is a Perl C<undef>,
-that does
-B<not> necessary mean that the value of the
-token will be a Perl
-C<undef> value.
-Instead, it means that
-the token can have an "whatever" value.
-
-As a consequence,
-it is no longer possible in Marpa::R2 to specify
-a Perl C<undef> directly as a token value.
-Applications which want this
-must use some sort of translation scheme.
-The most general approach to deal with this
-is to have all token values be references,
-and to write actions which dereference token values.
-
=head2 By default, the non-LHS symbols are the terminals
Traditionally, a symbol has been a terminal if
@@ -233,8 +200,7 @@ could be made non-nulling.
This behavior was worse than useless and non-intuitive --
it was dangerous and logically inconsistent.
-Marpa::R2,
-will not allow
+Marpa::R2 will not allow
a nulling symbol to be used as a terminal.
To the extent that the Marpa::XS behavior made sense,
it can be duplicated by creating a symbol which
@@ -251,6 +217,8 @@ This
is not as severe a restriction as it might sound --
while sequences cannot share the same LHS with other
rules directly, they can do so indirectly.
+For details, see
+L<Marpa::R2::Grammar/"Duplicate rules">.
In Marpa::XS, the definition of when a sequence
was a duplicate was more liberal,

0 comments on commit 9a5a2e1

Please sign in to comment.