About this document

This page is the reference for the grammar objects of Marpa's Scanless interface.

Constructor

The new() method is the constructor for Scanless grammars. An example of its use is above. The new() constructor accepts a hash of named arguments. The following named arguments are allowed:

bless_package

Specifies the name of a Perl package. The package is used for blessing node values into a Perl class, in conjunction with the bless adverb.

source

The value of the source named argument must be a reference to a string which contains a description of the grammar. The string's format is a domain-specific language, described in its own document.

trace_file_handle

The value is a file handle. Trace output and warning messages go to the trace file handle. By default the trace file handle is STDERR.

Discouraged named arguments

action_object

Use of this argument is discouraged in favor of the semantics_package named argument of the SLIF recognizer. Like the semantics_package named argument, it sets the semantic package. Unlike the semantics_package named argument, it is a fatal error if used together with an explicit per-parse argument of the SLIF recognizer's value() method. It is also a fatal error to try to use the semantics_package and action_object arguments together.

"Expands" a rule ID into symbol ID's. An array of symbol ID's is returned. The ID of the LHS symbol is the first element, and the remaining elements are the ID's of the RHS symbols, in order. Returns an empty array if the rule does not exist.

The first argument is the ID of the rule to be "expanded". The second, optional, argument is the name of a subgrammar. Currently there are L0 and G1 subgrammars. The default subgrammar is G1.

rule_ids()

do_something($_) for $slg->rule_ids();

do_something($_) for $slg->rule_ids('L0');

Returns a list of the rule ID's as an array. Takes one, optional, argument: the name of a subgrammar. Currently there are L0 and G1 subgrammars. The default subgrammar is G1.

rule_show()

my $rule_description = $slg->rule_show($rule_id);

my $rule_description = $slg->rule_show($rule_id, 'L0');

For a rule ID, returns a string describing that rule in a form which is useful for tracing and debugging, but subject to change. Returns a Perl undef if the rule does not exist.

The first argument is the ID of the rule to be displayed. The second, optional, argument is the name of a subgrammar. Currently there are L0 and G1 subgrammars. The default subgrammar is G1.

Given a symbol ID, returns a description of the symbol. The description may not be defined. Currently internal symbols tend to have descriptions, while symbols explicitly specified by the user in the DSL are treated as self-explanatory. The description is intended for humans to read, and is subject to change.

The first argument is the symbol ID. A second, optional, argument is the subgrammar. Currently there are L0 and G1 subgrammars. The default subgrammar is G1. Returns undefined if the symbol does not exist, or if it has no description.

Given a symbol ID, returns the "display form" of the symbol. This is the symbol in a form thought most suitable for display in messages, etc. The display form is always defined. The display form of a symbol is not useable as a name -- it is not necessarily unique, and is subject to change.

The first argument is the symbol ID. A second, optional, argument is the subgrammar. Currently there are L0 and G1 subgrammars. The default subgrammar is G1. Returns undefined if the symbol does not exist.

Given a symbol ID, returns the "DSL form" of the symbol. This is the name of the symbol in a form similar to the way it specified by the user in the DSL. If the symbol has an explicit name, the symbol's DSL form is same as its explici name. The DSL form may or may not be defined if a symbol does not have an explicit name. The DSL form of a symbol is not intended for use as a symbol name -- it is not necessarily unique, is not always defined, and it is subject to change.

The first argument is the symbol ID. A second, optional, argument is the subgrammar. Currently there are L0 and G1 subgrammars. The default subgrammar is G1. Returns undefined if the symbol does not exist, or if it has no DSL form.

symbol_ids()

do_something($_) for $slg->symbol_ids();

do_something($_) for $slg->symbol_ids('L0');

Returns a list of the symbol ID's as an array. Takes one, optional, argument: the name of a subgrammar. Currently there are L0 and G1 subgrammars. The default subgrammar is G1.

symbol_name()

Given a symbol ID, returns the name of the symbol. For every symbol ID, this method's return value will be defined and will be unique to that symbol ID, so that it is suitable for use as a symbol name. If a symbol has an explicit name, the return value will be the symbol's explicit name. If there is no explicit name, it will be an internal name. Internal names are subject to change.

The first argument is the symbol ID. A second, optional, argument is the subgrammar. Currently there are L0 and G1 subgrammars. The default subgrammar is G1. Returns undefined if the symbol does not exist.

Trace methods

show_rules()

my $show_rules_output = $slg->show_rules();

$show_rules_output .= $slg->show_rules(3, 'L0');

The show_rules() method returns a descripton of the rules for a subgrammar, by default G1. It is useful for understanding the rules as they appear in trace and debugging outputs. To allow for improvements in Marpa::R2, the output of show_rules() is subject to change.

The first optional argument can be a numeric verbosity level. The default verbosity is 1, which is adequate for most purposes. A verbosity of 2 prints additional information useful for those new to SLIF tracing and debugging. A verbosity of 3 prints additional information for experts.

The second, optional, argument is the name of a subgrammar. Currently there are L0 and G1 subgrammars.

show_symbols()

$show_symbols_output .= $slg->show_symbols(3);

$show_symbols_output .= $slg->show_symbols(3, 'L0');

The show_symbols() method returns a descripton of the symbols for a subgrammar, by default G1. It is useful for understanding the symbols as they appear in trace and debugging outputs. To allow for improvements in Marpa::R2, the output of show_symbols() is subject to change.

The first argument can be a numeric verbosity level. The default verbosity is 1, which is adequate for most purposes. A verbosity of 2 prints additional information useful for those new to SLIF tracing and debugging. A verbosity of 3 prints additional information for experts.

The second, optional, argument is the name of a subgrammar. Currently there are L0 and G1 subgrammars.

Discouraged methods

Discouraged methods are those that continue to be supported, but whose use is discouraged for one reason or another.

g0_rule()

Please prefer "rule_expand()", together with "symbol_name()" or "symbol_display_form()". Given a L0 rule ID as its argument, returns an array containing the names of the symbols of that rule. The g0_rule() method returns a Perl false if no L0 rule with that rule ID exists. If the L0 rule ID exists, g0_rule() returns a list of one or more symbol names. The first symbol name will be that of the rule's LHS symbol. The rest of the list will be the names of the rule's RHS symbols, in order.

rule()

Please prefer "rule_expand()", together with "symbol_name()" or "symbol_display_form()". Given a G1 rule ID as its argument, returns an array containing the names of the symbols of that rule. The rule() method returns a Perl false if no G1 rule with that rule ID exists. If the rule ID exists, rule() returns a list of one or more symbol names. The first symbol name will be that of the rule's LHS symbol. The rest of the list will be the names of the rule's RHS symbols, in order. The SLIF's rule() method is useful in combination with the SLIF's of the progress method, whose output identifies rules by rule ID.

Copyright and License

Copyright 2013 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/.

Module Install Instructions

To install Marpa::R2::Scanless::G, simply copy and paste either of the commands in to your terminal