NAME

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

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 Hitchhiker's Guide, which describes the Earth as "mostly harmless" -- it means "for most user's in typical circumstances".

Events

In Marpa::R3, events have been changed from an event-driven mechanism to a callback mechanism. A new events_handlers named argument has been added to Marpa::R3::Recognizer::new(). The $slr->events() method has been removed.

New valuer object

There is a new valuer object, with its own new POD document.

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).

"Eager" lexemes added

See "eager" in Marpa::R3::DSL.

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.

Semantics moved from recognizer to grammar

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

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.

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.

The Thin interface (THIF) has been removed.

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

The NAIF has been removed

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

LATM is now the default

[name, values] is now the default action

Unicode now works in the SLIF DSL

Context::location is now Context::g1_range

New context variable, Context::g1_span

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 their documentation.

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.

Marpa::R2 Grammar named arguments, alphabetically

This section accounts for each of the Marpa::R2 grammar's named arguments, in alphabetical order.

bless_package

Mostly unchanged.

ranking_method

Formerly recognizer named argument. high_rule_only option renamed to high_rank_only.

source

Mostly unchanged.

trace_file_handle

Mostly unchanged.

action_object

Removed.

default_action

Removed.

Marpa::R2 Grammar methods, alphabetically

This section accounts for each of the Marpa::R2 grammar's methods, in alphabetical order.

g0_rule()

See "Rule and symbol accessors are completely different".

g0_rule_ids()

See "Rule and symbol accessors are completely different".

g1_rule_ids()

See "Rule and symbol accessors are completely different".

new()

See the entries for changes in the grammar named arguments.

parse()

Mostly unchanged.

rule()

See "Rule and symbol accessors are completely different".

rule_expand()

See "Rule and symbol accessors are completely different".

rule_ids()

See "Rule and symbol accessors are completely different".

rule_name()

See "Rule and symbol accessors are completely different".

rule_show()

See "Rule and symbol accessors are completely different".

set()

See the entries for changes in the grammar named arguments.

show_rules()

See "Rule and symbol accessors are completely different".

show_symbols()

See "Rule and symbol accessors are completely different".

start_symbol_id()

See "Rule and symbol accessors are completely different".

symbol_description()

See "Rule and symbol accessors are completely different".

symbol_display_form()

See "Rule and symbol accessors are completely different".

symbol_dsl_form()

See "Rule and symbol accessors are completely different".

symbol_ids()

See "Rule and symbol accessors are completely different".

symbol_name()

See "Rule and symbol accessors are completely different".

Marpa::R2 Recognizer named arguments, alphabetically

This section accounts for each of the Marpa::R2 recognizer's named arguments, in alphabetical order.

end

Mostly unchanged.

event_is_active

Mostly unchanged.

exhaustion

Removed.

grammar

Mostly unchanged.

max_parses

The max_parses recognizer named argument of Marpa::R2 has been removed. In Marpa::R3, it is a named argument of the new valuator objects.

ranking_method

Changed to grammar named argument. high_rule_only option renamed to high_rank_only.

rejection

Removed.

semantics_package

Removed.

too_many_earley_items

Mostly unchanged.

trace_file_handle

Mostly unchanged.

trace_terminals

Mostly unchanged.

trace_values

Mostly unchanged.

Marpa::R2 Recognizer methods, alphabetically

This section accounts for each of the Marpa::R2 recognizer's methods, in alphabetical order.

activate()

Mostly unchanged.

ambiguity_metric()

The Marpa::R2::Recognizer::ambiguity_metric() method has been removed. Its purpose is now served by the valuer's ambiguity_level() method.

ambiguous()

The Marpa::R2::Recognizer::ambiguous() method has been removed. Its purpose is now served by the valuer's ambiguous() method.

current_g1_location()

The Marpa::R2::Recognizer::current_g1_location() method has been removed. Its purpose is now served by the Marpa::R3 recognizer's block_progress() method.

event()

Removed.

events()

Mostly unchanged.

exhausted()

Mostly unchanged.

g1_location_to_span()

Removed.

input_length()

The arguments of $recce-input_length() >>, have changed. Its first parameter now is the block id.

last_completed()

Mostly unchanged.

last_completed_range()

Removed.

last_completed_span()

Removed.

lexeme_alternative()

The interface to $recce-lexeme_alternative() >> has changed. Some of its functionality is taken over by the new $recce-lexeme_alternative_literal() >> method.

lexeme_complete()

The arguments of $recce-lexeme_complete() >>, have changed. Its first parameter now is the block id.

lexeme_priority_set()

Mostly unchanged.

lexeme_read()

The Marpa::R2::Recognizer::lexeme_read() method has been removed. Its function is provided by the new Marpa::R2::Recognizer::lexeme_read_block() and Marpa::R2::Recognizer::lexeme_read_string() methods. Marpa::R2::Recognizer::lexeme_read() may reappear in a non-backward-compatible form.

line_column()

The interface to Marpa::R2::Recognizer::line_column() has changed to allow multi-block input.

literal()

The interface to Marpa::R2::Recognizer::literal() has changed to allow multi-block input.

new()

See the entries for changes in the recognizer named arguments.

pause_lexeme()

Removed.

pause_span()

The Marpa::R2::Recognizer::pause_span() method has been removed. Event location information is now available as arguments to the event handlers.

pos()

Mostly unchanged.

progress()

Marpa::R2::Recognizer::progress() reported the dot position of completions as -1. In Marpa::R3, $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.

range_to_string()

Removed.

read()

The interface to the $recce->read() method has changed in major ways. One important change is that the slr->read() method may now called multiple times during a parse, each time with a new string. These strings will be called input blocks. For more details see Marpa::R3::Recognizer.

resume()

Mostly unchanged.

series_restart()

Removed.

set()

See the entries for changes in the recognizer named arguments.

show_progress()

Renamed to progress_show(). Also, see "Rule and symbol accessors are completely different".

substring()

$recce->substring() has been renamed $recce->g1_literal().

terminals_expected()

Mostly unchanged.

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 its documentation.

For dealing with ambiguous parses, and other advanced techniques, there is a new value object.

COPYRIGHT AND LICENSE

  Marpa::R3 is Copyright (C) 2018, 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.

cpanm Marpa::R3

perl -MCPAN -e shell
install Marpa::R3