.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Marpa::R2::Changes 3pm"
.TH Marpa::R2::Changes 3pm "2015-03-06" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Marpa::R2::Changes \- Differences between Marpa::R2 and Marpa::XS
.SH "About this document"
.IX Header "About this document"
This document describes the incompatible
differences between Marpa::XS
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 writing new applications for Marpa::R2,
and for readers migrating Marpa::XS applications
and tools to Marpa::R2.
.SH "Changes"
.IX Header "Changes"
.SS "Additional reserved symbol names"
.IX Subsection "Additional reserved symbol names"
Marpa::XS reserved, for its internal use, all symbol names
ending with the right square bracket ("\f(CW\*(C`]\*(C'\fR\*(L").
In addition,
Marpa::RS reserved symbols ending 
with the right parenthesis (\*(R"\f(CW\*(C`)\*(C'\fR\*(L"),
the right angle bracket (\*(R"\f(CW\*(C`>\*(C'\fR\*(L"),
and the right curly bracket (\*(R"\f(CW\*(C`}\*(C'\fR").
Any other valid Perl string remains an acceptable
symbol name.
.SS "The return value of the \fIread()\fP method has changed"
.IX Subsection "The return value of the read() method has changed"
The return value of
the Marpa::R2 recognizer's \f(CW\*(C`read()\*(C'\fR method differs from its Marpa::XS
equivalent.
In Marpa::XS it returned the number of distinct
terminals (by symbol \s-1ID\s0) allowed in the next 
\&\f(CW\*(C`read()\*(C'\fR.
In Marpa::R2 it returns the number of recognizer
events that occurred during the read.
Examples of recognizer events are exhaustion,
the Earley sets exceeding a designated \*(L"warning\*(R"
level,
and other circumstances settable by the user.
For more detail,
see the documentation of recognizer's
\&\f(CW\*(C`read\*(C'\fR method.
.SS "Rule \s-1LHS\s0's are no longer a source of action names"
.IX Subsection "Rule LHS's are no longer a source of action names"
In Marpa::XS, if there was no explicit action name for a rule, Marpa
would try to find a closure that had the same name as the rule's
\&\s-1LHS. \s0 The use of rule \s-1LHS\s0's as
action names had a potential for
unpleasant surprises.
A surprise could occur if the rule's \s-1LHS\s0 coincided with
a function name without the prorgrammer realizing or intending it.
This kind of 'action at a distance' bug can be very hard to detect
and trace.
.PP
It was originally thought that implicitly using the \s-1LHS\s0 as the name
of an action would be convenient enough to outweigh the dangers.
But in fact,
this feature wound up being little used.  And accidental
resolution via a rule \s-1LHS\s0 was a danger for all users, whether they
used the feature or not.  For these reasons, as well as
potential optimization and efficiency considerations, Marpa::R2 no longer
does implicit action resolution using a rule \s-1LHS.\s0
.SS "Different rules with the same rank now appear in arbitrary order"
.IX Subsection "Different rules with the same rank now appear in arbitrary order"
In ranking parse trees,
if two rule instances are for different
rules
but have the same rule rank,
they will now appear in arbitrary order.
This is probably the behavior that programmers
have always expected.
.PP
In Marpa::XS, when the \f(CW\*(C`null_ranking\*(C'\fR named
argument of rules was in use for one of the rules,
specific guarantees were made for the order
in some of the cases.
The intent was to be orthogonal with the guarantees
made for the ranking of null variants within the
same rule.
These additional guarantees
proved useless in practice,
cumbersome to implement,
and, when documented, opaque and unintuitive.
In Marpa::R2 they have been dropped.
.SS "Null actions now come from the rules"
.IX Subsection "Null actions now come from the rules"
In Marpa::XS null actions were specified by symbol.
This created a dual semantics \*(-- one for non-nulled rules,
and another for nulled rules.   The conventions and
behaviors of the two semantics were quite dissimilar.
The rules for their coordination were complicated,
and it was possible for a programmer
expecting one semantics, to be surprised by a result from
the other.
.PP
In Marpa::R2 the semantics of nulled rules is the same
as that of non-nulled rules,
and the semantics of nulled symbols comes from the semantics
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 Marpa::R2::NAIF::Semantics::Null.
.SS "Actions can now be constants"
.IX Subsection "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 that constant, except that it is more efficient.
.PP
Perl cannot reliably distinguish between non-existent symbols and symbols
whose value is \f(CW\*(C`undef\*(C'\fR,
so constants whose value is \f(CW\*(C`undef\*(C'\fR are not allowed.
The \f(CW\*(C`::undef\*(C'\fR reserved action name can be used instead.
.ie n .SS "Actions names beginning with """"::"""" are reserved"
.el .SS "Actions names beginning with ``\f(CW::\fP'' are reserved"
.IX Subsection "Actions names beginning with ""::"" are reserved"
Action names which start with "\f(CW\*(C`::\*(C'\fR\*(L" are reserved.
\&\*(R"\f(CW\*(C`::undef\*(C'\fR" is a safe way of specify a constant whose
value is \f(CW\*(C`undef\*(C'\fR.
Use of a reserved name which has not yet been defined causes
an exception to be thrown.
.ie n .SS "The ""default_null_value"" named argument for grammars has been removed"
.el .SS "The ``default_null_value'' named argument for grammars has been removed"
.IX Subsection "The default_null_value named argument for grammars has been removed"
Symbols no longer have null values, so the \*(L"default_null_value\*(R"
named argument of grammars has been removed.
.ie n .SS "The ""null_value"" symbol property has been removed"
.el .SS "The ``null_value'' symbol property has been removed"
.IX Subsection "The null_value symbol property has been removed"
Symbols no longer have null values.
Use of the \f(CW\*(C`null value\*(C'\fR symbol property
now causes an exception.
.SS "The token value argument of \fIread()\fP has changed"
.IX Subsection "The token value argument of read() has changed"
The Marpa::R2 recognizer's \f(CW\*(C`read()\*(C'\fR method differs from its Marpa::XS
equivalent.
In Marpa::R2, If \f(CW\*(C`read()\*(C'\fR's token value argument is
omitted, then the value of the token will be a Perl \f(CW\*(C`undef\*(C'\fR.
If \f(CW\*(C`read()\*(C'\fR's
token value is given explicitly, then that explicit value will be
the value of the token.  In particular, an explicit \f(CW\*(C`undef\*(C'\fR token
value argument will behave differently from an omitted token value
argument.  For details, see the documentation of recognizer's
\&\f(CW\*(C`read\*(C'\fR method.
.ie n .SS "The token value argument of ""alternative()"" has changed"
.el .SS "The token value argument of \f(CWalternative()\fP has changed"
.IX Subsection "The token value argument of alternative() has changed"
The Marpa::R2 recognizer's \f(CW\*(C`alternative()\*(C'\fR 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
Perl \f(CW\*(C`undef\*(C'\fR,
then the value of the token will be a Perl \f(CW\*(C`undef\*(C'\fR.
If alternative's
token value argument is reference to \f(CW\*(C`undef\*(C'\fR, then the value
of the token is a Perl \f(CW\*(C`undef\*(C'\fR.  For details, see the documentation
of the \f(CW\*(C`alternative\*(C'\fR method.
.SS "\fIMarpa::R2::Recognizer::value()\fP does not accept named arguments"
.IX Subsection "Marpa::R2::Recognizer::value() does not accept named arguments"
In the Marpa::XS recognizer, the \f(CW\*(C`new()\*(C'\fR, \f(CW\*(C`set()\*(C'\fR and \fIvalue()\fR methods
all accepted named arguments.  As of Marpa::R2, the \f(CW\*(C`value()\*(C'\fR method
will no longer do so.
.PP
Allowing named arguments for the \f(CW\*(C`value()\*(C'\fR 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 \f(CW\*(C`value()\*(C'\fR 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.
.PP
Eliminating named arguments from the \f(CW\*(C`value()\*(C'\fR method eliminates a
variety of special cases and, as a result, the documentation of the
\&\f(CW\*(C`value()\*(C'\fR method is now simpler, shorter and clearer.  Anything that
could be done by providing named arguments to the \f(CW\*(C`value()\*(C'\fR method
can be done more using the recognizer's \f(CW\*(C`set()\*(C'\fR method, and the code
will be clearer for it.
.SS "Marpa's grammar rewriting is now invisible"
.IX Subsection "Marpa's grammar rewriting is now invisible"
Internally, Marpa rewrites its grammars.
In Marpa::XS, most details of these rewrites were
invisible, but not all.
In Marpa::R2, all internal rules and symbols
are now completely
invisible to the user,
even in the tools for debugging grammars.
.SS "By default, the non-LHS symbols are the terminals"
.IX Subsection "By default, the non-LHS symbols are the terminals"
Traditionally, a symbol has been a terminal if
it is not on the \s-1LHS\s0 of any rule, and vice versa.
This is now the default in Marpa::R2,
replacing the more complicated, and less intuitive,
scheme that was in Marpa::XS.
Marpa::R2 still allows the user to
use any non-nulling symbol as a terminal,
including those symbols that appear on the \s-1LHS\s0
of a rule,
but this is now an option,
and never the default.
For more, see
\&\*(L"Terminal symbols\*(R" in Marpa::R2::NAIF::Grammar.
.SS "The lhs_terminals grammar named argument has been eliminated"
.IX Subsection "The lhs_terminals grammar named argument has been eliminated"
The lhs_terminals named argument of grammar objects implemented
what is now the default behavior.
Since it no longer performs a function,
its use is now a fatal error.
.SS "Nulling symbols cannot be terminals"
.IX Subsection "Nulling symbols cannot be terminals"
In Marpa::XS, it was possible for a symbol to be both
nulling and a terminal.
In practice
that meant
that the symbol was nulling,
but that, on input,
that property could be overriden,
and a specific instance of the nulling symbol
could be made non-nulling.
This behavior was worse than useless and non-intuitive \*(--
it was dangerous and logically inconsistent.
.PP
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
is the \s-1LHS\s0 of two rules, one empty,
and the other rule with a \s-1RHS\s0 consisting of exactly one
terminal symbol.
.SS "A sequence must have a unique \s-1LHS\s0"
.IX Subsection "A sequence must have a unique LHS"
The \s-1LHS\s0 of a sequence rule
may not be on the \s-1LHS\s0 of any other
rule, whether another sequence rule, or a \s-1BNF\s0 rule.
This
is not as severe a restriction as it might sound \*(--
while sequences cannot share the same \s-1LHS\s0 with other
rules directly, they can do so indirectly.
For details, see
\&\*(L"Duplicate rules\*(R" in Marpa::R2::NAIF::Grammar.
.PP
In Marpa::XS, the definition of when a sequence
was a duplicate was more liberal,
but it was also complicated and non-intuitive.
The new definition is simpler and more
intuitive, and its greater restrictiveness
is easy to work around.
.SS "The terminal status of a symbol is locked once set"
.IX Subsection "The terminal status of a symbol is locked once set"
Once a symbol is marked as a terminal or a non-terminal,
its terminal status cannot be changed.
We doubt this will affect any actual applications.
It would only affect an application
that changes symbols from their default status
to non-terminal,
and then only if they attempted to mark the same symbol
as a terminal at another point.
Few Marpa::R2 applications change symbols from
their default terminal status,
and none to my knowledge mark symbols as non-terminals.
.SS "Evaluation of infinite loops has been changed"
.IX Subsection "Evaluation of infinite loops has been changed"
Infinite loops (cycles) are still, by default, fatal errors.
For those considering programming with them,
and evaluating parses from grammars with cycles,
the semantics of cycles is now more closely specified.
For details of the new semantics,
see Marpa::R2::NAIF::Semantics::Infinite.
.SS "The range of values allowed for ranks has been clarified"
.IX Subsection "The range of values allowed for ranks has been clarified"
Symbols and rules have numeric ranks.
Previously, no mention was made of range of values allowed.
This is implemented-defined,
except that the magnitudes
of the ends of the range
will always be
at least
the 28th power of 2, less 1.
That is,
numbers in the range between
\&\-134,217,727 and 134,217,727 will always be
allowed as ranks.
.SH "Copyright and License"
.IX Header "Copyright and License"
.Vb 5
\&  Copyright 2014 Jeffrey Kegler
\&  This file is part of Marpa::R2.  Marpa::R2 is free software: you can
\&  redistribute it and/or modify it under the terms of the GNU Lesser
\&  General Public License as published by the Free Software Foundation,
\&  either version 3 of the License, or (at your option) any later version.
\&
\&  Marpa::R2 is distributed in the hope that it will be useful,
\&  but WITHOUT ANY WARRANTY; without even the implied warranty of
\&  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
\&  Lesser General Public License for more details.
\&
\&  You should have received a copy of the GNU Lesser
\&  General Public License along with Marpa::R2.  If not, see
\&  http://www.gnu.org/licenses/.
.Ve