# 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 significant incompatibilities
between Marpa::R2
and Marpa::R3.
It is intended for readers already familiar with Marpa::R2,
who are writing new applications for Marpa::R3,
and for readers migrating Marpa::R2 applications
and tools to Marpa::R3.
Differences that do not give rise to a significant incompatibility
are not included.
Here "significant" means "likely to impact legacy Marpa::R2 code".
This document is a checklist and, on its own, is not a complete guide
for migration.
It avoids duplicating material in the main Marpa::R3 documents.
For example, if a Marpa::R2 method is replaced by a Marpa::R3 method,
this document may simply note that fact and refer the reader to
the description of the new method in the other documents.
Marpa::R3 contains so many highly inter-connected changes,
that nothing in it can safely be said to be simply "unchanged".
Some methods and named arguments are described as "Mostly unchanged".
Here "mostly" is used in the same sense in which Douglas Adams uses
in the I<Hitchhiker's Guide>, which describes the Earth as
"mostly harmless" -- it means "for most user's in typical circumstances".
=head1 Events
In Marpa::R3, events have been changed from an event-driven
mechanism to a callback mechanism.
A new C<events_handlers> named argument has been added to
C<< Marpa::R3::Recognizer::new() >>.
The
C<< $slr->events() >> method has been
removed.
=head1 New valuer object
There is a new valuer object,
with its own L<new
POD document|Marpa::R3::Valuer.pod>.
=head1 Marpa strings must be UTF-8
Marpa expects all strings passed to it to be valid UTF-8.
(Note that all ASCII-7 string are valid UTF-8).
=head1 "Eager" lexemes added
See L<Marpa::R3::DSL/"eager">.
=head1 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.
=head1 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.
=head1 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.
=head1 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 no usage.
=head1 The Thin interface (THIF) has been removed.
The THIF was a "thin" Perl interface.
It has been removed.
=head1 The NAIF has been removed
The NAIF was an older interface using hashes of named
variables, instead of a DSL.
It has been removed.
=head1 LATM is now the default
=head1 [name, values] is now the default action
=head1 Unicode now works in the SLIF DSL
=head1 Context::location is now Context::g1_range
=head1 New context variable, Context::g1_span
=head1 Rule and symbol accessors are completely different
In Marpa::R3,
symbols and rules were divided in external and internal.
As a result,
the grammar accessors for symbols and rules
changed completely between Marpa::R2
and Marpa::R3.
The changes are so massive that
any summary of the changes
to the grammar accessors
would be essentially be a repetition of
L<their
documentation|Marpa::R3::Grammar/"Accessors">.
=head1 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.
=head1 Marpa::R2 Grammar named arguments, alphabetically
This section accounts for each of the Marpa::R2 grammar's
named arguments, in alphabetical order.
=head2 bless_package
Mostly unchanged.
=head2 ranking_method
Formerly recognizer named argument.
C<high_rule_only> option renamed to
C<high_rank_only>.
=head2 source
Mostly unchanged.
=head2 trace_file_handle
Mostly unchanged.
=head2 action_object
Removed.
=head2 default_action
Removed.
=head1 Marpa::R2 Grammar methods, alphabetically
This section accounts for each of the Marpa::R2 grammar's
methods, in alphabetical order.
=head2 g0_rule()
See L</"Rule and symbol accessors are completely different">.
=head2 g0_rule_ids()
See L</"Rule and symbol accessors are completely different">.
=head2 g1_rule_ids()
See L</"Rule and symbol accessors are completely different">.
=head2 new()
See the entries for changes
in the grammar named arguments.
=head2 parse()
Mostly unchanged.
=head2 rule()
See L</"Rule and symbol accessors are completely different">.
=head2 rule_expand()
See L</"Rule and symbol accessors are completely different">.
=head2 rule_ids()
See L</"Rule and symbol accessors are completely different">.
=head2 rule_name()
See L</"Rule and symbol accessors are completely different">.
=head2 rule_show()
See L</"Rule and symbol accessors are completely different">.
=head2 set()
See the entries for changes
in the grammar named arguments.
=head2 show_rules()
See L</"Rule and symbol accessors are completely different">.
=head2 show_symbols()
See L</"Rule and symbol accessors are completely different">.
=head2 start_symbol_id()
See L</"Rule and symbol accessors are completely different">.
=head2 symbol_description()
See L</"Rule and symbol accessors are completely different">.
=head2 symbol_display_form()
See L</"Rule and symbol accessors are completely different">.
=head2 symbol_dsl_form()
See L</"Rule and symbol accessors are completely different">.
=head2 symbol_ids()
See L</"Rule and symbol accessors are completely different">.
=head2 symbol_name()
See L</"Rule and symbol accessors are completely different">.
=head1 Marpa::R2 Recognizer named arguments, alphabetically
This section accounts for each of the Marpa::R2 recognizer's
named arguments, in alphabetical order.
=head2 end
Mostly unchanged.
=head2 event_is_active
Mostly unchanged.
=head2 exhaustion
Removed.
=head2 grammar
Mostly unchanged.
=head2 max_parses
The C<max_parses>
recognizer named argument
of Marpa::R2
has been removed.
In Marpa::R3,
it is a named argument of
the new valuator objects.
=head2 ranking_method
Changed to grammar named argument.
C<high_rule_only> option renamed to
C<high_rank_only>.
=head2 rejection
Removed.
=head2 semantics_package
Removed.
=head2 too_many_earley_items
Mostly unchanged.
=head2 trace_file_handle
Mostly unchanged.
=head2 trace_terminals
Mostly unchanged.
=head2 trace_values
Mostly unchanged.
=head1 Marpa::R2 Recognizer methods, alphabetically
This section accounts for each of the Marpa::R2 recognizer's
methods, in alphabetical order.
=head2 activate()
Mostly unchanged.
=head2 ambiguity_metric()
The C<Marpa::R2::Recognizer::ambiguity_metric()> method
has been removed.
Its purpose is now served by the
valuer's
C<ambiguity_level()> method.
=head2 ambiguous()
The C<Marpa::R2::Recognizer::ambiguous()> method
has been removed.
Its purpose is now served by the
valuer's C<ambiguous()> method.
=head2 current_g1_location()
The C<Marpa::R2::Recognizer::current_g1_location()> method
has been removed.
Its purpose is now served by the
Marpa::R3 recognizer's C<block_progress()> method.
=head2 event()
Removed.
=head2 events()
Mostly unchanged.
=head2 exhausted()
Mostly unchanged.
=head2 g1_location_to_span()
Removed.
=head2 input_length()
The arguments of
C< $recce->input_length() >>,
have changed.
Its first parameter now is the block id.
=head2 last_completed()
Mostly unchanged.
=head2 last_completed_range()
Removed.
=head2 last_completed_span()
Removed.
=head2 lexeme_alternative()
The interface to
C< $recce->lexeme_alternative() >>
has changed.
Some of its functionality is taken over
by the new
C< $recce->lexeme_alternative_literal() >>
method.
=head2 lexeme_complete()
The arguments of
C< $recce->lexeme_complete() >>,
have changed.
Its first parameter now is the block id.
=head2 lexeme_priority_set()
Mostly unchanged.
=head2 lexeme_read()
The C<Marpa::R2::Recognizer::lexeme_read()> method
has been removed.
Its function is provided by the new
C<Marpa::R2::Recognizer::lexeme_read_block()>
and C<Marpa::R2::Recognizer::lexeme_read_string()>
methods.
C<Marpa::R2::Recognizer::lexeme_read()> may reappear
in a non-backward-compatible form.
=head2 line_column()
The interface to
C<Marpa::R2::Recognizer::line_column()> has changed
to allow multi-block input.
=head2 literal()
The interface to
C<Marpa::R2::Recognizer::literal()> has changed
to allow multi-block input.
=head2 new()
See the entries for changes
in the recognizer named arguments.
=head2 pause_lexeme()
Removed.
=head2 pause_span()
The C<Marpa::R2::Recognizer::pause_span()> method
has been removed.
Event location information is now available
as arguments to the
event handlers.
=head2 pos()
Mostly unchanged.
=head2 progress()
C<Marpa::R2::Recognizer::progress()> reported
the dot position of completions as -1.
In Marpa::R3,
C<< $slr->progress() >> reports
the dot position of completions as a non-negative integer,
consistent with other dot positions.
As a reminder, the dot position of a completed production is always
the same as its RHS length.
=head2 range_to_string()
Removed.
=head2 read()
The interface to
the C<< $recce->read() >> method has changed in major ways.
One important change is that
the C<< slr->read() >> method may now called multiple
times during a parse,
each time with a new string.
These strings will be called B<input blocks>.
For more details see L<Marpa::R3::Recognizer>.
=head2 resume()
Mostly unchanged.
=head2 series_restart()
Removed.
=head2 set()
See the entries for changes
in the recognizer named arguments.
=head2 show_progress()
Renamed to C<progress_show()>.
Also, see L</"Rule and symbol accessors are completely different">.
=head2 substring()
C<< $recce->substring() >> has been renamed
C<< $recce->g1_literal() >>.
=head2 terminals_expected()
Mostly unchanged.
=head2 value()
The recognizer value() method has changed.
Most notably, it
now throws a fatal error if
the parse is ambiguous -- this is
what most applications want.
Details are in L<its
documentation|Marpa::R3::Recognizer/"value()">.
For dealing
with ambiguous parses, and other
advanced techniques,
there is a L<new
value object|Marpa::R3::Valuer>.
=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: