—

              
# Copyright 2016 Jeffrey Kegler
# This file is part of Marpa::R3.  Marpa::R3 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::R3 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::R3.  If not, see
# http://www.gnu.org/licenses/.
HideShow 487 lines of Pod
=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
=for Marpa::R3::Display
name: SLG rule_expand() 2 args synopsis
    my ($lhs_id, @rhs_ids) = $grammar->rule_expand($rule_id, 'L0');
    $text .= "L0 Rule #$rule_id: $lhs_id ::= " . (join q{ }, @rhs_ids) . "\n";
=for Marpa::R3::Display::End
"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.
=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
=for Marpa::R3::Display
name: SLG rule_ids() 2 arg synopsis
normalize-whitespace: 1
    do_something($_) for $grammar->rule_ids('L0');
=for Marpa::R3::Display::End
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.
=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
=for Marpa::R3::Display
name: SLG rule_show() 2 args synopsis
    my $rule_description = $grammar->rule_show($rule_id, 'L0');
=for Marpa::R3::Display::End
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.
=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
=for Marpa::R3::Display
name: SLG symbol_display_form() 2 arg synopsis
    my $display_form = $grammar->symbol_display_form( $symbol_id, 'L0' );
    $text
        .= "L0 symbol number: $symbol_id  name in display form: $display_form\n";
=for Marpa::R3::Display::End
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 a Perl C<undef> if the symbol does not exist.
=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
=for Marpa::R3::Display
name: SLG symbol_dsl_form() 2 arg synopsis
    my $dsl_form = $grammar->symbol_dsl_form( $symbol_id, 'L0' )
        // '[No name in DSL form]';
    $text .= "L0 symbol number: $symbol_id  DSL form: $dsl_form\n";
=for Marpa::R3::Display::End
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 is specified by the user in the DSL.
If the symbol has an explicit name,
the symbol's DSL form is the same as its explicit name.
If the symbol does not have an explicit name,
the method may return a Perl C<undef>,
or it may return a DSL name invented by Marpa
and intended to be suggestive.
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 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
=for Marpa::R3::Display
name: SLG symbol_ids() 2 arg synopsis
normalize-whitespace: 1
    do_something($_) for $grammar->symbol_ids('L0');
=for Marpa::R3::Display::End
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.
=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
=for Marpa::R3::Display
name: SLG symbol_name() 2 arg synopsis
    my $name = $grammar->symbol_name( $symbol_id, 'L0' );
    $text .= "L0 symbol number: $symbol_id  name: $name\n";
=for Marpa::R3::Display::End
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 a Perl C<undef> if the symbol does not exist.
=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
=for Marpa::R3::Display
name: SLG show_rules() synopsis with 2 args
partial: 1
normalize-whitespace: 1
    $show_rules_output .= $grammar->show_rules(3, 'L0');
=for Marpa::R3::Display::End
The C<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::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.
The second, optional, argument is the name of a subgrammar.
Currently there are L0 and G1 subgrammars.
=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
=for Marpa::R3::Display
name: SLIF show_symbols() synopsis
partial: 1
normalize-whitespace: 1
    $show_symbols_output .= $grammar->show_symbols(3, 'L0');
=for Marpa::R3::Display::End
The C<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::R3,
the output of C<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.
=head1 Copyright and License
=for Marpa::R3::Display
ignore: 1
  Copyright 2016 Jeffrey Kegler
  This file is part of Marpa::R3.  Marpa::R3 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::R3 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::R3.  If not, see
  http://www.gnu.org/licenses/.
=for Marpa::R3::Display::End
=cut
# vim: expandtab shiftwidth=4: