# Marpa::R3 is Copyright (C) 2016, 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::Scanless::G - Scanless interface grammars
=head1 Synopsis
=for Marpa::R3::Display
name: Scanless grammar synopsis
partial: 1
normalize-whitespace: 1
my $grammar = Marpa::R3::Scanless::G->new(
{
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
}
);
=for Marpa::R3::Display::End
=head1 About this document
This page is the reference for the grammar objects
of Marpa's Scanless interface.
=head1 Constructor
The C<new()> method is the constructor for Scanless grammars.
An example of its use is L<above|/"Synopsis">.
The C<new()> constructor accepts a hash of named arguments.
The following named arguments are allowed:
=head2 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
L<C<bless> adverb|Marpa::R3::Scanless::DSL/"bless">.
C<bless_package> should not be confused with the
L<SLIF's
C<semantics_package> recognizer setting|Marpa::R3::Scanless::R/"semantics_package">.
The two are not closely related.
=head2 source
The value of the C<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 L<in its own
document|Marpa::R3::Scanless::DSL>.
=head2 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 C<STDERR>.
=head1 Mutators
=head2 parse()
=for Marpa::R3::Display
name: Landing page synopsis
normalize-whitespace: 1
partial: 1
my $grammar = Marpa::R3::Scanless::G->new( { source => \$dsl } );
my $input = '42 * 1 + 7';
my $value_ref = $grammar->parse( \$input, 'My_Actions' );
=for Marpa::R3::Display::End
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 L<Marpa::R3> is reimplemented
using low-level calls in L<Marpa::R3::Tutorial2>.
The C<parse()> method takes one or more arguments.
The first argument, which is required, is a ref to an input string.
Optionally, the second argument may be a string specifying the package name
for the semantics.
The remaining arguments
(including the second argument if it exists, but is not a string)
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,
C<parse()> throws an exception.
=head2 set()
=for Marpa::R3::Display
name: SLIF grammar set() synopsis
normalize-whitespace: 1
$grammar->set( { trace_file_handle => $trace_fh } );
=for Marpa::R3::Display::End
This method allows the named arguments to be changed after an SLIF
grammar is created.
Currently, the only argument that may be changed in L<C<trace_file_handle>|/"trace_file_handle">.
=head1 Accessors
=head2 rule_expand()
=for Marpa::R3::Display
name: SLG rule_expand() synopsis
my ($lhs_id, @rhs_ids) = $grammar->rule_expand($rule_id);
$text .= "Rule #$rule_id: $lhs_id ::= " . (join q{ }, @rhs_ids) . "\n";
=for Marpa::R3::Display::End
"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.
=head2 l0_rule_expand()
=for Marpa::R3::Display
name: SLG l0_rule_expand() synopsis
my ($lhs_id, @rhs_ids) = $grammar->l0_rule_expand($rule_id);
$text .= "L0 Rule #$rule_id: $lhs_id ::= " . (join q{ }, @rhs_ids) . "\n";
=for Marpa::R3::Display::End
"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.
=head2 rule_ids()
=for Marpa::R3::Display
name: SLG rule_ids() synopsis
normalize-whitespace: 1
do_something($_) for $grammar->rule_ids();
=for Marpa::R3::Display::End
Returns a list of the G1 grammar rule ID's as an array.
=head2 l0_rule_ids()
=for Marpa::R3::Display
name: SLG l0_rule_ids() synopsis
normalize-whitespace: 1
do_something($_) for $grammar->l0_rule_ids();
=for Marpa::R3::Display::End
Returns a list of the L0 grammar rule ID's as an array.
=head2 rule_name()
=for Marpa::R3::Display
name: $grammar->rule_name() example
push @rule_names, $grammar->rule_name($_) for $grammar->rule_ids();
=for Marpa::R3::Display::End
Given a rule ID, returns the rule name.
A rule name is as defined by
L<the C<name> adverb|Marpa::R3::Scanless::DSL/"name">.
If no rule name was defined, the rule name is the name of
the LHS symbol.
=head2 rule_show()
=for Marpa::R3::Display
name: SLG rule_show() synopsis
my $rule_description = $grammar->rule_show($rule_id);
=for Marpa::R3::Display::End
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.
=head2 SLG l0_rule_show()
=for Marpa::R3::Display
name: SLG l0_rule_show() synopsis
my $rule_description = $grammar->l0_rule_show($rule_id);
=for Marpa::R3::Display::End
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.
=head2 start_symbol_id()
=for Marpa::R3::Display
name: $grammar->start_symbol_id() example
my $start_id = $grammar->start_symbol_id();
=for Marpa::R3::Display::End
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.
=head2 symbol_display_form()
=for Marpa::R3::Display
name: SLG symbol_display_form() synopsis
my $display_form = $grammar->symbol_display_form($symbol_id);
$text
.= "symbol number: $symbol_id name in display form: $display_form\n";
=for Marpa::R3::Display::End
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 C<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.
=head2 l0_symbol_display_form()
=for Marpa::R3::Display
name: SLG l0_symbol_display_form() synopsis
my $display_form = $grammar->l0_symbol_display_form( $symbol_id );
$text
.= "L0 symbol number: $symbol_id name in display form: $display_form\n";
=for Marpa::R3::Display::End
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 C<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.
=head2 symbol_dsl_form()
=for Marpa::R3::Display
name: SLG symbol_dsl_form() synopsis
my $dsl_form = $grammar->symbol_dsl_form($symbol_id)
// '[No name in DSL form]';
$text .= "symbol number: $symbol_id DSL form: $dsl_form\n";
=for Marpa::R3::Display::End
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 C<undef> if the symbol does not exist,
or if it has no DSL form.
=head2 l0_symbol_dsl_form()
=for Marpa::R3::Display
name: SLG l0_symbol_dsl_form() synopsis
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";
=for Marpa::R3::Display::End
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 C<undef> if the symbol does not exist,
or if it has no DSL form.
=head2 symbol_ids()
=for Marpa::R3::Display
name: SLG symbol_ids() synopsis
normalize-whitespace: 1
do_something($_) for $grammar->symbol_ids();
=for Marpa::R3::Display::End
Returns a list of the G1 grammar symbol ID's as an array.
=head2 l0_symbol_ids()
=for Marpa::R3::Display
name: SLG l0_symbol_ids() synopsis
normalize-whitespace: 1
do_something($_) for $grammar->l0_symbol_ids();
=for Marpa::R3::Display::End
Returns a list of the L0 grammar symbol ID's as an array.
=head2 symbol_name()
=for Marpa::R3::Display
name: SLG symbol_name() synopsis
my $name = $grammar->symbol_name($symbol_id);
$text .= "symbol number: $symbol_id name: $name\n";
=for Marpa::R3::Display::End
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 C<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.
=head2 l0_symbol_name()
=for Marpa::R3::Display
name: SLG l0_symbol_name() synopsis
my $name = $grammar->l0_symbol_name( $symbol_id );
$text .= "L0 symbol number: $symbol_id name: $name\n";
=for Marpa::R3::Display::End
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 C<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.
=head1 Trace methods
=head2 show_rules()
=for Marpa::R3::Display
name: SLG show_rules() synopsis
partial: 1
normalize-whitespace: 1
my $show_rules_output = $grammar->show_rules();
=for Marpa::R3::Display::End
The C<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 C<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.
=head2 l0_show_rules()
=for Marpa::R3::Display
name: SLG l0_show_rules() synopsis
partial: 1
normalize-whitespace: 1
$show_rules_output .= $grammar->l0_show_rules(3);
=for Marpa::R3::Display::End
The C<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 C<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.
=head2 show_symbols()
=for Marpa::R3::Display
name: SLIF show_symbols() synopsis
partial: 1
normalize-whitespace: 1
$show_symbols_output .= $grammar->show_symbols(3);
=for Marpa::R3::Display::End
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 C<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.
=head2 l0_show_symbols()
=for Marpa::R3::Display
name: SLIF show_symbols() synopsis
partial: 1
normalize-whitespace: 1
$show_symbols_output .= $grammar->l0_show_symbols(3);
=for Marpa::R3::Display::End
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 C<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.
=head1 COPYRIGHT AND LICENSE
=for Marpa::R3::Display
ignore: 1
Marpa::R3 is Copyright (C) 2016, 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: