parse::recdescent.3

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

\&    parser = new Parse::RecDescent (q{
\&        expression: and_expr \*(Aq&&\*(Aq expression | and_expr
\&        and_expr:   not_expr \*(Aq&&\*(Aq and_expr   | not_expr
\&        not_expr:   \*(Aq!\*(Aq brack_expr           | brack_expr
\&        brack_expr: \*(Aq(\*(Aq expression \*(Aq)\*(Aq       | identifier
\&        identifier: /[a\-z]+/i
\&                        { new terminal_node($item[1]) }
\&        });
.Ve
.PP
each \f(CW\*(C`identifier\*(C'\fR match produces a \f(CW\*(C`terminal_node\*(C'\fR object, \fInot\fR an
\&\f(CW\*(C`identifier_node\*(C'\fR object.
.PP
A level 1 warning is issued each time an \*(L"autoaction\*(R" is added to
some production.
.Sh "Autotrees"
.IX Subsection "Autotrees"
A commonly needed autoaction is one that builds a parse-tree. It is moderately
tricky to set up such an action (which must treat terminals differently from
non-terminals), so Parse::RecDescent simplifies the process by providing the
\&\f(CW\*(C`<autotree>\*(C'\fR directive.
.PP
If this directive appears at the start of grammar, it causes
Parse::RecDescent to insert autoactions at the end of any rule except
those which already end in an action. The action inserted depends on whether
the production is an intermediate rule (two or more items), or a terminal
of the grammar (i.e. a single pattern or string item).
.PP
So, for example, the following grammar:
.PP
.Vb 1
\&        <autotree>
\&
\&        file    : command(s)
\&        command : get | set | vet
\&        get     : \*(Aqget\*(Aq ident \*(Aq;\*(Aq
\&        set     : \*(Aqset\*(Aq ident \*(Aqto\*(Aq value \*(Aq;\*(Aq
\&        vet     : \*(Aqcheck\*(Aq ident \*(Aqis\*(Aq value \*(Aq;\*(Aq
\&        ident   : /\ew+/
\&        value   : /\ed+/
.Ve
.PP
is equivalent to:
.PP
.Vb 7
\&        file    : command(s)                    { bless \e%item, $item[0] }
\&        command : get                           { bless \e%item, $item[0] }
\&                | set                           { bless \e%item, $item[0] }
\&                | vet                           { bless \e%item, $item[0] }
\&        get     : \*(Aqget\*(Aq ident \*(Aq;\*(Aq               { bless \e%item, $item[0] }
\&        set     : \*(Aqset\*(Aq ident \*(Aqto\*(Aq value \*(Aq;\*(Aq    { bless \e%item, $item[0] }
\&        vet     : \*(Aqcheck\*(Aq ident \*(Aqis\*(Aq value \*(Aq;\*(Aq  { bless \e%item, $item[0] }
\&
\&        ident   : /\ew+/          { bless {_\|_VALUE_\|_=>$item[1]}, $item[0] }
\&        value   : /\ed+/          { bless {_\|_VALUE_\|_=>$item[1]}, $item[0] }
.Ve
.PP
Note that each node in the tree is blessed into a class of the same name
as the rule itself. This makes it easy to build object-oriented
processors for the parse-trees that the grammar produces. Note too that
the last two rules produce special objects with the single attribute
\&'_\|_VALUE_\|_'. This is because they consist solely of a single terminal.
.PP
This autoaction-ed grammar would then produce a parse tree in a data
structure like this:
.PP
.Vb 10
\&        {
\&          file => {
\&                    command => {
\&                                 [ get => {
\&                                            identifier => { _\|_VALUE_\|_ => \*(Aqa\*(Aq },
\&                                          },
\&                                   set => {
\&                                            identifier => { _\|_VALUE_\|_ => \*(Aqb\*(Aq },
\&                                            value      => { _\|_VALUE_\|_ => \*(Aq7\*(Aq },
\&                                          },
\&                                   vet => {
\&                                            identifier => { _\|_VALUE_\|_ => \*(Aqb\*(Aq },
\&                                            value      => { _\|_VALUE_\|_ => \*(Aq7\*(Aq },
\&                                          },
\&                                  ],
\&                               },
\&                  }
\&        }
.Ve
.PP
(except, of course, that each nested hash would also be blessed into
the appropriate class).
.Sh "Autostubbing"
.IX Subsection "Autostubbing"
Normally, if a subrule appears in some production, but no rule of that
name is ever defined in the grammar, the production which refers to the
non-existent subrule fails immediately. This typically occurs as a
result of misspellings, and is a sufficiently common occurance that a
warning is generated for such situations.
.PP
However, when prototyping a grammar it is sometimes useful to be
able to use subrules before a proper specification of them is 
really possible.  For example, a grammar might include a section like:
.PP
.Vb 1
\&        function_call: identifier \*(Aq(\*(Aq arg(s?) \*(Aq)\*(Aq
\&
\&        identifier: /[a\-z]\ew*/i
.Ve
.PP
where the possible format of an argument is sufficiently complex that
it is not worth specifying in full until the general function call
syntax has been debugged. In this situation it is convenient to leave
the real rule \f(CW\*(C`arg\*(C'\fR undefined and just slip in a placeholder (or
\&\*(L"stub\*(R"):
.PP
.Vb 1
\&        arg: \*(Aqarg\*(Aq
.Ve
.PP
so that the function call syntax can be tested with dummy input such as:
.PP
.Vb 4
\&        f0()
\&        f1(arg)
\&        f2(arg arg)
\&        f3(arg arg arg)
.Ve
.PP
et cetera.
.PP
Early in prototyping, many such \*(L"stubs\*(R" may be required, so 
\&\f(CW\*(C`Parse::RecDescent\*(C'\fR provides a means of automating their definition.
If the variable \f(CW$::RD_AUTOSTUB\fR is defined when a parser is built,
a subrule reference to any non-existent rule (say, \f(CW\*(C`sr\*(C'\fR),
causes a \*(L"stub\*(R" rule of the form:
.PP
.Vb 1
\&        sr: \*(Aqsr\*(Aq
.Ve
.PP
to be automatically defined in the generated parser.
A level 1 warning is issued for each such \*(L"autostubbed\*(R" rule.
.PP
Hence, with \f(CW$::AUTOSTUB\fR defined, it is possible to only partially
specify a grammar, and then \*(L"fake\*(R" matches of the unspecified
(sub)rules by just typing in their name.
.Sh "Look-ahead"
.IX Subsection "Look-ahead"
If a subrule, token, or action is prefixed by \*(L"...\*(R", then it is
treated as a \*(L"look-ahead\*(R" request. That means that the current production can
(as usual) only succeed if the specified item is matched, but that the matching
\&\fIdoes not consume any of the text being parsed\fR. This is very similar to the
\&\f(CW\*(C`/(?=...)/\*(C'\fR look-ahead construct in Perl patterns. Thus, the rule:
.PP
.Vb 1
\&        inner_word: word ...word
.Ve
.PP
will match whatever the subrule \*(L"word\*(R" matches, provided that match is followed
by some more text which subrule \*(L"word\*(R" would also match (although this
second substring is not actually consumed by \*(L"inner_word\*(R")
.PP
Likewise, a \*(L"...!\*(R" prefix, causes the following item to succeed (without
consuming any text) if and only if it would normally fail. Hence, a
rule such as:
.PP
.Vb 1
\&        identifier: ...!keyword ...!\*(Aq_\*(Aq /[A\-Za\-z_]\ew*/
.Ve
.PP
matches a string of characters which satisfies the pattern
\&\f(CW\*(C`/[A\-Za\-z_]\ew*/\*(C'\fR, but only if the same sequence of characters would
not match either subrule \*(L"keyword\*(R" or the literal token '_'.
.PP
Sequences of look-ahead prefixes accumulate, multiplying their positive and/or
negative senses. Hence:
.PP
.Vb 1
\&        inner_word: word ...!......!word
.Ve
.PP
is exactly equivalent the the original example above (a warning is issued in
cases like these, since they often indicate something left out, or
misunderstood).
.PP
Note that actions can also be treated as look-aheads. In such cases,
the state of the parser text (in the local variable \f(CW$text\fR)
\&\fIafter\fR the look-ahead action is guaranteed to be identical to its
state \fIbefore\fR the action, regardless of how it's changed \fIwithin\fR
the action (unless you actually undefine \f(CW$text\fR, in which case you
get the disaster you deserve :\-).
.Sh "Directives"
.IX Subsection "Directives"
Directives are special pre-defined actions which may be used to alter
the behaviour of the parser. There are currently eighteen directives:
\&\f(CW\*(C`<commit>\*(C'\fR,
\&\f(CW\*(C`<uncommit>\*(C'\fR,
\&\f(CW\*(C`<reject>\*(C'\fR,
\&\f(CW\*(C`<score>\*(C'\fR,
\&\f(CW\*(C`<autoscore>\*(C'\fR,
\&\f(CW\*(C`<skip>\*(C'\fR,
\&\f(CW\*(C`<resync>\*(C'\fR,
\&\f(CW\*(C`<error>\*(C'\fR,
\&\f(CW\*(C`<rulevar>\*(C'\fR,
\&\f(CW\*(C`<matchrule>\*(C'\fR,
\&\f(CW\*(C`<leftop>\*(C'\fR,
\&\f(CW\*(C`<rightop>\*(C'\fR,
\&\f(CW\*(C`<defer>\*(C'\fR,
\&\f(CW\*(C`<nocheck>\*(C'\fR,
\&\f(CW\*(C`<perl_quotelike>\*(C'\fR,
\&\f(CW\*(C`<perl_codeblock>\*(C'\fR,
\&\f(CW\*(C`<perl_variable>\*(C'\fR,
and \f(CW\*(C`<token>\*(C'\fR.
.IP "Committing and uncommitting" 4
.IX Item "Committing and uncommitting"
The \f(CW\*(C`<commit>\*(C'\fR and \f(CW\*(C`<uncommit>\*(C'\fR directives permit the recursive
descent of the parse tree to be pruned (or \*(L"cut\*(R") for efficiency.
Within a rule, a \f(CW\*(C`<commit>\*(C'\fR directive instructs the rule to ignore subsequent
productions if the current production fails. For example:
.Sp
.Vb 3
\&        command: \*(Aqfind\*(Aq <commit> filename
\&               | \*(Aqopen\*(Aq <commit> filename
\&               | \*(Aqmove\*(Aq filename filename
.Ve
.Sp
Clearly, if the leading token 'find' is matched in the first production but that
production fails for some other reason, then the remaining
productions cannot possibly match. The presence of the
\&\f(CW\*(C`<commit>\*(C'\fR causes the \*(L"command\*(R" rule to fail immediately if
an invalid \*(L"find\*(R" command is found, and likewise if an invalid \*(L"open\*(R"
command is encountered.
.Sp
It is also possible to revoke a previous commitment. For example:
.Sp
.Vb 5
\&        if_statement: \*(Aqif\*(Aq <commit> condition
\&                                \*(Aqthen\*(Aq block <uncommit>
\&                                \*(Aqelse\*(Aq block
\&                    | \*(Aqif\*(Aq <commit> condition
\&                                \*(Aqthen\*(Aq block
.Ve
.Sp
In this case, a failure to find an \*(L"else\*(R" block in the first
production shouldn't preclude trying the second production, but a
failure to find a \*(L"condition\*(R" certainly should.
.Sp
As a special case, any production in which the \fIfirst\fR item is an
\&\f(CW\*(C`<uncommit>\*(C'\fR immediately revokes a preceding \f(CW\*(C`<commit>\*(C'\fR
(even though the production would not otherwise have been tried). For
example, in the rule:
.Sp
.Vb 5
\&        request: \*(Aqexplain\*(Aq expression
\&               | \*(Aqexplain\*(Aq <commit> keyword
\&               | \*(Aqsave\*(Aq
\&               | \*(Aqquit\*(Aq
\&               | <uncommit> term \*(Aq?\*(Aq
.Ve
.Sp
if the text being matched was \*(L"explain?\*(R", and the first two
productions failed, then the \f(CW\*(C`<commit>\*(C'\fR in production two would cause
productions three and four to be skipped, but the leading
\&\f(CW\*(C`<uncommit>\*(C'\fR in the production five would allow that production to
attempt a match.
.Sp
Note in the preceding example, that the \f(CW\*(C`<commit>\*(C'\fR was only placed
in production two. If production one had been:
.Sp
.Vb 1
\&        request: \*(Aqexplain\*(Aq <commit> expression
.Ve
.Sp
then production two would be (inappropriately) skipped if a leading
\&\*(L"explain...\*(R" was encountered.
.Sp
Both \f(CW\*(C`<commit>\*(C'\fR and \f(CW\*(C`<uncommit>\*(C'\fR directives always succeed, and their value
is always 1.
.IP "Rejecting a production" 4
.IX Item "Rejecting a production"
The \f(CW\*(C`<reject>\*(C'\fR directive immediately causes the current production
to fail (it is exactly equivalent to, but more obvious than, the
action \f(CW\*(C`{undef}\*(C'\fR). A \f(CW\*(C`<reject>\*(C'\fR is useful when it is desirable to get
the side effects of the actions in one production, without prejudicing a match
by some other production later in the rule. For example, to insert
tracing code into the parse:
.Sp
.Vb 1
\&        complex_rule: { print "In complex rule...\en"; } <reject>
\&                    
\&        complex_rule: simple_rule \*(Aq+\*(Aq \*(Aqi\*(Aq \*(Aq*\*(Aq simple_rule
\&                    | \*(Aqi\*(Aq \*(Aq*\*(Aq simple_rule
\&                    | simple_rule
.Ve
.Sp
It is also possible to specify a conditional rejection, using the
form \f(CW\*(C`<reject:\f(CIcondition\f(CW>\*(C'\fR, which only rejects if the
specified condition is true. This form of rejection is exactly
equivalent to the action \f(CW\*(C`{(\f(CIcondition\f(CW)?undef:1}>\*(C'\fR.
For example:
.Sp
.Vb 4
\&        command: save_command
\&               | restore_command
\&               | <reject: defined $::tolerant> { exit }
\&               | <error: Unknown command. Ignored.>
.Ve
.Sp
A \f(CW\*(C`<reject>\*(C'\fR directive never succeeds (and hence has no
associated value). A conditional rejection may succeed (if its
condition is not satisfied), in which case its value is 1.
.Sp
As an extra optimization, \f(CW\*(C`Parse::RecDescent\*(C'\fR ignores any production
which \fIbegins\fR with an unconditional \f(CW\*(C`<reject>\*(C'\fR directive,
since any such production can never successfully match or have any
useful side-effects. A level 1 warning is issued in all such cases.
.Sp
Note that productions beginning with conditional
\&\f(CW\*(C`<reject:...>\*(C'\fR directives are \fInever\fR \*(L"optimized away\*(R" in
this manner, even if they are always guaranteed to fail (for example:
\&\f(CW\*(C`<reject:1>\*(C'\fR)
.Sp
Due to the way grammars are parsed, there is a minor restriction on the
condition of a conditional \f(CW\*(C`<reject:...>\*(C'\fR: it cannot
contain any raw '<' or '>' characters. For example:
.Sp
.Vb 1
\&        line: cmd <reject: $thiscolumn > max> data
.Ve