Sponsoring The Perl Toolchain Summit 2025: Help make this important event another success Learn more

NAME

Pugs::Compiler::Rule - Compiler for Perl 6 Rules

SYNOPSIS

Un-named rules are objects:

my $rule = Pugs::Compiler::Rule->compile( '((.).).' );
my $match = $rule->match( 'abc' );
if ($match) { # true
print $match; # "abc"
print $match->from; # 0
print $match->to; # 3
print $match->[0]; # "ab"
print $match->[0][0]; # "a"
}

Named rules are methods in a Grammar:

package MyGrammar;
*rule = Pugs::Compiler::Rule->compile( '((.).).' )->code;
my $match = MyGrammar->rule( 'abc' );

Rules may have parameters:

*subrule = $grammar->compile( $source, { signature => $sig } )->code;
*rule = $grammar->compile( '
<subrule: param1, param2>
' )->code;

DESCRIPTION

This module provides an implementation for Perl 6 Rules. It is a front-end to several other modules:

Implemented Features

<ws>
#comment\n
.
? * + *? +? ??
literal
[]
()
|
<'literal'>
<subrule>
<namespace::subrule>
<$var>
<?subrule>
<!subrule>
<before ...>
<after ...> -- implemented in :ratchet mode only
<subrule('param')> -- constant parameters only
%hash
<@var> -- special-cased for array-of-rule (but not Rule|Str)
\char -- not all chars implemented
{code} -- non-capturing closure
-- perl5 syntax inside closure
-- $/ doesn't work yet
{ return code } -- capturing closure
-- perl5 syntax inside closure
-- $/ works
$var := (capture) -- capture aliasing
$<> $/<> -- special variables can't be used inside a match yet
$/
$<0> $<1>
$0 $1
\n \N
$^a $^b -- positional parameters (must start with $^a)
^ $
:

Unimplemented or untested features

$variable
@variable
$/<0> $/<1>
$/0 $/1
<"literal">
^^ $$
<unicode-class> <+unicode-class> <+unicode-class+unicode-class>
<&var>
<%var>
**{n..m}
:: ::: (commit)
$var := [non-capture]
$var := <rule>
<(closure-assertion)> <{code-returns-rule}>
<<character-class>> <[character-class]>
:flag :flag() :flag[]
\x0a \0123 ...
&
$1 - lvalue match variables
$/ $() - global match variables

METHODS

compile (Str $rule_source, \%options )

Class method. Returns a compiled rule object, or throws an exception on invalid rule syntax.

options:

  • grammar => $class - Specify which namespace (Grammar) the rule belongs to.

  • ratchet => 1 - Disable backtracking. Match faster. Defaults to 1 in Rules and Tokens.

  • pos => $pos - Specify a string position to match. Starts in zero. Defaults to undef.

  • sigspace => 1 - Whitespace is significant. Defaults to 1 in Rules.

match (Str $match_against)

Instance method. Returns a Pugs::Runtime::Match object (or Pugs::Runtime::Match::Ratchet).

perl5

Instance method. Returns a string that can be eval'ed into a rule/token/regex object.

CAVEATS

This is an experimental development version. The API is still in flux.

The set of implemented features depends on the ratchet switch.

AUTHORS

The Pugs Team <perl6-compiler@perl.org>.

Please join us on irc.freenode.net #perl6 if you'd like to participate.

SEE ALSO

The Perl 6 Rules Spec: http://dev.perl.org/perl6/doc/design/syn/S05.html

COPYRIGHT

Copyright 2006 by Flavio Soibelmann Glock and others.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

3 POD Errors

The following errors were encountered while parsing the POD:

Around line 69:

You can't have =items (as at line 73) unless the first thing after the =over is an =item

Around line 178:

'=item' outside of any '=over'

Around line 187:

You forgot a '=back' before '=head2'