Name
Marpa::R3::Scanless::G - Scanless interface grammars
Synopsis
my $grammar = Marpa::R3::Scanless::G->new(
{
semantics_package => 'My_Actions',
source => \(<<'END_OF_SOURCE'),
:default ::= action => do_first_arg
:start ::= Script
Script ::= Expression+ separator => comma action => do_script
comma ~ [,]
Expression ::=
Number
| '(' Expression ')' action => do_parens assoc => group
|| Expression '**' Expression action => do_pow assoc => right
|| Expression '*' Expression action => do_multiply
| Expression '/' Expression action => do_divide
|| Expression '+' Expression action => do_add
| Expression '-' Expression action => do_subtract
Number ~ [\d]+
:discard ~ whitespace
whitespace ~ [\s]+
# allow comments
:discard ~ <hash comment>
<hash comment> ~ <terminated hash comment> | <unterminated
final hash comment>
<terminated hash comment> ~ '#' <hash comment body> <vertical space char>
<unterminated final hash comment> ~ '#' <hash comment body>
<hash comment body> ~ <hash comment char>*
<vertical space char> ~ [\x{A}\x{B}\x{C}\x{D}\x{2028}\x{2029}]
<hash comment char> ~ [^\x{A}\x{B}\x{C}\x{D}\x{2028}\x{2029}]
END_OF_SOURCE
}
);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. bless_package should not be confused with the SLIF's semantics_package grammar setting. The two are not closely related.
exhaustion
The exhaustion grammar setting determines what happens when asynchronous parse exhaustion occurs. Intuitively, "asynchronous" parse exhaustion is parse exhaustion at a point when control would not normally return to the application. For details see the description of exhaustion parse events.
The value of the exhaustion grammar setting must be either "fatal" or "event". "fatal" is the default. If the value is "fatal", asynchronous parse exhaustion is treated as an error, and an exception is thrown. If the value is "event", an event occurs as described in the section on exhaustion parse events.
ranking_method
The ranking_method is only allowed in calls of the new() method. The value must be a string: one of "none", "rule", or "high_rule_only". When the value is "none", Marpa returns the parse results in arbitrary order. This is the default.
The "rule" and "high_rule_only" ranking methods allows the user to control the order in which parse results are returned by the value method, and to exclude some parse results from the parse series. For details, see the document on parse order.
rejection
The rejection grammar setting determines what happens when all tokens are rejected by the G1 parser. The value must be either "fatal" or "event". "fatal" is the default.
If the value is "fatal", rejection of all tokens is treated as an error, and an exception is thrown. If the value is "event", an event occurs as described in the section on rejection parse events.
semantics_package
Sets the semantic package for the grammar. The semantics_package grammar setting is used when resolving action names to fully qualified Perl names. For more details on the SLIF semantics, see the document on SLIF semantics.
The semantics_package grammar setting should not be confused with the SLIF's bless_package grammar setting. The two are not closely related.
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.
Mutators
parse()
my $grammar = Marpa::R3::Scanless::G->new(
{
semantics_package => 'My_Actions',
source => \$dsl
}
);
my $input = '42 * 1 + 7';
my $value_ref = $grammar->parse( \$input );This very-high level method is a "one shot" way of producing a parse value from a grammar and an input stream. The features this method provides are those most often wanted in the "first cut" of a parser.
As the parser grows, users are likely to find their application has outgrown this method. It is recommended, rather than spend a lot of time exploring ways to adapt this method to expanding needs, that users be quick to abandon it in favor of the lower level calls. As an example of how to make this transition, the tutorial in Marpa::R3 is reimplemented using low-level calls in Marpa::R3::Tutorial2.
The parse() method takes one or more arguments. The first argument, which is required, is a ref to an input string. The remaining arguments must be references to hashes of named arguments. These hash references will be passed, as is, to the constructor for the recognizer.
This method returns a reference to the only parse value, if there is exactly one parse value. If there is no parse, or if the parse is ambiguous, parse() throws an exception.
set()
$grammar->set( { trace_file_handle => $trace_fh } );This method allows the named arguments to be changed after an SLIF grammar is created. Currently, the only argument that may be changed in trace_file_handle.
Accessors
rule_expand()
my ($lhs_id, @rhs_ids) = $grammar->rule_expand($rule_id);
$text .= "Rule #$rule_id: $lhs_id ::= " . (join q{ }, @rhs_ids) . "\n";"Expands" a G1 grammar rule ID into symbol ID's. The first and only argument, which is required, is the ID of the rule to be "expanded". 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 G1 grammar rule does not exist.
l0_rule_expand()
my ($lhs_id, @rhs_ids) = $grammar->l0_rule_expand($rule_id);
$text .= "L0 Rule #$rule_id: $lhs_id ::= " . (join q{ }, @rhs_ids) . "\n";"Expands" a L0 grammar rule ID into symbol ID's. The first and only argument, which is required, is the ID of the rule to be "expanded". 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 L0 grammar rule does not exist.
rule_ids()
do_something($_) for $grammar->rule_ids();Returns a list of the G1 grammar rule ID's as an array.
l0_rule_ids()
do_something($_) for $grammar->l0_rule_ids();Returns a list of the L0 grammar rule ID's as an array.
rule_name()
push @rule_names, $grammar->rule_name($_) for $grammar->rule_ids();Given a G1 rule ID, returns the rule name. A rule name is as defined by the name adverb. If no rule name was defined, the rule name is the name of the LHS symbol.
rule_show()
my $rule_description = $grammar->rule_show($rule_id);The first argument, which is required, is the ID of a G1 grammar rule. 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.
SLG l0_rule_show()
my $rule_description = $grammar->l0_rule_show($rule_id);The first argument, which is required, is the ID of a L0 grammar rule. 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.
start_symbol_id()
my $start_id = $grammar->start_symbol_id();Returns the ID of the start symbol. Note that there is no method to return the ID of the start rule, because there may be no unique start rule.
symbol_display_form()
my $display_form = $grammar->symbol_display_form($symbol_id);
$text
.= "symbol number: $symbol_id name in display form: $display_form\n";The first, required, argument is a G1 grammar symbol ID. Returns the "display form" of the symbol. This is the symbol in a form thought most suitable for display in messages, etc. Returns a Perl undef if the symbol does not exist.
The display form of a symbol 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.
l0_symbol_display_form()
my $display_form = $grammar->l0_symbol_display_form( $symbol_id );
$text
.= "L0 symbol number: $symbol_id name in display form: $display_form\n";The first, required, argument is an L0 grammar symbol ID. Returns the "display form" of the symbol. This is the symbol in a form thought most suitable for display in messages, etc. Returns a Perl undef if the symbol does not exist.
The display form of a symbol 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.
symbol_dsl_form()
my $dsl_form = $grammar->symbol_dsl_form($symbol_id)
// '[No name in DSL form]';
$text .= "symbol number: $symbol_id DSL form: $dsl_form\n";Takes one, required, argument: a symbol ID in the G1 grammar. The return value is the "DSL form" of the symbol. This is the symbol exactly as it was specified by the user in the SLIF DSL. The return value is a Perl undef if the symbol does not exist, or if it has no DSL form.
l0_symbol_dsl_form()
my $dsl_form = $grammar->l0_symbol_dsl_form( $symbol_id )
// '[No name in DSL form]';
$text .= "L0 symbol number: $symbol_id DSL form: $dsl_form\n";Takes one, required, argument: a symbol ID in the L0 grammar. The return value is the "DSL form" of the symbol. This is the symbol exactly as it was specified by the user in the SLIF DSL. The return value is a Perl undef if the symbol does not exist, or if it has no DSL form.
symbol_ids()
do_something($_) for $grammar->symbol_ids();Returns a list of the G1 grammar symbol ID's as an array.
l0_symbol_ids()
do_something($_) for $grammar->l0_symbol_ids();Returns a list of the L0 grammar symbol ID's as an array.
symbol_name()
my $name = $grammar->symbol_name($symbol_id);
$text .= "symbol number: $symbol_id name: $name\n";The first and only argument, which is required, is a G1 grammar symbol ID. The return value is the name of the symbol, if the symbol exists, and a Perl undef if the symbol does not exist.
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 the SLIF DSL explicitly specifies a name, the return value is that explicitly specified name. Otherwise, the return value is an internal name, which is subject to change in future versions of Marpa::R3.
l0_symbol_name()
my $name = $grammar->l0_symbol_name( $symbol_id );
$text .= "L0 symbol number: $symbol_id name: $name\n";The first and only argument, which is required, is an L0 grammar symbol ID. The return value is the name of the symbol, if the symbol exists, and a Perl undef if the symbol does not exist.
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 the SLIF DSL explicitly specifies a name, the return value is that explicitly specified name. Otherwise, the return value is an internal name, which is subject to change in future versions of Marpa::R3.
Trace methods
show_rules()
my $show_rules_output = $grammar->show_rules();The show_rules() method returns a description of the rules for the G1 grammar. It is useful for understanding the rules as they appear in trace and debugging outputs. To allow for improvements in Marpa::R3, 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.
l0_show_rules()
$show_rules_output .= $grammar->l0_show_rules(3);The show_rules() method returns a description of the rules for the L0 grammar. It is useful for understanding the rules as they appear in trace and debugging outputs. To allow for improvements in Marpa::R3, 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.
show_symbols()
$show_symbols_output .= $grammar->show_symbols(3);The first and only argument, which is optional, is a numeric verbosity level. The return value is a descripton of the symbols for the G1 grammar. It is useful for understanding the symbols as they appear in trace and debugging outputs. To allow for improvements in Marpa::R3, the output of show_symbols() is subject to change.
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.
l0_show_symbols()
$show_symbols_output .= $grammar->l0_show_symbols(3);The first and only argument, which is optional, is a numeric verbosity level. The return value is a descripton of the symbols for the L0 grammar. It is useful for understanding the symbols as they appear in trace and debugging outputs. To allow for improvements in Marpa::R3, the output of show_symbols() is subject to change.
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.
COPYRIGHT AND LICENSE
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.