# 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 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(
        {
            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
        }
    );

=for Marpa::R3::Display::End

=head1 About this document

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

=head1 Errors

All errors in these methods are thrown, unless specifically
documented otherwise.

=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> grammar setting|Marpa::R3::Scanless::G/"semantics_package">.
The two are not closely related.

=head2 exhaustion

The C<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
L<description of exhaustion parse events|Marpa::R3::Event/"Exhaustion events">.

The value
of the C<exhaustion> grammar setting
must be either "C<fatal>"
or "C<event>".
"C<fatal>" is the default.
If the value is "C<fatal>",
asynchronous parse exhaustion is treated as an error,
and an exception is thrown.
If the value is "C<event>",
an event occurs
as described in the
L<section on exhaustion parse events|Marpa::R3::Event/"Exhaustion events">.

=head2 ranking_method

The C<ranking_method>
is only allowed in
calls of the L<C<new()>|/"Constructor"> method.
The value must be a string:
one of "C<none>",
"C<rule>",
or "C<high_rule_only>".
When the value is "C<none>", Marpa returns the parse results
in arbitrary order.
This is the default.

The "C<rule>"
and "C<high_rule_only>" ranking methods
allow the user
to control the order
in which parse results are returned by
the C<value> method,
and to exclude some parse results from the parse series.
For details, see L<the document
on parse order|Marpa::R3::Semantics::Order>.

=head2 rejection

The C<rejection> grammar setting
determines what happens when all tokens are rejected.
The value must be either "C<fatal>"
or "C<event>".
"C<fatal>" is the default.

If the value is "C<fatal>",
rejection of all tokens is treated as an error,
and an exception is thrown.
If the value is "C<event>",
an event occurs
as described in the
L<section on rejection parse events|Marpa::R3::Event/"Rejection events">.

=head2 semantics_package

Sets the semantic package for the grammar.
The C<semantics_package> grammar setting
is used when resolving action names to
fully qualified Perl names.
For more details on the SLIF semantics,
see the L<document on SLIF
semantics|Marpa::R3::Semantics>.

The C<semantics_package> grammar setting
should not be confused with the
L<SLIF's
C<bless_package> grammar setting|Marpa::R3::Scanless::G/"bless_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(
        {
            semantics_package => 'My_Actions',
            source            => \$dsl
        }
    );
    my $input     = '42 * 1 + 7';
    my $value_ref = $grammar->parse( \$input );

=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.
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,
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 highest_production_id()

=for Marpa::R3::Display
name: SLG highest_production_id() synopsis
normalize-whitespace: 1

    my $max_production_id = $grammar->highest_production_id();
    for (
        my $production_id = 1 ;
        $production_id <= $max_production_id ;
        $production_id++
      )
    {
        production_faire_des_choses($production_id);
    }

=for Marpa::R3::Display::End

Returns the production ID that is,
numerically, the highest.
For the purpose of writing loops over
all of the production IDs, you
may prefer
L<production_ids_gen()|/"production_ids_gen()">.
The lowest production ID 
is always 1.
Any production ID between the lowest and the highest production ID,
inclusive,
is guaranteed to be valid.

=head2 highest_symbol_id()

=for Marpa::R3::Display
name: SLG highest_symbol_id() synopsis
normalize-whitespace: 1

    my $max_symbol_id = $grammar->highest_symbol_id();
    for ( my $symbol_id = 1 ; $symbol_id <= $max_symbol_id ; $symbol_id++ ) {
        symbol_faire_des_choses($symbol_id);
    }

=for Marpa::R3::Display::End

Returns the symbol ID that is,
numerically, the highest.
For the purpose of writing loops over
all of the symbol IDs, you
may prefer
L<symbol_ids_gen()|/"symbol_ids_gen()">.
The lowest symbol ID 
is always 1.
Any symbol ID between the lowest and the highest symbol ID,
inclusive,
is guaranteed to be valid.

=head2 production_dotted_show()

=for Marpa::R3::Display
name: SLG production_dotted_show() synopsis

    $production_dotted_results .=
      $grammar->production_dotted_show( $production_id, $dot_position ) . "\n";

=for Marpa::R3::Display::End

Returns a string showing the dotted production 
for C<$production_id> and C<$dot_position>.

Argument 1 (reguired): A production ID.

Argument 2 (reguired): A valid dot position in the production.
Valid dot positions are from 0 to I<N>, where I<N> is the length
of the RHS of the production.

Return on success: A string describing that production in a form which is useful for tracing and debugging.
To allow for improvements in Marpa::R3,
the output of C<production_dotted_show()> is subject to change.

=head2 production_expand()

=for Marpa::R3::Display
name: SLG production_expand() synopsis

    my ($lhs_id, @rhs_ids) = $grammar->production_expand($production_id);
    $production_expand_results .= "Production #$production_id: $lhs_id ::= " . (join q{ }, @rhs_ids) . "\n";

=for Marpa::R3::Display::End

"Expands" a
production ID into symbol ID's.

Argument 1 (required):
The only argument is the ID of the production to be expanded.

Return value: 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.

=head2 production_ids_gen()

=for Marpa::R3::Display
name: SLG production_ids_gen() synopsis
normalize-whitespace: 1

    for (
        my $iter = $grammar->production_ids_gen() ;
        defined( my $prid = $iter->() ) ;
      )
    {
        do_something($prid);
    }


=for Marpa::R3::Display::End

Returns an iterator function for the production IDs,
suitable for looping through them.
The first call of the iterator returns the first production ID.
Successive calls return the other production IDs,
in numeric order.
The iterator never returns the same production ID twice.
Once an iterator has returned every possible production ID,
it returns a Perl C<undef>.

=head2 production_length()

=for Marpa::R3::Display
name: SLG production_length() synopsis

    my $length = $grammar->production_length($production_id);
    $production_length_results .= "Production #$production_id: length=$length\n";

=for Marpa::R3::Display::End

Given a production ID, returns the length of its RHS.

=head2 production_name()

=for Marpa::R3::Display
name: SLG production_name() synopsis

    my $name = $grammar->production_name($production_id);
    $production_name_results .= "Production #$production_id: $name\n";

=for Marpa::R3::Display::End

Given a production ID, returns the production name.
A production name is as defined by
L<the C<name> adverb|Marpa::R3::Scanless::DSL/"name">.
If no production name was defined,
the production name is the name of
the LHS symbol.
Production names are not necessarily unique.

=head2 production_show()

=for Marpa::R3::Display
name: SLG production_show() synopsis

    my $production_description = $grammar->production_show($prid);

=for Marpa::R3::Display::End

Argument 1 (required): The first argument
is the ID of a production.

Return value: a string describing that production in a form which is useful for tracing and debugging.
To allow for improvements in Marpa::R3,
the output of C<productions_show()> is subject to change.

=head2 productions_show()

=for Marpa::R3::Display
name: SLG productions_show() synopsis
partial: 1
normalize-whitespace: 1

    $productions_show_output = $grammar->productions_show();

=for Marpa::R3::Display::End

=for Marpa::R3::Display
name: SLG productions_show() verbose synopsis
partial: 1
normalize-whitespace: 1

    $productions_show_output = $grammar->productions_show( { verbose => 3 } );

=for Marpa::R3::Display::End

The C<productions_show()> method returns a description of
the grammar's productions.
It is useful for understanding the rules as they
appear in trace and debugging outputs.

Argument 1 (optional):
The only argument is a hash whose keys are
named arguments and whose values are the values
of the corresponding named argument.
Currently there is only one named argument,
C<verbose>, whose value is a verbosity level.
Verbosity level must be an integer.

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.

Return value: A description of the grammar's productions.
To allow for improvements in Marpa::R3,
the output of C<productions_show()> is subject to change.

=head2 start_symbol_id()

=for Marpa::R3::Display
name: SLG start_symbol_id() synopsis

    $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 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 of a symbol is always defined.
The display form of a symbol is not suitable for use as a name:
it is not necessarily unique,
and it 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.
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_gen()

=for Marpa::R3::Display
name: SLG symbol_ids_gen() synopsis
normalize-whitespace: 1

    for (
        my $iter = $grammar->symbol_ids_gen() ;
        defined( my $symbol_id = $iter->() ) ;
      )
    {
        do_something($symbol_id);
    }

=for Marpa::R3::Display::End

Returns an iterator function for the symbol IDs,
suitable for looping through them.
The first call of the iterator returns the first symbol ID.
Successive calls return the other symbol IDs,
in numeric order.
The iterator never returns the same symbol ID twice.
Once an iterator has returned every possible symbol ID,
it returns a Perl C<undef>.

=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

Argument 1 (required): The only argument is a symbol ID.

Return value: The return value is the name of the symbol.
For every valid symbol ID,
this method's return value will be defined
and will be unique to that symbol ID.
The return value may be an internal name,
which is subject to change in future versions of Marpa::R3.

=head2 symbol_show()

=for Marpa::R3::Display
name: SLG symbol_show() synopsis

    $symbol_show_results .= $grammar->symbol_show($symbol_id);

=for Marpa::R3::Display::End

The first argument, which is required,
is the ID of a symbol.
Returns a string describing that symbol in a form which is useful for tracing and debugging,
but which is subject to change in future versions of Marpa::R3.

=head2 symbols_show()

=for Marpa::R3::Display
name: SLG symbols_show() synopsis
partial: 1
normalize-whitespace: 1

    $symbols_show_output = $grammar->symbols_show();

=for Marpa::R3::Display::End

=for Marpa::R3::Display
name: SLG symbols_show() verbose synopsis
partial: 1
normalize-whitespace: 1

    $symbols_show_output = $grammar->symbols_show( { verbose => 3 } );

=for Marpa::R3::Display::End

The C<symbols_show()> method returns a description of
the grammar's symbols.
It is useful for understanding the symbols as they
appear in trace and debugging outputs.

Argument 1 (optional):
The only argument is a hash whose keys are
named arguments and whose values are the values
of the corresponding named argument.
Currently there is only one named argument,
C<verbose>, whose value is a verbosity level.
Verbosity level must be an integer.

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.

Return value: A description of the grammar's symbols.
To allow for improvements in Marpa::R3,
the output of C<symbols_show()> is subject to change.

=head1 COPYRIGHT AND LICENSE

=for Marpa::R3::Display
ignore: 1

  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.

=for Marpa::R3::Display::End

=cut

# vim: expandtab shiftwidth=4: