view release on metacpan or  search on metacpan

pod/Glade.pod  view on Meta::CPAN

    if ( $recce->ambiguity_metric() > 1 ) {
        my $asf = Marpa::R2::ASF->new( { slr => $recce } );
        die 'No ASF' if not defined $asf;
        my $ambiguities = Marpa::R2::Internal::ASF::ambiguities($asf);

        # Only report the first two
        my @ambiguities = grep {defined} @{$ambiguities}[ 0 .. 1 ];

        $actual_value = 'Application grammar is ambiguous';
        $actual_result =
            Marpa::R2::Internal::ASF::ambiguities_show( $asf, \@ambiguities );
        last PROCESSING;
    } ## end if ( $recce->ambiguity_metric() > 1 )

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

=head2 ambiguities()

=for Marpa::R2::Display
name: ASF ambiguity reporting
normalize-whitespace: 1
partial: 1

    my $ambiguities = Marpa::R2::Internal::ASF::ambiguities($asf);

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

Returns a reference to an array of ambiguity reports in the ASF.
The first and only argument must be an ASF object.
The array returned will be be zero length if the parse was not ambiguous.
Ambiguity reports are as L<described below|"Ambiguity reports">.

While the C<ambiguities()> method can be called to determine whether
or not ambiguities exist, it is the more expensive way to do it.
The L<$slr-E<gt>ambiguity_metric() method|Marpa::R2::Scanless::R/"ambiguity_metric()">
tests an already-existing boolean and is therefore extremely fast.
If you are simply testing for ambiguity,
use the C<ambiguity_metric()> method instead.
If you can save time when you know that a parse is unambiguous,
you may want to test for ambiguity with the C<ambiguity_metric()> method
before calling the C<ambiguities()> method.

=head2 ambiguities_show()

=for Marpa::R2::Display
name: ASF ambiguity reporting
normalize-whitespace: 1
partial: 1

  $actual_result =
    Marpa::R2::Internal::ASF::ambiguities_show( $asf, \@ambiguities );

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

Returns a string which contains a description of the ambiguities in its arguments.
Takes two arguments, both required.
The first is an ASF, and the second is a reference to an array of ambiguities,
in the format returned by L<the ambiguities() method|/"ambiguities()">.

Major applications will often have their own 
customized ambiguity formatting routine, one which can formulate
error messages based, not just on the names of the rules and symbols,
but on knowledge of the role that
the rules and symbols play in
the application.
This method is intended for applications which do not have
their own customized ambiguity handling.
For those which do, it can be used
as a fallback for handling those reports that the customized method does not recognize
or that do not need special handling.
The format of the returned string
and is subject to change,
and is intended for reading by humans only.

=head1 Ambiguity reports

The ambiguity reports returned by the L<C<ambiguities()> method|/"ambiguities()">
are of two kinds: symch reports and factoring reports.
Only ambiguities uppermost on a path are reported --
in other words, an ambiguity
is not reported if it is downhill
and does not have a higher altitude.
(Because of cycles,
it is possible for a downhill glade to be at a higher altitude.)
Within glade, all of the factorings are 
considered downhill from,
and of equal altitude to the symches,
so that if a glade has a symch ambiguity,
there will be no factoring ambiguity reports for that glade.

Typically, when there is more than one kind of ambiguity in an input span, only
one is of real interest,
and
symch ambiguities are usually of more interest than factorings.
And if one ambiguity is uphill from another, the downhill ambiguity is usually
a side effect of the uphill one and
of little interest.

=head2 Symch reports

A symch report is issued whenever, in a top-down traversal of the ASF,
a glade is encountered which has more than one symch.
A symch report takes the form

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

   [ 'symch', $glade ]

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

where C<$glade> is the ID of the glade with the symch ambiguity.
With this and the accessor methods in this document, an application can report full
details of the symch ambiguity.

=head2 Factoring reports

A factoring report identifies
a sequence of RHS symbols which has more than one factoring.
Factoring reports identify not just a rule,
but specific subsequences within the RHS