NAME

Wraith - Parser Combinator in Perl

SYNOPSIS

use Wraith;

my ($expn, $term, $factor, $num);
wraith_rule->makerules(\$expn, \$term, \$factor, \$num);

$expn = ( (\$term >> $wraith::token->('\+') >> \$expn) ** sub { [ $_[0]->[0] + $_[0]->[2] ] } ) |
        ( (\$term >> $wraith::token->('-') >> \$expn) ** sub { [ $_[0]->[0] - $_[0]->[2] ] } ) |
        ( \$term );

$term = ( (\$factor >> $wraith::token->('\*') >> \$term) ** sub { [ $_[0]->[0] * $_[0]->[2] ] } ) |
        ( (\$factor >> $wraith::token->('\/') >> \$term) **
            sub { $_[0]->[2] ? [ $_[0]->[0] / $_[0]->[2] ] : [] } ) |
        ( \$factor );

$factor = ( (\$num) ** sub { my $args = $_[0]; my $val = undef; for my $elt (@$args) { $val .= $elt; } [ $val ] } ) |
          ( ( $wraith::token->('\(') >> \$expn >> $wraith::token->('\)') ) ** sub { my $args = $_[0]; [ $args->[1] ] } );

$num = $wraith::token->('[1-9][0-9]*');

print $expn->('2 + (4 - 1) * 3 + 4 -2')->[0]->[0]->[0], "\n";

DESCRIPTION

Wraith is a simple parser combinator library (not monadic nor memoized) inspired
by Boost.Spirit. It is not complete as Spirit but the fundamental operators are
implemented.

When applied with arguments, all operators/combinators return a function, which 
takes a string as input sentence(s) and return a reference to a list of pairs:
[ $pair_1, $pair_2, ..., $pair_n ],
where each pair is a reference to a two-element list:
[ ref_to_list_of_results, input_unprocessed ],
in which ref_to_list_of_results is a reference to a list of analysis results and
input_unprocessed is a string representing the unprocessed input so far.


=head2 Basic Operators:

    =head3 reference $succeed

        It is a curried version of operator succeed. The first parameter of succeed is
        the analysis result and the second parameter is the unprocessed input string.

    =head3 reference $fail

        It takes an argument, discards it and return an empty list.

        Those two operators are rarely used. Use them if you need new combinators.

    =head3 reference $literal

        It takes one character as the only argument. The returned function match the first 
        character of its input against the argument character and return (argument, input_left)
        if matched, where input_left is the input without its first character, or return
        an empty list if failed to match.

    =head3 reference $literals

        Almost the same as $literal, but takes a string as the only argument and match
        the first character of input with each character in argument string until matched.

    =head3 reference $token

        Takes a regex string as its first argument. The second and optional argument is a
        regex string of skipped strings. It matches the regex at the beginning of the
        input string, return (token, input_left) if matched or an empty list if failed.

=head2 Combinators:

    There are four combinators: then for sequence, alt for alternative, many for kleene
    star and using for semantic actions. Except many, the combinators are overloaded
    perl operators which takes at least one operator, combinator, compsite of combinators,
    product, or reference to an instance of those classes as the left-hand-side operand.

    The returned list of function generated by combinators is a list of tokens in the
    order of they appeared in the products.

    =head3 operator >> 

        Sequence combinator. For example, the product S -> T S would be written as
            $S = \$T >> $S;
        where $S and $T are rules, i.e, products.

    =head3 operator | 

        Alternative combinator. For example, the product S -> P | Q would be written as
            $S = \$T | \$Q;
        where $S, $T and $Q are rules.

    =head3 operator **

        Using combinator. It takes a operator, combinator, compsite of combinators, product,
        or reference to an instance of those classes as the left-hand-side operand and a
        subroutine as the right-hand-side operand. The returned value of lhs operand will
        be passed to rhs operand, and the returned value of rhs operand applied with its
        argument will be returned. This combinator is used for semantic actions.
        The returned value must be a reference to a list containing all the results given
        by the semantic subroutine.

    =head3 reference $many

        Kleene star combinator. The argument combinator will be matched at least zero time.
        The returned value is a list of all possible matchings.

=head2 Rules:

    Rules are products. Products are compsite of operators and/or combinators. To create
    a product, a scalar variable must be declared,
        my $P;
    and then, call Wraith_rules->makerules(\$P) to make it a rule.

    =head3 Wraith_rules->makerules( @list_of_references_to_products )

        It takes a list of references to would-be rules and returned the blessed references.
        However the returned values can be omitted for the contents of the variables are
        already blessed. Thus, the variables are able to use the overloaded operators.

AUTHOR

Bo Wang <sceneviper@hotmail.com>

COPYRIGHT

Copyright 2013 - Bo Wang

SEE ALSO

Parser::Combinators, which implements parsec-like parser combinators.

LICENSE

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