The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Marpa-R3-4.001_049
River stage zero No dependents
2 ++
/ Marpa::R3::Scanless::G

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.

Errors

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

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 allow 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. 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

highest_production_id()

    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);
    }

Returns the production ID that is, numerically, the highest. For the purpose of writing loops over all of the production IDs, you may prefer 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.

highest_symbol_id()

    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);
    }

Returns the symbol ID that is, numerically, the highest. For the purpose of writing loops over all of the symbol IDs, you may prefer 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.

production_dotted_show()

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

Returns a string showing the dotted production for $production_id and $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 N, where 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 production_dotted_show() is subject to change.

production_expand()

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

"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.

production_ids_gen()

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

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 undef.

production_length()

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

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

production_name()

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

Given a production ID, returns the production name. A production name is as defined by the name adverb. If no production name was defined, the production name is the name of the LHS symbol. Production names are not necessarily unique.

production_show()

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

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 productions_show() is subject to change.

productions_show()

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

The 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, 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 productions_show() is subject to change.

start_symbol_id()

    $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 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.

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. 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_gen()

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

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 undef.

symbol_name()

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

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.

symbol_show()

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

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.

symbols_show()

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

The 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, 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 symbols_show() is subject to change.

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.