recdescent.pod

来自「视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.」· POD 代码 · 共 1,783 行 · 第 1/5 页

=head1 NAME

Parse::RecDescent - Generate Recursive-Descent Parsers

=head1 VERSION

This document describes version 1.94 of Parse::RecDescent,
released April  9, 2003.

=head1 SYNOPSIS

 use Parse::RecDescent;

 # Generate a parser from the specification in $grammar:

	 $parser = new Parse::RecDescent ($grammar);

 # Generate a parser from the specification in $othergrammar

	 $anotherparser = new Parse::RecDescent ($othergrammar);


 # Parse $text using rule 'startrule' (which must be
 # defined in $grammar):

	$parser->startrule($text);


 # Parse $text using rule 'otherrule' (which must also
 # be defined in $grammar):

	 $parser->otherrule($text);


 # Change the universal token prefix pattern
 # (the default is: '\s*'):

	$Parse::RecDescent::skip = '[ \t]+';


 # Replace productions of existing rules (or create new ones)
 # with the productions defined in $newgrammar:

	$parser->Replace($newgrammar);


 # Extend existing rules (or create new ones)
 # by adding extra productions defined in $moregrammar:

	$parser->Extend($moregrammar);


 # Global flags (useful as command line arguments under -s):

	$::RD_ERRORS	   # unless undefined, report fatal errors
	$::RD_WARN	   # unless undefined, also report non-fatal problems
	$::RD_HINT	   # if defined, also suggestion remedies
	$::RD_TRACE	   # if defined, also trace parsers' behaviour
	$::RD_AUTOSTUB	   # if defined, generates "stubs" for undefined rules
	$::RD_AUTOACTION   # if defined, appends specified action to productions


=head1 DESCRIPTION

=head2 Overview

Parse::RecDescent incrementally generates top-down recursive-descent text
parsers from simple I<yacc>-like grammar specifications. It provides:

=over 4

=item *

Regular expressions or literal strings as terminals (tokens),

=item *

Multiple (non-contiguous) productions for any rule,

=item *

Repeated and optional subrules within productions,

=item *

Full access to Perl within actions specified as part of the grammar,

=item *

Simple automated error reporting during parser generation and parsing,

=item *

The ability to commit to, uncommit to, or reject particular
productions during a parse,

=item *

The ability to pass data up and down the parse tree ("down" via subrule
argument lists, "up" via subrule return values)

=item *

Incremental extension of the parsing grammar (even during a parse),

=item *

Precompilation of parser objects,

=item *

User-definable reduce-reduce conflict resolution via
"scoring" of matching productions.

=back

=head2 Using C<Parse::RecDescent>

Parser objects are created by calling C<Parse::RecDescent::new>, passing in a
grammar specification (see the following subsections). If the grammar is
correct, C<new> returns a blessed reference which can then be used to initiate
parsing through any rule specified in the original grammar. A typical sequence
looks like this:

	$grammar = q {
			# GRAMMAR SPECIFICATION HERE
		     };

	$parser = new Parse::RecDescent ($grammar) or die "Bad grammar!\n";

	# acquire $text

	defined $parser->startrule($text) or print "Bad text!\n";

The rule through which parsing is initiated must be explicitly defined
in the grammar (i.e. for the above example, the grammar must include a
rule of the form: "startrule: <subrules>".

If the starting rule succeeds, its value (see below)
is returned. Failure to generate the original parser or failure to match a text
is indicated by returning C<undef>. Note that it's easy to set up grammars
that can succeed, but which return a value of 0, "0", or "".  So don't be
tempted to write:

	$parser->startrule($text) or print "Bad text!\n";

Normally, the parser has no effect on the original text. So in the
previous example the value of $text would be unchanged after having
been parsed.

If, however, the text to be matched is passed by reference:

	$parser->startrule(\$text)

then any text which was consumed during the match will be removed from the
start of $text.


=head2 Rules

In the grammar from which the parser is built, rules are specified by
giving an identifier (which must satisfy /[A-Za-z]\w*/), followed by a
colon I<on the same line>, followed by one or more productions,
separated by single vertical bars. The layout of the productions
is entirely free-format:

	rule1:	production1
	     |  production2 |
		production3 | production4

At any point in the grammar previously defined rules may be extended with
additional productions. This is achieved by redeclaring the rule with the new
productions. Thus:

	rule1: a | b | c
	rule2: d | e | f
	rule1: g | h

is exactly equivalent to:

	rule1: a | b | c | g | h
	rule2: d | e | f

Each production in a rule consists of zero or more items, each of which 
may be either: the name of another rule to be matched (a "subrule"),
a pattern or string literal to be matched directly (a "token"), a
block of Perl code to be executed (an "action"), a special instruction
to the parser (a "directive"), or a standard Perl comment (which is
ignored).

A rule matches a text if one of its productions matches. A production
matches if each of its items match consecutive substrings of the
text. The productions of a rule being matched are tried in the same
order that they appear in the original grammar, and the first matching
production terminates the match attempt (successfully). If all
productions are tried and none matches, the match attempt fails.

Note that this behaviour is quite different from the "prefer the longer match"
behaviour of I<yacc>. For example, if I<yacc> were parsing the rule:

	seq : 'A' 'B'
	    | 'A' 'B' 'C'

upon matching "AB" it would look ahead to see if a 'C' is next and, if
so, will match the second production in preference to the first. In
other words, I<yacc> effectively tries all the productions of a rule
breadth-first in parallel, and selects the "best" match, where "best"
means longest (note that this is a gross simplification of the true
behaviour of I<yacc> but it will do for our purposes).

In contrast, C<Parse::RecDescent> tries each production depth-first in
sequence, and selects the "best" match, where "best" means first. This is
the fundamental difference between "bottom-up" and "recursive descent"
parsing.

Each successfully matched item in a production is assigned a value,
which can be accessed in subsequent actions within the same
production (or, in some cases, as the return value of a successful
subrule call). Unsuccessful items don't have an associated value,
since the failure of an item causes the entire surrounding production
to immediately fail. The following sections describe the various types
of items and their success values.


=head2 Subrules

A subrule which appears in a production is an instruction to the parser to
attempt to match the named rule at that point in the text being
parsed. If the named subrule is not defined when requested the
production containing it immediately fails (unless it was "autostubbed" - see
L<Autostubbing>).

A rule may (recursively) call itself as a subrule, but I<not> as the
left-most item in any of its productions (since such recursions are usually
non-terminating).

The value associated with a subrule is the value associated with its
C<$return> variable (see L<"Actions"> below), or with the last successfully
matched item in the subrule match.

Subrules may also be specified with a trailing repetition specifier,
indicating that they are to be (greedily) matched the specified number
of times. The available specifiers are:

		subrule(?)	# Match one-or-zero times
		subrule(s)	# Match one-or-more times
		subrule(s?)	# Match zero-or-more times
		subrule(N)	# Match exactly N times for integer N > 0
		subrule(N..M)	# Match between N and M times
		subrule(..M)	# Match between 1 and M times
		subrule(N..)	# Match at least N times

Repeated subrules keep matching until either the subrule fails to
match, or it has matched the minimal number of times but fails to
consume any of the parsed text (this second condition prevents the
subrule matching forever in some cases).

Since a repeated subrule may match many instances of the subrule itself, the
value associated with it is not a simple scalar, but rather a reference to a
list of scalars, each of which is the value associated with one of the
individual subrule matches. In other words in the rule:

		program: statement(s)

the value associated with the repeated subrule "statement(s)" is a reference
to an array containing the values matched by each call to the individual
subrule "statement".

Repetition modifieres may include a separator pattern:

		program: statement(s /;/)

specifying some sequence of characters to be skipped between each repetition.
This is really just a shorthand for the E<lt>leftop:...E<gt> directive
(see below).

=head2 Tokens

If a quote-delimited string or a Perl regex appears in a production,
the parser attempts to match that string or pattern at that point in
the text. For example:

		typedef: "typedef" typename identifier ';'

		identifier: /[A-Za-z_][A-Za-z0-9_]*/

As in regular Perl, a single quoted string is uninterpolated, whilst
a double-quoted string or a pattern is interpolated (at the time
of matching, I<not> when the parser is constructed). Hence, it is
possible to define rules in which tokens can be set at run-time:

		typedef: "$::typedefkeyword" typename identifier ';'

		identifier: /$::identpat/

Note that, since each rule is implemented inside a special namespace
belonging to its parser, it is necessary to explicitly quantify
variables from the main package.

Regex tokens can be specified using just slashes as delimiters
or with the explicit C<mE<lt>delimiterE<gt>......E<lt>delimiterE<gt>> syntax:

		typedef: "typedef" typename identifier ';'

		typename: /[A-Za-z_][A-Za-z0-9_]*/

		identifier: m{[A-Za-z_][A-Za-z0-9_]*}

A regex of either type can also have any valid trailing parameter(s)
(that is, any of [cgimsox]):

		typedef: "typedef" typename identifier ';'

		identifier: / [a-z_] 		# LEADING ALPHA OR UNDERSCORE
			      [a-z0-9_]*	# THEN DIGITS ALSO ALLOWED
			    /ix			# CASE/SPACE/COMMENT INSENSITIVE

The value associated with any successfully matched token is a string
containing the actual text which was matched by the token.

It is important to remember that, since each grammar is specified in a
Perl string, all instances of the universal escape character '\' within
a grammar must be "doubled", so that they interpolate to single '\'s when
the string is compiled. For example, to use the grammar:

		word:	    /\S+/ | backslash
		line:	    prefix word(s) "\n"
		backslash:  '\\'

the following code is required:

		$parser = new Parse::RecDescent (q{

			word:	    /\\S+/ | backslash
			line:	    prefix word(s) "\\n"
			backslash:  '\\\\'

		});


=head2 Terminal Separators

For the purpose of matching, each terminal in a production is considered
to be preceded by a "prefix" - a pattern which must be
matched before a token match is attempted. By default, the 
prefix is optional whitespace (which always matches, at
least trivially), but this default may be reset in any production.

The variable C<$Parse::RecDescent::skip> stores the universal
prefix, which is the default for all terminal matches in all parsers
built with C<Parse::RecDescent>.

The prefix for an individual production can be altered
by using the C<E<lt>skip:...E<gt>> directive (see below).


=head2 Actions