parse::recdescent.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

upon matching \*(L"\s-1AB\s0\*(R" 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, \fIyacc\fR effectively tries all the productions of a rule
breadth-first in parallel, and selects the \*(L"best\*(R" match, where \*(L"best\*(R"
means longest (note that this is a gross simplification of the true
behaviour of \fIyacc\fR but it will do for our purposes).
.PP
In contrast, \f(CW\*(C`Parse::RecDescent\*(C'\fR tries each production depth-first in
sequence, and selects the \*(L"best\*(R" match, where \*(L"best\*(R" means first. This is
the fundamental difference between \*(L"bottom-up\*(R" and \*(L"recursive descent\*(R"
parsing.
.PP
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.
.Sh "Subrules"
.IX Subsection "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 \*(L"autostubbed\*(R" \- see
Autostubbing).
.PP
A rule may (recursively) call itself as a subrule, but \fInot\fR as the
left-most item in any of its productions (since such recursions are usually
non-terminating).
.PP
The value associated with a subrule is the value associated with its
\&\f(CW$return\fR variable (see \*(L"Actions\*(R" below), or with the last successfully
matched item in the subrule match.
.PP
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:
.PP
.Vb 7
\&                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
.Ve
.PP
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).
.PP
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:
.PP
.Vb 1
\&                program: statement(s)
.Ve
.PP
the value associated with the repeated subrule \*(L"statement(s)\*(R" is a reference
to an array containing the values matched by each call to the individual
subrule \*(L"statement\*(R".
.PP
Repetition modifieres may include a separator pattern:
.PP
.Vb 1
\&                program: statement(s /;/)
.Ve
.PP
specifying some sequence of characters to be skipped between each repetition.
This is really just a shorthand for the <leftop:...> directive
(see below).
.Sh "Tokens"
.IX Subsection "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:
.PP
.Vb 1
\&                typedef: "typedef" typename identifier \*(Aq;\*(Aq
\&
\&                identifier: /[A\-Za\-z_][A\-Za\-z0\-9_]*/
.Ve
.PP
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, \fInot\fR when the parser is constructed). Hence, it is
possible to define rules in which tokens can be set at run-time:
.PP
.Vb 1
\&                typedef: "$::typedefkeyword" typename identifier \*(Aq;\*(Aq
\&
\&                identifier: /$::identpat/
.Ve
.PP
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.
.PP
Regex tokens can be specified using just slashes as delimiters
or with the explicit \f(CW\*(C`m<delimiter>......<delimiter>\*(C'\fR syntax:
.PP
.Vb 1
\&                typedef: "typedef" typename identifier \*(Aq;\*(Aq
\&
\&                typename: /[A\-Za\-z_][A\-Za\-z0\-9_]*/
\&
\&                identifier: m{[A\-Za\-z_][A\-Za\-z0\-9_]*}
.Ve
.PP
A regex of either type can also have any valid trailing parameter(s)
(that is, any of [cgimsox]):
.PP
.Vb 1
\&                typedef: "typedef" typename identifier \*(Aq;\*(Aq
\&
\&                identifier: / [a\-z_]            # LEADING ALPHA OR UNDERSCORE
\&                              [a\-z0\-9_]*        # THEN DIGITS ALSO ALLOWED
\&                            /ix                 # CASE/SPACE/COMMENT INSENSITIVE
.Ve
.PP
The value associated with any successfully matched token is a string
containing the actual text which was matched by the token.
.PP
It is important to remember that, since each grammar is specified in a
Perl string, all instances of the universal escape character '\e' within
a grammar must be \*(L"doubled\*(R", so that they interpolate to single '\e's when
the string is compiled. For example, to use the grammar:
.PP
.Vb 3
\&                word:       /\eS+/ | backslash
\&                line:       prefix word(s) "\en"
\&                backslash:  \*(Aq\e\e\*(Aq
.Ve
.PP
the following code is required:
.PP
.Vb 1
\&                $parser = new Parse::RecDescent (q{
\&
\&                        word:       /\e\eS+/ | backslash
\&                        line:       prefix word(s) "\e\en"
\&                        backslash:  \*(Aq\e\e\e\e\*(Aq
\&
\&                });
.Ve
.Sh "Terminal Separators"
.IX Subsection "Terminal Separators"
For the purpose of matching, each terminal in a production is considered
to be preceded by a \*(L"prefix\*(R" \- 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.
.PP
The variable \f(CW$Parse::RecDescent::skip\fR stores the universal
prefix, which is the default for all terminal matches in all parsers
built with \f(CW\*(C`Parse::RecDescent\*(C'\fR.
.PP
The prefix for an individual production can be altered
by using the \f(CW\*(C`<skip:...>\*(C'\fR directive (see below).
.Sh "Actions"
.IX Subsection "Actions"
An action is a block of Perl code which is to be executed (as the
block of a \f(CW\*(C`do\*(C'\fR 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\*(R" below).
.PP
The action is considered to succeed if the final value of the block
is defined (that is, if the implied \f(CW\*(C`do\*(C'\fR statement evaluates to a
defined value \- \fIeven one which would be treated as \*(L"false\*(R"\fR). Note
that the value associated with a successful action is also the final
value in the block.
.PP
An action will \fIfail\fR if its last evaluated value is \f(CW\*(C`undef\*(C'\fR. 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 \fIisn't\fR activated:
.PP
.Vb 4
\&        description: name rank serial_number
\&                        { print "Got $item[2] $item[1] ($item[3])\en"
\&                                if $::debugging
\&                        }
.Ve
.PP
If \f(CW$debugging\fR is false, no statement in the block is executed, so
the final value is \f(CW\*(C`undef\*(C'\fR, and the entire production fails. The solution is:
.PP
.Vb 5
\&        description: name rank serial_number
\&                        { print "Got $item[2] $item[1] ($item[3])\en"
\&                                if $::debugging;
\&                          1;
\&                        }
.Ve
.PP
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):
.ie n .IP "@item\fR and \f(CW%item" 4
.el .IP "\f(CW@item\fR and \f(CW%item\fR" 4
.IX Item "@item and %item"
The array slice \f(CW@item[1..$#item]\fR stores the value associated with each item
(that is, each subrule, token, or action) in the current production. The
analogy is to \f(CW$1\fR, \f(CW$2\fR, etc. in a \fIyacc\fR grammar.
Note that, for obvious reasons, \f(CW@item\fR only contains the
values of items \fIbefore\fR the current point in the production.
.Sp
The first element (\f(CW$item[0]\fR) stores the name of the current rule
being matched.
.Sp
\&\f(CW@item\fR is a standard Perl array, so it can also be indexed with negative
numbers, representing the number of items \fIback\fR from the current position in
the parse:
.Sp
.Vb 3
\&        stuff: /various/ bits \*(Aqand\*(Aq pieces "then" data \*(Aqend\*(Aq
\&                        { print $item[\-2] }  # PRINTS data
\&                                             # (EASIER THAN: $item[6])
.Ve
.Sp
The \f(CW%item\fR hash complements the <@item> array, providing named
access to the same item values:
.Sp
.Vb 3
\&        stuff: /various/ bits \*(Aqand\*(Aq pieces "then" data \*(Aqend\*(Aq
\&                        { print $item{data}  # PRINTS data
\&                                             # (EVEN EASIER THAN USING @item)
.Ve
.Sp
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 \*(L"named
positional\*(R" key that indictates their ordinal position within their item
type: _\|_STRING\fIn\fR_\|_, _\|_PATTERN\fIn\fR_\|_, _\|_DIRECTIVE\fIn\fR_\|_, _\|_ACTION\fIn\fR_\|_:
.Sp
.Vb 6
\&        stuff: /various/ bits \*(Aqand\*(Aq pieces "then" data \*(Aqend\*(Aq { save }
\&                        { print $item{_\|_PATTERN1_\|_}, # PRINTS \*(Aqvarious\*(Aq
\&                                $item{_\|_STRING2_\|_},  # PRINTS \*(Aqthen\*(Aq
\&                                $item{_\|_ACTION1_\|_},  # PRINTS RETURN
\&                                                     # VALUE OF save
\&                        }
.Ve
.Sp
If you want proper \fInamed\fR access to patterns or literals, you need to turn 
them into separate rules:
.Sp
.Vb 3
\&        stuff: various bits \*(Aqand\*(Aq pieces "then" data \*(Aqend\*(Aq
\&                        { print $item{various}  # PRINTS various
\&                        }
\&
\&        various: /various/
.Ve
.Sp
The special entry \f(CW$item{_\|_RULE_\|_}\fR stores the name of the current
rule (i.e. the same value as \f(CW$item[0]\fR.
.Sp
The advantage of using \f(CW%item\fR, instead of \f(CW@items\fR is that it
removes the need to track items positions that may change as a grammar
evolves. For example, adding an interim \f(CW\*(C`<skip>\*(C'\fR directive
of action can silently ruin a trailing action, by moving an \f(CW@item\fR
element \*(L"down\*(R" the array one place. In contrast, the named entry 
of \f(CW%item\fR is unaffected by such an insertion.
.Sp
A limitation of the \f(CW%item\fR hash is that it only records the \fIlast\fR
value of a particular subrule. For example:
.Sp
.Vb 2
\&        range: \*(Aq(\*(Aq number \*(Aq..\*(Aq number )\*(Aq
\&                        { $return = $item{number} }
.Ve
.Sp
will return only the value corresponding to the \fIsecond\fR match of the
\&\f(CW\*(C`number\*(C'\fR subrule. In other words, successive calls to a subrule
overwrite the corresponding entry in \f(CW%item\fR. Once again, the
solution is to rename each subrule in its own rule:
.Sp
.Vb 2
\&        range: \*(Aq(\*(Aq from_num \*(Aq..\*(Aq to_num )\*(Aq
\&                        { $return = $item{from_num} }
\&
\&        from_num: number
\&        to_num:   number
.Ve
.ie n .IP "@arg\fR and \f(CW%arg" 4
.el .IP "\f(CW@arg\fR and \f(CW%arg\fR" 4
.IX Item "@arg and %arg"
The array \f(CW@arg\fR and the hash \f(CW%arg\fR store any arguments passed to
the rule from some other rule (see "\*(L"Subrule argument lists\*(R"). 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 \f(CW$return\fR
variable \- see next item).
.ie n .IP "$return" 4
.el .IP "\f(CW$return\fR" 4
.IX Item "$return"
If a value is assigned to \f(CW$return\fR within an action, that value is
returned if the production containing the action eventually matches
successfully. Note that setting \f(CW$return\fR \fIdoesn't\fR cause the current
production to succeed. It merely tells it what to return if it \fIdoes\fR succeed.
Hence \f(CW$return\fR is analogous to \f(CW$$\fR in a \fIyacc\fR grammar.
.Sp
If \f(CW$return\fR is not assigned within a production, the value of the
last component of the production (namely: \f(CW$item[$#item]\fR) is
returned if the production succeeds.
.ie n .IP "$commit" 4
.el .IP "\f(CW$commit\fR" 4
.IX Item "$commit"
The current state of commitment to the current production (see \*(L"Directives\*(R"
below).
.ie n .IP "$skip" 4
.el .IP "\f(CW$skip\fR" 4
.IX Item "$skip"
The current terminal prefix (see \*(L"Directives\*(R" below).
.ie n .IP "$text" 4
.el .IP "\f(CW$text\fR" 4
.IX Item "$text"
The remaining (unparsed) text. Changes to \f(CW$text\fR \fIdo not