/ 
HOP-Parser-0.02_04
River stage zero No dependents
/ HOP::Parser

NAME

HOP::Parser - "Higher Order Perl" Parser

VERSION

Version 0.02_04

SYNOPSIS

use HOP::Parser qw/:all/;

# assemble a bunch of parsers according to a grammar

DESCRIPTION

This package is based on the Parser.pm code from the book "Higher Order Perl", by Mark Jason Dominus.

This module implements recursive-descent parsers by allowing programmers to build a bunch of smaller parsers to represent grammar elements and assemble them into a full parser. Pages 376 to 415 of the first and second editions of HOP should be enough to get you up to speed :)

The PDF for the second edition can be downloaded from MJD's site: http://hop.perl.plover.com/book/pdf/HigherOrderPerl.pdf.

Please note that this module should be considered ALPHA code. While everything works fairly well, the documentation is incomplete and some of the functions could stand to be better named (rlist_of, for example).

EXPORT

  • absorb

  • action

  • alternate

  • concatenate

  • debug

  • fetch_error

  • End_of_Input

  • error

  • list_of

  • list_values_of

  • lookfor

  • match

  • lookahead

  • neg_lookahead

  • nothing

  • null_list

  • operator

  • optional

  • parser

  • rlist_of

  • rlist_values_of

  • star

  • plus

  • T

  • test

FUNCTIONS

nothing

my ($parsed, $remainder) = nothing($stream);

nothing is a special purpose parser which is used internally. It always succeeds and returns undef for $parsed and the $remainder is the unaltered input $stream.

End_of_Input

if (End_of_Input($stream)) {
  ...
}

End_of_Input is another special purpose parser which only succeeds if there is no input left in the stream. It's generally used in the start symbol of the grammar.

# entire_input ::= statements 'End_Of_Input'

my $entire_input = concatenate(
  $statements,
  \&End_of_Input
);

lookfor

my $parser = lookfor($label, [\&get_value], [$param]); # or
my $parser = lookfor(\@label_and_optional_values, [\&get_value], [$param]);
my ($parsed, $remaining_stream) = $parser->($stream);

The following details the arguments to lookfor.

  • $label or @label_and_optional_values

    The first argument is either a scalar with the token label or an array reference. The first element in the array reference should be the token label and subsequent elements can be anything you need. Usually the second element is the token value, but if you need more than this, that's OK.

  • \&get_value

    If an optional get_value subroutine is supplied, that get_value will be applied to the parsed value prior to it being returned. This is useful if non-standard tokens are being passed in or if we wish to preprocess the returned values.

  • $param

    If needed, additional arguments besides the current matched token can be passed to &get_value. Supply them as the third argument (which can be any data structure you wish, so long as it's a single scalar value).

In practice, the full power of this function is rarely needed and match is used instead.

match

my $parser = match($label, [$value]);
my ($parsed, $remainder) = $parser->($stream);

This function takes a label and an optional value and builds a parser which matches them by dispatching to lookfor with the arguments as an array reference. See lookfor for more information.

parser

my $parser = parser { 'some code' };

Currently, this is merely syntactic sugar that allows us to declare a naked block as a subroutine (i.e., omit the "sub" keyword).

lookahead

my $parser = lookahead( $label );
$parser = lookahead( $parser );

This function takes a parser argument or list of arguments supported by lookfor() and returns a parser that will return true if the parser matches, but does not actually change the stream. This is so that you can write parsers that match something and then look ahead to see if they match the next thing, without actualy consuming that next thing. This is akin to a zero width positive look-ahead in a regular expression.

neg_lookahead

my $parser = neg_lookahead( $label );
$parser = neg_lookahead( $parser );

This function returns a parser that returns true if it looks ahead and does not find a match for the specified parser. That is, it's akin to a zero width negative look-ahead in a regular expression. The supported arguments are the same as for lookahead().

concatenate

my $parser = concatenate(@parsers);
my ($values, $remainder) = $parser->($stream);

This function takes a list of parsers and returns a new parser. The new parser succeeds if all parsers passed to concatenate succeed sequentially.

concatenate will discard undefined values. This allows us to do this and only return the desired value(s):

concatenate(absorb($lparen), $value, absorb($rparen))

alternate

my $parser = alternate(@parsers);
my ($parsed, $remainder) = $parser->stream;

This function behaves like concatenate but matches one of any tokens (rather than all tokens sequentially).

list_of

my $parser = list_of( $element, $separator );
my ($parsed, $remainder) = $parser->($stream);

This function takes two parsers and returns a new parser which matches a $separator delimited list of $element items.

rlist_of

my $parser = list_of( $element, $separator );
my ($parsed, $remainder) = $parser->($stream);

This function takes two parsers and returns a new parser which matches a $separator delimited list of $element items. Unlike list_of, this parser expects a leading $separator in what it matches.

list_values_of

my $parser = list_of( $element, $separator );
my ($parsed, $remainder) = $parser->($stream);

This parser generator is the same as &list_of, but it only returns the elements, not the separators.

rlist_values_of

my $parser = list_of( $element, $separator );
my ($parsed, $remainder) = $parser->($stream);

This parser generator is the same as &list_values_of, but it only returns the elements, not the separators.

List rlist_of, it expects a separator at the beginning of the list.

absorb

my $parser = absorb( $parser );
my ($parsed, $remainder) = $parser->($stream);

This special-purpose parser will allow you to match a given item but not actually return anything. This is very useful when matching commas in lists, statement separators, etc.

T

my @result = T( $parser, \&transform );

Given a parser and a transformation sub, this function will apply the tranformation to the values returned by the parser, if any.

null_list

my ($parsed, $remainder) = null_list($stream);

This special purpose parser always succeeds and returns an empty array reference and the stream.

star

my $parser = star($another_parser);
my ($parsed, $remainder) = $parser->($stream);

This parser always succeeds and matches zero or more instances of $another_parser. It parallels the regular expression * quantifier. If it matches zero, it returns the same results as null_list. Otherwise, it returns and array ref of the matched values and the remainder of the stream.

plus

my $parser = plus($another_parser);
my ($parsed, $remainder) = $parser->($stream);

This parser succeeds when it matches one or more instances of $another_parser. It parallels the regular expression + quantifier. If it matches one or more, it returns and array ref of the matched values and the remainder of the stream.

optional

my $parser = optional($another_parser);
my ($parser, $remainder) = $parser->(stream);

This parser matches 0 or 1 of the given parser item. It parallels the regular expression ? quantifier.

AUTHOR

Mark Jason Dominus. Maintained by Curtis "Ovid" Poe, <ovid@cpan.org>

BUGS

Please report any bugs or feature requests to bug-hop-parser@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HOP-Parser. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

Many thanks to Mark Dominus and Elsevier, Inc. for allowing this work to be republished.

COPYRIGHT & LICENSE

Code derived from the book "Higher-Order Perl" by Mark Dominus, published by Morgan Kaufmann Publishers, Copyright 2005 by Elsevier Inc.

ABOUT THE SOFTWARE

All Software (code listings) presented in the book can be found on the companion website for the book (http://perl.plover.com/hop/) and is subject to the License agreements below.

LATEST VERSION

You can download the latest versions of these modules at http://github.com/Ovid/hop/. Feel free to fork and make changes.

ELSEVIER SOFTWARE LICENSE AGREEMENT

Please read the following agreement carefully before using this Software. This Software is licensed under the terms contained in this Software license agreement ("agreement"). By using this Software product, you, an individual, or entity including employees, agents and representatives ("you" or "your"), acknowledge that you have read this agreement, that you understand it, and that you agree to be bound by the terms and conditions of this agreement. Elsevier inc. ("Elsevier") expressly does not agree to license this Software product to you unless you assent to this agreement. If you do not agree with any of the following terms, do not use the Software.

LIMITED WARRANTY AND LIMITATION OF LIABILITY

YOUR USE OF THIS SOFTWARE IS AT YOUR OWN RISK. NEITHER ELSEVIER NOR ITS LICENSORS REPRESENT OR WARRANT THAT THE SOFTWARE PRODUCT WILL MEET YOUR REQUIREMENTS OR THAT ITS OPERATION WILL BE UNINTERRUPTED OR ERROR-FREE. WE EXCLUDE AND EXPRESSLY DISCLAIM ALL EXPRESS AND IMPLIED WARRANTIES NOT STATED HEREIN, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN ADDITION, NEITHER ELSEVIER NOR ITS LICENSORS MAKE ANY REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE PERFORMANCE OF YOUR NETWORK OR COMPUTER SYSTEM WHEN USED IN CONJUNCTION WITH THE SOFTWARE PRODUCT. WE SHALL NOT BE LIABLE FOR ANY DAMAGE OR LOSS OF ANY KIND ARISING OUT OF OR RESULTING FROM YOUR POSSESSION OR USE OF THE SOFTWARE PRODUCT CAUSED BY ERRORS OR OMISSIONS, DATA LOSS OR CORRUPTION, ERRORS OR OMISSIONS IN THE PROPRIETARY MATERIAL, REGARDLESS OF WHETHER SUCH LIABILITY IS BASED IN TORT, CONTRACT OR OTHERWISE AND INCLUDING, BUT NOT LIMITED TO, ACTUAL, SPECIAL, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES. IF THE FOREGOING LIMITATION IS HELD TO BE UNENFORCEABLE, OUR MAXIMUM LIABILITY TO YOU SHALL NOT EXCEED THE AMOUNT OF THE PURCHASE PRICE PAID BY YOU FOR THE SOFTWARE PRODUCT. THE REMEDIES AVAILABLE TO YOU AGAINST US AND THE LICENSORS OF MATERIALS INCLUDED IN THE SOFTWARE PRODUCT ARE EXCLUSIVE.

YOU UNDERSTAND THAT ELSEVIER, ITS AFFILIATES, LICENSORS, SUPPLIERS AND AGENTS, MAKE NO WARRANTIES, EXPRESSED OR IMPLIED, WITH RESPECT TO THE SOFTWARE PRODUCT, INCLUDING, WITHOUT LIMITATION THE PROPRIETARY MATERIAL, AND SPECIFICALLY DISCLAIM ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT WILL ELSEVIER, ITS AFFILIATES, LICENSORS, SUPPLIERS OR AGENTS, BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, WITHOUT LIMITATION, ANY LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF YOUR USE OR INABILITY TO USE THE SOFTWARE PRODUCT REGARDLESS OF WHETHER SUCH DAMAGES ARE FORESEEABLE OR WHETHER SUCH DAMAGES ARE DEEMED TO RESULT FROM THE FAILURE OR INADEQUACY OF ANY EXCLUSIVE OR OTHER REMEDY.

SOFTWARE LICENSE AGREEMENT

This Software License Agreement is a legal agreement between the Author and any person or legal entity using or accepting any Software governed by this Agreement. The Software is available on the companion website (http://perl.plover.com/hop/) for the Book, Higher-Order Perl, which is published by Morgan Kaufmann Publishers. "The Software" is comprised of all code (fragments and pseudocode) presented in the book.

By installing, copying, or otherwise using the Software, you agree to be bound by the terms of this Agreement.

The parties agree as follows:

1 Grant of License

We grant you a nonexclusive license to use the Software for any purpose, commercial or non-commercial, as long as the following credit is included identifying the original source of the Software: "from Higher-Order Perl by Mark Dominus, published by Morgan Kaufmann Publishers, Copyright 2005 by Elsevier Inc".

2 Disclaimer of Warranty.

We make no warranties at all. The Software is transferred to you on an "as is" basis. You use the Software at your own peril. You assume all risk of loss for all claims or controversies, now existing or hereafter, arising out of use of the Software. We shall have no liability based on a claim that your use or combination of the Software with products or data not supplied by us infringes any patent, copyright, or proprietary right. All other warranties, expressed or implied, including, without limitation, any warranty of merchantability or fitness for a particular purpose are hereby excluded.

3 Limitation of Liability.

We will have no liability for special, incidental, or consequential damages even if advised of the possibility of such damages. We will not be liable for any other damages or loss in any way connected with the Software.