- ABOUT THIS DOCUMENT
- COPYRIGHT AND LICENSE
Marpa::R2::Changes - Differences between Marpa::R2 and Marpa::XS
This document describes the differences between Marpa::XS and Marpa::R2. 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 and tools to Marpa::R2.
In Marpa::XS, the default value for rules, null values, and token values, was a Perl
undef. In Marpa::R2, rules and null values now default to an arbitrary value. In this context, "arbitrary" means is that the value may not be relied on, and may vary from instance to instance. Arbitrary values will usually only be suitable in cases where the application simply does not care what is returned.
The motivation for the change is efficiency. If Marpa::R2 knows that a value on evaluation stack is allowed to be arbitrary, it implements the logic to create it as a no-op. Real applications allow arbitrary values surprisingly often, and this one change makes Marpa::R2 20% faster than Marpa::XS for typical applications.
Users should make sure that Marpa::R2 code does not expect the default semantics will produce an Perl
Similarly, if the token value of a
read call or an
alternative call is a Perl
undef, that does not necessary mean that the value of the token will be a Perl
undef value. Instead, it means that the token can have an arbitrary value.
As a consequence, it is no longer possible in Marpa::R2 to specify a Perl
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.
Traditionally, a symbol has been a terminal if it is not on the LHS 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 LHS of a rule, but this is now an option, and never the default. For more, see "Terminal symbols" in Marpa::R2::Grammar.
The lhs_terminals named argument of grammar objects implemented what is now the default behavior. Since it no longer performs a function, it is now a fatal error.
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 that property could be overriden on input. This behavior was useless and logically inconsistent.
In Marpa::R2 it is an error if you try to make a nulling symbol into a terminal. To the extent that the old behavior made sense, it can be duplicated by creating a symbol which is the LHS of two rules, one empty, and the other rule with a RHS consisting of one symbol, a terminal.
The LHS of a sequence rule may not be on the LHS of any other rule, whether another sequence rule, or a BNF rule. 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.
In Marpa::XS, the definition of when a sequence was the duplicate was more liberal. But this meant that issues of whether sequences were duplicates if they differed only in their separators or their minimum counts. And it meant that some BNF rules which were the equivalent of instances of sequence rules were considered duplicates, while others were not. The new definition is much simpler and more intuitive, and its greater restrictiveness is easy to work around.
Copyright 2012 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/.