# Marpa::R3 is Copyright (C) 2017, Jeffrey Kegler.
#
# This module is free software; you can redistribute it and/or modify it
# under the same terms as Perl 5.10.1. For more details, see the full text
# of the licenses in the directory LICENSES.
#
# This program is distributed in the hope that it will be
# useful, but it is provided “as is” and without any express
# or implied warranties. For details, see the full text of
# of the licenses in the directory LICENSES.

=head1 NAME

Marpa::R3::Changes - Differences between Marpa::R2 and Marpa::R3

=head1 About this document

This document describes the incompatible
differences between Marpa::R2
and Marpa::R3.
(Differences that do not give rise to incompatibility
are outside of its scope.)
It is intended for readers already familiar with Marpa::R2,
who are writing new applications for Marpa::R3,
and for readers migrating Marpa::XS applications
and tools to Marpa::R3.

=head1 Changes

=head2 "Eager" lexemes added

See L<Marpa::R3::Scanless::DSL/"eager">.

=head2 Problems with kernel Earley items in progress reports fixed

Progress reports had been misreporting some
Earley items.  The misreported items
were certain kernel Earley items
instances containing one
or more proper nullables.
By kernel Earley item, I mean an Earley item
where the dot is in the middle -- not at the beginning
and and not at the end.
In other words, kernel Earley items are items which
are not predictions, and which are not
completions.

This bug is actually quite obscure --
almost all interest in progress reports is in
completed Earley items, which were not affected.
So obscure, in fact, was this bug that
it went unnoticed in use.
It surfaced only when I reread the
code and realized that some corner cases were
not being dealt with correctly.
This bugs is now fixed.

=head2 Semantics moved from recognizer to grammar

In Marpa::R2, the semantics was not finally settled
until the C<< $recce->value() >> call.
In Marpa::R3, semantics will be fully settled in the grammar.

=head2 Options moved from recognizer to grammar

The C<exhaustion>,
C<ranking_method>,
C<rejection>,
C<semantics_package>,
and C<trace_actions>
named arguments
are grammar options in Marpa::R3.
They were
recognizer name arguments in Marpa::R2,

=head2 Actions that are Perl names must resolve to subroutines

It was a little noticed feature of Marpa::R2, that actions specified
as Perl names (like "My_Action::doit") could resolve to scalars.
In Marpa::R3 they must resolve to Perl subroutines.

=head2 Newlines now obey Perl standards

In Marpa::R3 newlines are defined as in Perl.
In Marpa::R2 newlines were recognized according to the Unicode
standard, which was a superset including
UNIX and Windows newlines.

=head2 The Stuifzand interface (PSIF) has been removed

The Stuifzand interface (PSIF), and its documentation,
have been removed.
Important in the development of Marpa,
it now has little or now usage.

=head2 The Thin interface (THIF) has been removed.

The THIF was a "thin" Perl interface.
It has been removed.

=head2 The NAIF has been removed

The NAIF was an older interface using hashes of named
variables, instead of a DSL.
It has been removed.

=head2 LATM is now the default

=head2 [name, values] is now the default action

=head2 Unicode now works in the SLIF DSL

=head2 New method g1_input_span

=head2 Context::location is now Context::g1_range

=head2 New context variable, Context::g1_span

=head2 Marpa::R2::Scanless::G named arguments removed in Marpa::R3

The C<actions>, C<action_object>, C<default_action>
and C<default_empty_action>
named arguments
of Marpa::R2::Scanless::G named arguments
have been
removed in Marpa::R3.

=head2 New Marpa::R3::Scanless::G methods

Several new methods have been added as accessors for
L0 grammars:

=over 4

=item * C<Marpa::R2::Scanless::G::l0_symbol_dsl_form()>

=item * C<Marpa::R2::Scanless::G::l0_rule_expand()>

=item * C<Marpa::R2::Scanless::G::l0_rule_ids()>

=item * C<Marpa::R2::Scanless::G::l0_rule_show()>

=item * C<Marpa::R2::Scanless::G::l0_symbol_display_form()>

=item * C<Marpa::R2::Scanless::G::l0_symbol_ids()>

=item * C<Marpa::R2::Scanless::G::l0_symbol_name()>

=item * C<Marpa::R2::Scanless::G::l0_show_rules()>

=item * C<Marpa::R2::Scanless::G::l0_show_symbols()>

=back

=head2 Marpa::R2::Scanless::G methods removed in Marpa::R3

The
C<Marpa::R2::Scanless::G::g0_rule()> method,
the C<Marpa::R2::Scanless::G::g0_rule_ids()> method,
the C<Marpa::R2::Scanless::G::g1_rule_ids()> method,
and
the C<Marpa::R2::Scanless::G::rule()> method,
discouraged in Marpa::R2,
have been eliminated in Marpa::R3.

The
C<Marpa::R2::Scanless::G::symbol_description()> method
has been removed.

=head2 Marpa::R2::Scanless::G methods changed in Marpa::R3

The following methods have been changed:

=over 4

=item * C<Marpa::R2::Scanless::G::symbol_dsl_form()>

=item * C<Marpa::R2::Scanless::G::rule_expand()>

=item * C<Marpa::R2::Scanless::G::rule_ids()>

=item * C<Marpa::R2::Scanless::G::rule_show()>

=item * C<Marpa::R2::Scanless::G::symbol_display_form()>

=item * C<Marpa::R2::Scanless::G::symbol_ids()>

=item * C<Marpa::R2::Scanless::G::symbol_name()>

=item * C<Marpa::R2::Scanless::G::show_rules()>

=item * C<Marpa::R2::Scanless::G::show_symbols()>

=back

They no longer take an argument indicating the subgrammar --
instead they always return result for the G1 grammar.
New methods have been added to return results for the L0
grammar.
For these, see
L</"New Marpa::R3::Scanless::G methods">.

=head2 Marpa::R2::Scanless::R methods renamed in Marpa::R3

For historical reasons,
the methods dealing with input and G1 parse location in Marpa::R2
often had unhelpful or misleading names.
In Marpa::R3 an attempt is being made to name
methods dealing with G1 and input parse location consistently,
and to ensure that the
G1 variants
have C<g1> somewhere in their name.
Accordingly,
C<< $slr->substring() >> has been renamed
C<< $slr->g1_literal() >>;
and
C<< $slr->current_g1_location() >>
is now
C<< $slr->g1_pos() >>.

=head2 Marpa::R2::Scanless::R methods removed in Marpa::R3

The
C<Marpa::R2::Scanless::R::event()> method,
C<Marpa::R2::Scanless::R::last_completed_range()> method,
C<Marpa::R2::Scanless::R::pause_lexeme()> method,
and the
C<Marpa::R2::Scanless::R::range_to_string()> method,
discouraged in Marpa::R2,
have been eliminated in Marpa::R3.

=head2 The per-parse constructor has been elminated

In Marpa::R2, if the semantics package has a C<new()>
method, that method was used as the constructor of
the per-parse object.
In Marpa::R3, there is no per-parse constructor.

=head2 The per-parse argument never affects the semantics package

As of Marpa::R3, the per-parse argument has no effect on
the semantics package.
In Marpa::R2, if the c<semantics_package> named argument was
not used and the per-parse argument was blessed,
then the package into which the per-parse argument was blessed
became the semantics package.

=head2 The semantic closure now always receives exactly 2 arguments

Under Marpa::R2, the semantic closure received a varying number
of arguments, depending on circumstances.
Under Marpa::R3, the semantic closure always receives exactly 
2 arguments.
The first argument is the per-parse object.
The second argument is a reference to an array containing
the values of the child nodes, in lexical order.
If there were no child nodes visible to the semantics,
then the second argument is an empty array.

=head2 

Under Marpa::R2,
the C<events()> method returned events in a specified
order, by type of event.
Under Marpa::R3, the order of events
returned by
the C<events()> method
is completely arbitrary.

=head1 COPYRIGHT AND LICENSE

=for Marpa::R3::Display
ignore: 1

  Marpa::R3 is Copyright (C) 2017, Jeffrey Kegler.

  This module is free software; you can redistribute it and/or modify it
  under the same terms as Perl 5.10.1. For more details, see the full text
  of the licenses in the directory LICENSES.

  This program 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.

=for Marpa::R3::Display::End

=cut

# vim: expandtab shiftwidth=4: