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

Name

Marpa::R3::Valuer - Valuer objects

Synopsis

    use Marpa::R3;

    my $dsl = <<'END_OF_DSL';

    Calculator ::= Expression action => ::first

    Factor ::= Number action => ::first
    Term ::=
        Term '*' Factor action => do_multiply
        | Factor action => ::first
    Expression ::=
        Expression '+' Term action => do_add
        | Term action => ::first
    Number ~ digits
    digits ~ [\d]+
    :discard ~ whitespace
    whitespace ~ [\s]+
    END_OF_DSL

    my $grammar = Marpa::R3::Scanless::G->new(
        {
            semantics_package => 'My_Actions',
            source            => \$dsl
        }
    );
    my $recce       = Marpa::R3::Scanless::R->new( { grammar => $grammar } );
    my $input       = '42 * 1 + 7';
    my $length_read = $recce->read( \$input );

    die "Read ended after $length_read of ", length $input, " characters"
        if $length_read != length $input;

    my $valuer = Marpa::R3::Scanless::V->new( { recognizer => $recce } );
    my $value_ref = $valuer->value();
    my $value = ${$value_ref};
    sub My_Actions::do_add {
        my ( undef, $values ) = @_;
        my ( $t1, undef, $t2 ) = @{$values};
        return $t1 + $t2;
    }

    sub My_Actions::do_multiply {
        my ( undef, $values ) = @_;
        my ( $t1, undef, $t2 ) = @{$values};
        return $t1 * $t2;
    }

About this document

This page is the reference document for the valuer objects of Marpa's SLIF (Scanless interface).

Many applications, probably the majority, will not need the SLIF valuer class or its methods. Instead, they will find the $recognizer->value() method method sufficient for their needs.

The methods in this document will be needed by applications that wish to do one of more of the following:

  • Treat an ambiguous parse as something other than an error.

  • Get more than one of the values from an ambiguous parse.

  • Set an end-of-parse location other than the default.

  • Have more than one valuer active at a time.

  • Use one of the valuer methods, as described in this document.

Valuer settings

The valuer settings are the named arguments accepted by the valuer's constructor or its set() method.

end

Most users will not need this setting. The end setting specifies the parse end, as a G1 location. The default is for the parse to end where the input did, so that the parse returned is of the entire virtual input stream. The end setting is only allowed in a valuer's constructor.

max_parses

If non-zero, causes a fatal error when that number of parse results is exceeded. max_parses is useful to limit CPU usage and output length when testing and debugging. Stable and production applications may prefer to count the number of parses, and take a less Draconian response when the count is exceeded.

The value must be an integer. If it is zero, there will be no limit on the number of parse results returned. The default is for there to be no limit. The max_parses setting is allowed by both the valuer's constructor and its set() method.

recognizer

The value of the recognizer setting must be a SLIF recognizer object. The new() method is required to have a recognizer setting. The recognizer setting is only allowed in a valuer's constructor.

trace_values

The value of the trace_values setting is a numeric trace level. If the numeric trace level is 1, Marpa prints tracing information as values are computed in the evaluation stack. A trace level of 0 turns value tracing off, which is the default. Traces are written to the trace file handle. The trace_values setting is allowed by both the valuer's constructor and its set() method.

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 inherited from the grammar. The trace_file_handle setting is allowed by both the valuer's constructor and its set() method.

Constructor

    my $valuer = Marpa::R3::Scanless::V->new( { recognizer => $recce } );

The new() method is the constructor for SLIF valuers. The arguments to the new() constructor must be one or more hashes of named arguments, where each hash key is a valuers setting. The recognizer valuer setting is required. All other valuer settings are optional. For more on valuer settings, see the section describing them.

Mutators

set()

    $valuer->set( { trace_values => 3 } );

This method allows valuer settings to be changed after a SLIF grammar is created. The arguments to set() must be one or more hashes whose key-value pairs are valuer settings and their values. The allowed valuer settings are described above.

Return values: The return value is reserved for future use. Failures are always thrown.

valuer value()

    my $value_ref = $valuer->value();

The value() method allows one optional argument. Call this argument $self. If specified, $self explicitly specifies the per-parse argument for the parse tree. The function of the per-parse argument is detailed in the description of the value() method of the recognizer.

The value() method of the valuer is an iterator. Each call of value() evaluates the next parse tree for the valuer object. value() succeeds if there is a parse tree and it can be evaluated. On success, value() returns a reference to the parse result for that parse tree. The value of a successful evaluation of a parse tree can be a Perl undef, in which case, and as implied above, value() returns a reference to Perl undef.

A soft failure occurs if there are no parse trees left to evaluate, in which case the value() method returns undef. All other failures are hard failures.

There will be more than one parse tree if the parse was ambiguous. There will be zero parse trees if there was no valid parse of the input according to the grammar. If there are zero parse trees, the first call of the value() method for a valuer will produce a soft failure.

Return values: On success, returns a reference to the parse result for a parse tree. If there are no more parse trees, returns a Perl undef. Hard failures are thrown.

Accessors

ambiguity_level()

    my $ambiguity_level = $valuer->ambiguity_level();

Succeeds and returns 1 if there was an unambiguous parse, in other words if there was exactly one parse tree. Succeeds and returns 2 if the parse was ambiguous, in other words if there was more than one parse tree. Succeeds and returns 0 if there are zero parse trees, in other words if no parse was found. Failures are thrown.

ambiguous()

    $ambiguity_status = $valuer->ambiguous();
    if ( $ambiguity_status ) {
        chomp $ambiguity_status;
        die "Parse is ambiguous\n", $ambiguity_status;
    }

If there is exactly one parse, returns the empty string. If there is no parse, returns a non-empty string indicating that fact. If there are two or more parses, returns a non-empty string describing the ambiguity.

The non-empty strings are intended only for reading by humans -- their exact format is subject to change. Applications can rely on the results of automated tests of the return value from ambiguous() only if that test is for empty versus non-empty.

g1_pos

    my $end_of_parse = $valuer->g1_pos();

Returns the G1 location of the end of parsing for this valuer.

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.