# Copyright 2022 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/.

=head1 Name

Marpa::R2::Scanless::G - Scanless interface grammars

=head1 Synopsis

=for Marpa::R2::Display
name: Scanless grammar synopsis
partial: 1
normalize-whitespace: 1

    my $grammar = Marpa::R2::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::R2::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::R2::Scanless::DSL/"bless">.
C<bless_package> should not be confused with the 
L<SLIF's
C<semantics_package> recognizer setting|Marpa::R2::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::R2::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>.

=head2 Discouraged named arguments

=head3 action_object

Use of this argument is discouraged
in favor of L<the C<semantics_package> named argument of the SLIF
recognizer|Marpa::R2::Scanless::R/"semantics_package">.
Like the C<semantics_package> named argument, it sets the semantic
package.
Unlike the C<semantics_package> named argument, it is a fatal error if used
together with an explicit per-parse argument of the SLIF recognizer's C<value()> method.
It is also a fatal error to try to use the C<semantics_package>
and C<action_object> arguments together.

=head3 default_action

Use of this argument is deprecated in favor of using the
L<C<action> adverb|Marpa::R2::Scanless::DSL/"action">
in a
L<default pseudo-rule|Marpa::R2::Scanless::DSL/"Default pseudo-rule">.
Specifies the C<default_action> named argument that
will be used for the G1 grammar.
For details of on possible default action values and how
they are used, see
L<C<action> adverb|Marpa::R2::Scanless::DSL/"action">.

=head1 Mutators

=head2 parse()

=for Marpa::R2::Display
name: Landing page synopsis
normalize-whitespace: 1 
partial: 1

    my $grammar   = Marpa::R2::Scanless::G->new( { source => \$dsl } );
    my $input     = '42 * 1 + 7';
    my $value_ref = $grammar->parse( \$input, 'My_Actions' );

=for Marpa::R2::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::R2> is reimplemented
using low-level calls in L<Marpa::R2::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::R2::Display
name: SLIF grammar set() synopsis
normalize-whitespace: 1

    $grammar->set( { trace_file_handle => $trace_fh } );

=for Marpa::R2::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::R2::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::R2::Display::End

=for Marpa::R2::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::R2::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::R2::Display
name: SLG rule_ids() synopsis
normalize-whitespace: 1

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

=for Marpa::R2::Display::End

=for Marpa::R2::Display
name: SLG rule_ids() 2 arg synopsis
normalize-whitespace: 1

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

=for Marpa::R2::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::R2::Display
name: $grammar->rule_name() example

    push @rule_names, $grammar->rule_name($_) for $grammar->rule_ids();

=for Marpa::R2::Display::End

Given a rule ID, returns the rule name.
A rule name is as defined by
L<the C<name> adverb|Marpa::R2::Scanless::DSL/"name">.
If no rule name was defined, the rule name is the name of
the LHS symbol.

=head2 rule_show()

=for Marpa::R2::Display
name: SLG rule_show() synopsis

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

=for Marpa::R2::Display::End

=for Marpa::R2::Display
name: SLG rule_show() 2 args synopsis

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

=for Marpa::R2::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::R2::Display
name: $grammar->start_symbol_id() example

    my $start_id = $grammar->start_symbol_id();

=for Marpa::R2::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_description()

=for Marpa::R2::Display
name: SLG symbol_description() synopsis

    my $description = $grammar->symbol_description($symbol_id)
        // '[No description]';
    $text .= "symbol number: $symbol_id  description $description\n";

=for Marpa::R2::Display::End

=for Marpa::R2::Display
name: SLG symbol_description() 2 arg synopsis

    my $description = $grammar->symbol_description( $symbol_id, 'L0' )
        // '[No description]';
    $text .= "L0 symbol number: $symbol_id  description $description\n";

=for Marpa::R2::Display::End

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 a Perl C<undef> if the symbol does not exist,
or if it has no description.

=head2 symbol_display_form()

=for Marpa::R2::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::R2::Display::End

=for Marpa::R2::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::R2::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::R2::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::R2::Display::End

=for Marpa::R2::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::R2::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::R2::Display
name: SLG symbol_ids() synopsis
normalize-whitespace: 1

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

=for Marpa::R2::Display::End

=for Marpa::R2::Display
name: SLG symbol_ids() 2 arg synopsis
normalize-whitespace: 1

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

=for Marpa::R2::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::R2::Display
name: SLG symbol_name() synopsis

    my $name = $grammar->symbol_name($symbol_id);
    $text .= "symbol number: $symbol_id  name: $name\n";

=for Marpa::R2::Display::End

=for Marpa::R2::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::R2::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::R2::Display
name: SLG show_rules() synopsis
partial: 1
normalize-whitespace: 1

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

=for Marpa::R2::Display::End

=for Marpa::R2::Display
name: SLG show_rules() synopsis with 2 args
partial: 1
normalize-whitespace: 1

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

=for Marpa::R2::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::R2,
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::R2::Display
name: SLIF show_symbols() synopsis
partial: 1
normalize-whitespace: 1

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

=for Marpa::R2::Display::End

=for Marpa::R2::Display
name: SLIF show_symbols() synopsis
partial: 1
normalize-whitespace: 1

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

=for Marpa::R2::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::R2,
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 Discouraged methods

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

=head2 g0_rule()

=for Marpa::R2::Display
name: Scanless g0_rule() synopsis
normalize-whitespace: 1

    my @g0_rule_ids = $grammar->g0_rule_ids();
    for my $g0_rule_id (@g0_rule_ids) {
        $g0_rules_description .= "$g0_rule_id "
            . ( join q{ }, map {"<$_>"} $grammar->g0_rule($g0_rule_id) ) . "\n";
    }

=for Marpa::R2::Display::End

Please prefer L<"rule_expand()">, together with
L<"symbol_name()"> or
L<"symbol_display_form()">.
Given a L0 rule ID as its argument,
returns an array containing the
names of the symbols of that rule.
The C<g0_rule()> method
returns a Perl false if no L0 rule with that rule ID exists.
If the L0 rule ID exists,
C<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.

=head2 g0_rule_ids()

=for Marpa::R2::Display
name: Scanless g0_rule() synopsis
normalize-whitespace: 1

    my @g0_rule_ids = $grammar->g0_rule_ids();
    for my $g0_rule_id (@g0_rule_ids) {
        $g0_rules_description .= "$g0_rule_id "
            . ( join q{ }, map {"<$_>"} $grammar->g0_rule($g0_rule_id) ) . "\n";
    }

=for Marpa::R2::Display::End

Please prefer L<"rule_expand()">.
Returns a list of the L0 rule ID's.

=head2 g1_rule_ids()

=for Marpa::R2::Display
name: Scanless rule() synopsis
normalize-whitespace: 1

    my @g1_rule_ids = $grammar->g1_rule_ids();
    for my $g1_rule_id (@g1_rule_ids) {
        $g1_rules_description .= "$g1_rule_id "
            . ( join q{ }, map {"<$_>"} $grammar->rule($g1_rule_id) ) . "\n";
    }

=for Marpa::R2::Display::End

Please prefer L<"rule_expand()">.
Returns a list of the G1 rule ID's.

=head2 rule()

=for Marpa::R2::Display
name: Scanless rule() synopsis

    my @g1_rule_ids = $grammar->g1_rule_ids();
    for my $g1_rule_id (@g1_rule_ids) {
        $g1_rules_description .= "$g1_rule_id "
            . ( join q{ }, map {"<$_>"} $grammar->rule($g1_rule_id) ) . "\n";
    }

=for Marpa::R2::Display::End

Please prefer L<"rule_expand()">, together with
L<"symbol_name()"> or
L<"symbol_display_form()">.
Given a G1 rule ID as its argument,
returns an array containing the
names of the symbols of that rule.
The C<rule()> method
returns a Perl false if no G1 rule with that rule ID exists.
If the rule ID exists,
C<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 C<rule()> method is useful in
combination with
the SLIF's
of L<the progress method|Marpa::R2::Scanless::R/progress()>,
whose output identifies rules by rule ID.

=head1 Copyright and License

=for Marpa::R2::Display
ignore: 1

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

=for Marpa::R2::Display::End

=cut

# Local Variables:
#   mode: cperl
#   cperl-indent-level: 4
#   fill-column: 100
# End:
# vim: expandtab shiftwidth=4: