Rules / Types, classes & roles / domain-specific

Grammar Reference

Formal grammar made up of named regexes

What it is #

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

method parse #

method parse($target, :$rule = 'TOP',  Capture() :$args = \(), Mu :$actions = Mu, *%opt)

Parses the $target, which will be coerced to Str if it isn't one, using $rule as the starting rule. Additional $args will be passed to the starting rule if provided. If the actions named argument is provided, it will be used as an actions object, that is, for each successful regex match, a method of the same name, if it exists, is called on the actions object, passing the match object as the

method subparse #

method subparse($target, :$rule = 'TOP', Capture() :$args = \(),  Mu :$actions = Mu, *%opt)

Does exactly the same as method parse, except that cursor doesn't have to reach the end of the string to succeed. That is, it doesn't have to match the whole string. Note that unlike method parse, subparse always returns a Match, which will be a failed match (and thus falsy), if the grammar failed to match.

method parsefile #

method parsefile(Str(Cool) $filename, :$enc, *%opts)

Reads file $filename encoding by $enc, and parses it. All named arguments are passed on to method parse.

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

2 doc-drift · 11 no-output · 1 not-runnable · 1 ok

class Grammar is Match {}

Not executed: the documentation states no expected output for this example.

grammar Identifier {
    token TOP       { <initial> <rest>* }
    token initial   { <+myletter +[_]> }
    token rest      { <+myletter +mynumber +[_]> }
    token myletter  { <[A..Za..z]> }
    token mynumber  { <[0..9]> }
}

Not executed: the documentation states no expected output for this example.

say Identifier.isa(Grammar);                # OUTPUT: «True␤»
my $match = Identifier.parse('W4anD0eR96');
say ~$match;                                # OUTPUT: «W4anD0eR96␤»

Neither engine can run this in isolation — the example depends on context from the surrounding text.

grammar RepeatChar {
    token start($character) { $character+ }
}

Not executed: the documentation states no expected output for this example.

say RepeatChar.parse('aaaaaa', :rule('start'), :args(\('a')));
say RepeatChar.parse('bbbbbb', :rule('start'), :args(\('b')));

Not executed: the documentation states no expected output for this example.

# OUTPUT:
# ｢aaaaaa｣
# ｢bbbbbb｣

Not executed: the documentation states no expected output for this example.

my $actions = class { method TOP($/) { say "7" } };
grammar { token TOP { a { say "42" } b } }.parse('ab', :$actions);
# OUTPUT: «42␤7␤»
Output
42
7

Documentation, Rakudo and Raku++ all agree.

say RepeatChar.parse('bbbbbb', :rule('start'), :args(\('b')), :pos(4)).Str;
# OUTPUT: «bb␤»
Documentation
bb
Rakudo
Raku++

Both engines agree; the documentation states something else. Trust the engines.

grammar RepeatChar {
    token start($character) { $character+ }
}

Not executed: the documentation states no expected output for this example.

say RepeatChar.subparse('bbbabb', :rule('start'), :args(\('b')));
say RepeatChar.parse(   'bbbabb', :rule('start'), :args(\('b')));
say RepeatChar.subparse('bbbabb', :rule('start'), :args(\('a')));
say RepeatChar.subparse('bbbabb', :rule('start'), :args(\('a')), :pos(3));

Not executed: the documentation states no expected output for this example.

# OUTPUT:
# ｢bbb｣
# Nil
# #<failed match>
# ｢a｣

Not executed: the documentation states no expected output for this example.

grammar Identifiers {
    token TOP        { [<identifier><.ws>]+ }
    token identifier { <initial> <rest>* }
    token initial    { <+myletter +[_]> }
    token rest       { <+myletter +mynumber +[_]> }
    token myletter   { <[A..Za..z]> }
    token mynumber   { <[0..9]> }
}

Not executed: the documentation states no expected output for this example.

say Identifiers.parsefile('users.txt', :enc('UTF-8'))
    .Str.trim.subst(/\n/, ',', :g);

Not executed: the documentation states no expected output for this example.

# users.txt :
# TimToady
# lizmat
# jnthn
# moritz
# zoffixznet
# MasterDuke17

Not executed: the documentation states no expected output for this example.

# OUTPUT: «TimToady,lizmat,jnthn,moritz,zoffixznet,MasterDuke17␤»
Documentation
TimToady,lizmat,jnthn,moritz,zoffixznet,MasterDuke17
Rakudo
Raku++

Both engines agree; the documentation states something else. Trust the engines.