recdescent.pod

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

An action is a block of Perl code which is to be executed (as the
block of a C<do> statement) when the parser reaches that point in a
production. The action executes within a special namespace belonging to
the active parser, so care must be taken in correctly qualifying variable
names (see also L<Start-up Actions> below).

The action is considered to succeed if the final value of the block
is defined (that is, if the implied C<do> statement evaluates to a
defined value - I<even one which would be treated as "false">). Note
that the value associated with a successful action is also the final
value in the block.

An action will I<fail> if its last evaluated value is C<undef>. This is
surprisingly easy to accomplish by accident. For instance, here's an
infuriating case of an action that makes its production fail, but only
when debugging I<isn't> activated:

	description: name rank serial_number
			{ print "Got $item[2] $item[1] ($item[3])\n"
				if $::debugging
			}

If C<$debugging> is false, no statement in the block is executed, so
the final value is C<undef>, and the entire production fails. The solution is:

	description: name rank serial_number
			{ print "Got $item[2] $item[1] ($item[3])\n"
				if $::debugging;
			  1;
			}

Within an action, a number of useful parse-time variables are
available in the special parser namespace (there are other variables
also accessible, but meddling with them will probably just break your
parser. As a general rule, if you avoid referring to unqualified
variables - especially those starting with an underscore - inside an action,
things should be okay):

=over 4

=item C<@item> and C<%item>

The array slice C<@item[1..$#item]> stores the value associated with each item
(that is, each subrule, token, or action) in the current production. The
analogy is to C<$1>, C<$2>, etc. in a I<yacc> grammar.
Note that, for obvious reasons, C<@item> only contains the
values of items I<before> the current point in the production.

The first element (C<$item[0]>) stores the name of the current rule
being matched.

C<@item> is a standard Perl array, so it can also be indexed with negative
numbers, representing the number of items I<back> from the current position in
the parse:

	stuff: /various/ bits 'and' pieces "then" data 'end'
			{ print $item[-2] }  # PRINTS data
					     # (EASIER THAN: $item[6])

The C<%item> hash complements the <@item> array, providing named
access to the same item values:

	stuff: /various/ bits 'and' pieces "then" data 'end'
			{ print $item{data}  # PRINTS data
					     # (EVEN EASIER THAN USING @item)


The results of named subrules are stored in the hash under each
subrule's name (including the repetition specifier, if any),
whilst all other items are stored under a "named
positional" key that indictates their ordinal position within their item
type: __STRINGI<n>__, __PATTERNI<n>__, __DIRECTIVEI<n>__, __ACTIONI<n>__:

        stuff: /various/ bits 'and' pieces "then" data 'end' { save }
                        { print $item{__PATTERN1__}, # PRINTS 'various'
                                $item{__STRING2__},  # PRINTS 'then'
                                $item{__ACTION1__},  # PRINTS RETURN
						     # VALUE OF save
                        }


If you want proper I<named> access to patterns or literals, you need to turn 
them into separate rules: 

        stuff: various bits 'and' pieces "then" data 'end'
                        { print $item{various}  # PRINTS various
                        }

        various: /various/


The special entry C<$item{__RULE__}> stores the name of the current
rule (i.e. the same value as C<$item[0]>.

The advantage of using C<%item>, instead of C<@items> is that it
removes the need to track items positions that may change as a grammar
evolves. For example, adding an interim C<E<lt>skipE<gt>> directive
of action can silently ruin a trailing action, by moving an C<@item>
element "down" the array one place. In contrast, the named entry 
of C<%item> is unaffected by such an insertion.

A limitation of the C<%item> hash is that it only records the I<last>
value of a particular subrule. For example:

        range: '(' number '..' number )'
                        { $return = $item{number} }

will return only the value corresponding to the I<second> match of the
C<number> subrule. In other words, successive calls to a subrule
overwrite the corresponding entry in C<%item>. Once again, the
solution is to rename each subrule in its own rule:

        range: '(' from_num '..' to_num )'
                        { $return = $item{from_num} }

        from_num: number
        to_num:   number



=item C<@arg> and C<%arg>

The array C<@arg> and the hash C<%arg> store any arguments passed to
the rule from some other rule (see L<"Subrule argument lists>). Changes
to the elements of either variable do not propagate back to the calling
rule (data can be passed back from a subrule via the C<$return>
variable - see next item).


=item C<$return>

If a value is assigned to C<$return> within an action, that value is
returned if the production containing the action eventually matches
successfully. Note that setting C<$return> I<doesn't> cause the current
production to succeed. It merely tells it what to return if it I<does> succeed.
Hence C<$return> is analogous to C<$$> in a I<yacc> grammar.

If C<$return> is not assigned within a production, the value of the
last component of the production (namely: C<$item[$#item]>) is
returned if the production succeeds.


=item C<$commit>

The current state of commitment to the current production (see L<"Directives">
below).

=item C<$skip>

The current terminal prefix (see L<"Directives"> below).

=item C<$text>

The remaining (unparsed) text. Changes to C<$text> I<do not
propagate> out of unsuccessful productions, but I<do> survive
successful productions. Hence it is possible to dynamically alter the
text being parsed - for example, to provide a C<#include>-like facility:

        hash_include: '#include' filename
                                { $text = ::loadfile($item[2]) . $text }

        filename: '<' /[a-z0-9._-]+/i '>'  { $return = $item[2] }
                | '"' /[a-z0-9._-]+/i '"'  { $return = $item[2] }


=item C<$thisline> and C<$prevline>

C<$thisline> stores the current line number within the current parse
(starting from 1). C<$prevline> stores the line number for the last 
character which was already successfully parsed (this will be different from
C<$thisline> at the end of each line).

For efficiency, C<$thisline> and C<$prevline> are actually tied
hashes, and only recompute the required line number when the variable's
value is used.

Assignment to C<$thisline> adjusts the line number calculator, so that
it believes that the current line number is the value being assigned. Note
that this adjustment will be reflected in all subsequent line numbers
calculations.

Modifying the value of the variable C<$text> (as in the previous
C<hash_include> example, for instance) will confuse the line
counting mechanism. To prevent this, you should call
C<Parse::RecDescent::LineCounter::resync($thisline)> I<immediately>
after any assignment to the variable C<$text> (or, at least, before the
next attempt to use C<$thisline>).

Note that if a production fails after assigning to or
resync'ing C<$thisline>, the parser's line counter mechanism will
usually be corrupted.

Also see the entry for C<@itempos>.

The line number can be set to values other than 1, by calling the start
rule with a second argument. For example:

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

        $parser->input($text, 10);      # START LINE NUMBERS AT 10


=item C<$thiscolumn> and C<$prevcolumn>

C<$thiscolumn> stores the current column number within the current line
being parsed (starting from 1). C<$prevcolumn> stores the column number
of the last character which was actually successfully parsed. Usually 
C<$prevcolumn == $thiscolumn-1>, but not at the end of lines.

For efficiency, C<$thiscolumn> and C<$prevcolumn> are
actually tied hashes, and only recompute the required column number
when the variable's value is used.

Assignment to C<$thiscolumn> or C<$prevcolumn> is a fatal error.

Modifying the value of the variable C<$text> (as in the previous
C<hash_include> example, for instance) may confuse the column
counting mechanism. 

Note that C<$thiscolumn> reports the column number I<before> any
whitespace that might be skipped before reading a token. Hence
if you wish to know where a token started (and ended) use something like this:

        rule: token1 token2 startcol token3 endcol token4
                        { print "token3: columns $item[3] to $item[5]"; }

        startcol: '' { $thiscolumn }    # NEED THE '' TO STEP PAST TOKEN SEP
        endcol:      { $prevcolumn }

Also see the entry for C<@itempos>.

=item C<$thisoffset> and C<$prevoffset>

C<$thisoffset> stores the offset of the current parsing position
within the complete text
being parsed (starting from 0). C<$prevoffset> stores the offset
of the last character which was actually successfully parsed. In all
cases C<$prevoffset == $thisoffset-1>.

For efficiency, C<$thisoffset> and C<$prevoffset> are
actually tied hashes, and only recompute the required offset
when the variable's value is used.

Assignment to C<$thisoffset> or <$prevoffset> is a fatal error.

Modifying the value of the variable C<$text> will I<not> affect the
offset counting mechanism. 

Also see the entry for C<@itempos>.

=item C<@itempos>

The array C<@itempos> stores a hash reference corresponding to
each element of C<@item>. The elements of the hash provide the
following:

        $itempos[$n]{offset}{from}      # VALUE OF $thisoffset BEFORE $item[$n]
        $itempos[$n]{offset}{to}        # VALUE OF $prevoffset AFTER $item[$n]
        $itempos[$n]{line}{from}        # VALUE OF $thisline BEFORE $item[$n]
        $itempos[$n]{line}{to}          # VALUE OF $prevline AFTER $item[$n]
        $itempos[$n]{column}{from}      # VALUE OF $thiscolumn BEFORE $item[$n]
        $itempos[$n]{column}{to}        # VALUE OF $prevcolumn AFTER $item[$n]

Note that the various C<$itempos[$n]...{from}> values record the
appropriate value I<after> any token prefix has been skipped.

Hence, instead of the somewhat tedious and error-prone:

        rule: startcol token1 endcol
              startcol token2 endcol
              startcol token3 endcol
                        { print "token1: columns $item[1]
                                              to $item[3]
                                 token2: columns $item[4]
                                              to $item[6]
                                 token3: columns $item[7]
                                              to $item[9]" }

        startcol: '' { $thiscolumn }    # NEED THE '' TO STEP PAST TOKEN SEP
        endcol:      { $prevcolumn }

it is possible to write:

        rule: token1 token2 token3
                        { print "token1: columns $itempos[1]{column}{from}
                                              to $itempos[1]{column}{to}
                                 token2: columns $itempos[2]{column}{from}
                                              to $itempos[2]{column}{to}
                                 token3: columns $itempos[3]{column}{from}
                                              to $itempos[3]{column}{to}" }

Note however that (in the current implementation) the use of C<@itempos>
anywhere in a grammar implies that item positioning information is 
collected I<everywhere> during the parse. Depending on the grammar
and the size of the text to be parsed, this may be prohibitively
expensive and the explicit use of C<$thisline>, C<$thiscolumn>, etc. may
be a better choice.


=item C<$thisparser>

A reference to the S<C<Parse::RecDescent>> object through which
parsing was initiated. 

The value of C<$thisparser> propagates down the subrules of a parse
but not back up. Hence, you can invoke subrules from another parser
for the scope of the current rule as follows:

        rule: subrule1 subrule2
            | { $thisparser = $::otherparser } <reject>
            | subrule3 subrule4
            | subrule5

The result is that the production calls "subrule1" and "subrule2" of
the current parser, and the remaining productions call the named subrules
from C<$::otherparser>. Note, however that "Bad Things" will happen if
C<::otherparser> isn't a blessed reference and/or doesn't have methods
with the same names as the required subrules!

=item C<$thisrule>

A reference to the S<C<Parse::RecDescent::Rule>> object corresponding to the 
rule currently being matched.

=item C<$thisprod>

A reference to the S<C<Parse::RecDescent::Production>> object
corresponding to the production currently being matched.

=item C<$score> and C<$score_return>

$score stores the best production score to date, as specified by
an earlier C<E<lt>score:...E<gt>> directive. $score_return stores
the corresponding return value for the successful production.

See L<Scored productions>.

=back

B<Warning:> the parser relies on the information in the various C<this...>
objects in some non-obvious ways. Tinkering with the other members of
these objects will probably cause Bad Things to happen, unless you
I<really> know what you're doing. The only exception to this advice is
that the use of C<$this...-E<gt>{local}> is always safe.


=head2 Start-up Actions

Any actions which appear I<before> the first rule definition in a
grammar are treated as "start-up" actions. Each such action is
stripped of its outermost brackets and then evaluated (in the parser's
special namespace) just before the rules of the grammar are first
compiled.

The main use of start-up actions is to declare local variables within the
parser's special namespace: