Skip to content
Generate pretty errors when a Perl 6 grammar parse fails
Other Makefile
  1. Other 96.2%
  2. Makefile 3.8%
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
eg
lib/Grammar
t
.travis.yml
META6.json
Makefile
README.md

README.md

Grammar::PrettyErrors

Build Status

Make grammars fail parsing with a pretty error instead of returning nil.

SYNOPSIS

Input:

use Grammar::PrettyErrors;

grammar G does Grammar::PrettyErrors {
  rule TOP {
    'orange'+ % ' '
  }
}

# Handle the failure.
G.parse('orange orange orange banana') orelse
    say "parse failed at line {.exception.line}";

# Don't handle it, an exception will be thrown:
G.parse('orange orange orange banana');

Output:

failed at line 1

--errors--
  1 │▶orange orange orange banana
                           ^

Uh oh, something went wrong around line 1.
Unable to parse TOP.

DESCRIPTION

When the Grammar::PrettyErrors role is applied to a Grammar, it changes the behavior of a parse failure. Instead of returning nil, a failure is thrown. The exception object has information about the context of the failure, and a pretty error message that includes some context around the input text.

It works by wrapping the <ws> token and keeping track of a highwater mark (the position), and the name of the most recent rule that was encountered.

This technique is described by moritz in his excellent book [0] (see below).

CLASSES, ROLES

Grammar::PrettyErrors (Role)

ATTRIBUTES

  • quiet -- Bool, default false: just save the error, don't throw it.

  • colors -- Bool, default true: make output colorful.

  • error -- a X::Grammar::PrettyError object (below).

METHODS

  • new -- wraps the <ws> token as described above, it also takes additional named arguments (to set the ATTRIBUTEs above).

X::Grammar::PrettyError (class)

METHODS

  • line -- the line number at which the parse failed (starting at 1). Or 0 if no lines were parsed;

  • column -- the column at which the parse failed (starting at 1). Or 0 if no characters were parsed;

  • lastrule -- the last rule which was parsed.

  • report -- the text of a report including the above information, with a few lines before and after. (see SYNOPSIS)

  • message -- Same as report.

EXAMPLES

grammar G does Grammar::PrettyErrors { ... }

# Throw an exception with a message when a parse fails.
G.parse('orange orange orange banana');

# Same thing
G.new.parse('orange orange orange banana');

# Pass options to the constructor.  Don't throw a failure.
my $g = G.new(:quiet, :!colors);
$g.parse('orange orange orange banana');
# Just print it ourselves.
say .report with $g.error;

# Use the failure to handle it without throwing it.
G.parse('orange orange orange banana') orelse
    say "parse failed at line {.exception.line}";

SEE ALSO

AUTHOR

Brian Duggan

You can’t perform that action at this time.