NAME

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

SYNOPSIS

Un-named rules are objects:

    use Pugs::Compiler::Rule;

    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;
    use Pugs::Compiler::Rule;
    use base 'Pugs::Grammar::Base';

    Pugs::Compiler::Rule->install( rule => '((.).).' );
    my $match = MyGrammar->rule( 'abc' );

Rules may have parameters:

    $grammar->install(subrule => $source, { signature => $sig } );

    $grammar->install(rule => q{
            <subrule: param1, param2>
    });

DESCRIPTION

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

* Front-end Modules

* Pugs::Compiler::Rule compiles Perl 6 Rules to Perl 5.

* Pugs::Compiler::Token compiles Perl 6 Tokens to Perl 5.

* Pugs::Compiler::Regex compiles Perl 6 Regexes to Perl 5.

* Pugs::Compiler::RegexPerl5 wraps Perl 5 Regexes to return a Match object.

* Runtime Classes

* Pugs::Runtime::Rule provides the runtime engine for Rules.

* Pugs::Runtime::Match represents a Match object.

* Pugs::Runtime::Match::Ratchet represents a Match object matched with :ratchet.

* Pugs::Runtime::Grammar represents a Grammar class / object.

* Grammars

* Pugs::Grammar::Rule parses the Rules syntax.

* Pugs::Grammar::Rule::Rule specifies the Rules syntax with Rules.

* Pugs::Grammar::Base is the base Grammar: <ws>, <space>.

* Code Emitters

* Pugs::Emitter::Rule::Perl5 converts parsed Rules to Perl 5 code.

* Pugs::Emitter::Rule::Perl5::Ratchet converts parsed :ratchet Rules to Perl 5 code.

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.

* Perl5 => 1

Use Perl 5 grammar and semantics for Regex.

match (Str $match_against)

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

install (Str $name, Str $rule_source, \%options)

Install a rule into the method $name. If $name is fully qualified then it will be installed into that path e.g MyGrammar::rulename, otherwise it will install it into the current package.

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

cpanm Pugs::Compiler::Rule

perl -MCPAN -e shell
install Pugs::Compiler::Rule