pod::parser.3

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

The base class implementation of this method simply prints the textblock
(unmodified) to the output filehandle.
.SH "\fB\fP\f(BItextblock()\fP\fB\fP"
.IX Header "textblock()"
.Vb 1
\&            $parser\->textblock($text,$line_num,$pod_para);
.Ve
.PP
This method may be overridden by subclasses to take the appropriate
action when a normal block of \s-1POD\s0 text is encountered (although the base
class method will usually do what you want). It is passed the following
parameters:
.ie n .IP "$text" 3
.el .IP "\f(CW$text\fR" 3
.IX Item "$text"
the block of text for the a \s-1POD\s0 paragraph
.ie n .IP "$line_num" 3
.el .IP "\f(CW$line_num\fR" 3
.IX Item "$line_num"
the line-number of the beginning of the paragraph
.ie n .IP "$pod_para" 3
.el .IP "\f(CW$pod_para\fR" 3
.IX Item "$pod_para"
a reference to a \f(CW\*(C`Pod::Paragraph\*(C'\fR object which contains further
information about the paragraph (see Pod::InputObjects
for details).
.PP
In order to process interior sequences, subclasses implementations of
this method will probably want to invoke either \fB\f(BIinterpolate()\fB\fR or
\&\fB\f(BIparse_text()\fB\fR, passing it the text block \f(CW$text\fR, and the corresponding
line number in \f(CW$line_num\fR, and then perform any desired processing upon
the returned result.
.PP
The base class implementation of this method simply prints the text block
as it occurred in the input stream).
.SH "\fB\fP\f(BIinterior_sequence()\fP\fB\fP"
.IX Header "interior_sequence()"
.Vb 1
\&            $parser\->interior_sequence($seq_cmd,$seq_arg,$pod_seq);
.Ve
.PP
This method should be overridden by subclasses to take the appropriate
action when an interior sequence is encountered. An interior sequence is
an embedded command within a block of text which appears as a command
name (usually a single uppercase character) followed immediately by a
string of text which is enclosed in angle brackets. This method is
passed the sequence command \f(CW$seq_cmd\fR and the corresponding text
\&\f(CW$seq_arg\fR. It is invoked by the \fB\f(BIinterpolate()\fB\fR method for each interior
sequence that occurs in the string that it is passed. It should return
the desired text string to be used in place of the interior sequence.
The \f(CW$pod_seq\fR argument is a reference to a \f(CW\*(C`Pod::InteriorSequence\*(C'\fR
object which contains further information about the interior sequence.
Please see Pod::InputObjects for details if you need to access this
additional information.
.PP
Subclass implementations of this method may wish to invoke the 
\&\fB\f(BInested()\fB\fR method of \f(CW$pod_seq\fR to see if it is nested inside
some other interior-sequence (and if so, which kind).
.PP
The base class implementation of the \fB\f(BIinterior_sequence()\fB\fR method
simply returns the raw text of the interior sequence (as it occurred
in the input) to the caller.
.SH "OPTIONAL SUBROUTINE/METHOD OVERRIDES"
.IX Header "OPTIONAL SUBROUTINE/METHOD OVERRIDES"
\&\fBPod::Parser\fR provides several methods which subclasses may want to override
to perform any special pre/post\-processing. These methods do \fInot\fR have to
be overridden, but it may be useful for subclasses to take advantage of them.
.SH "\fB\fP\f(BInew()\fP\fB\fP"
.IX Header "new()"
.Vb 1
\&            my $parser = Pod::Parser\->new();
.Ve
.PP
This is the constructor for \fBPod::Parser\fR and its subclasses. You
\&\fIdo not\fR need to override this method! It is capable of constructing
subclass objects as well as base class objects, provided you use
any of the following constructor invocation styles:
.PP
.Vb 3
\&    my $parser1 = MyParser\->new();
\&    my $parser2 = new MyParser();
\&    my $parser3 = $parser2\->new();
.Ve
.PP
where \f(CW\*(C`MyParser\*(C'\fR is some subclass of \fBPod::Parser\fR.
.PP
Using the syntax \f(CW\*(C`MyParser::new()\*(C'\fR to invoke the constructor is \fInot\fR
recommended, but if you insist on being able to do this, then the
subclass \fIwill\fR need to override the \fB\f(BInew()\fB\fR constructor method. If
you do override the constructor, you \fImust\fR be sure to invoke the
\&\fB\f(BIinitialize()\fB\fR method of the newly blessed object.
.PP
Using any of the above invocations, the first argument to the
constructor is always the corresponding package name (or object
reference). No other arguments are required, but if desired, an
associative array (or hash-table) my be passed to the \fB\f(BInew()\fB\fR
constructor, as in:
.PP
.Vb 2
\&    my $parser1 = MyParser\->new( MYDATA => $value1, MOREDATA => $value2 );
\&    my $parser2 = new MyParser( \-myflag => 1 );
.Ve
.PP
All arguments passed to the \fB\f(BInew()\fB\fR constructor will be treated as
key/value pairs in a hash-table. The newly constructed object will be
initialized by copying the contents of the given hash-table (which may
have been empty). The \fB\f(BInew()\fB\fR constructor for this class and all of its
subclasses returns a blessed reference to the initialized object (hash-table).
.SH "\fB\fP\f(BIinitialize()\fP\fB\fP"
.IX Header "initialize()"
.Vb 1
\&            $parser\->initialize();
.Ve
.PP
This method performs any necessary object initialization. It takes no
arguments (other than the object instance of course, which is typically
copied to a local variable named \f(CW$self\fR). If subclasses override this
method then they \fImust\fR be sure to invoke \f(CW\*(C`$self\->SUPER::initialize()\*(C'\fR.
.SH "\fB\fP\f(BIbegin_pod()\fP\fB\fP"
.IX Header "begin_pod()"
.Vb 1
\&            $parser\->begin_pod();
.Ve
.PP
This method is invoked at the beginning of processing for each \s-1POD\s0
document that is encountered in the input. Subclasses should override
this method to perform any per-document initialization.
.SH "\fB\fP\f(BIbegin_input()\fP\fB\fP"
.IX Header "begin_input()"
.Vb 1
\&            $parser\->begin_input();
.Ve
.PP
This method is invoked by \fB\f(BIparse_from_filehandle()\fB\fR immediately \fIbefore\fR
processing input from a filehandle. The base class implementation does
nothing, however, subclasses may override it to perform any per-file
initializations.
.PP
Note that if multiple files are parsed for a single \s-1POD\s0 document
(perhaps the result of some future \f(CW\*(C`=include\*(C'\fR directive) this method
is invoked for every file that is parsed. If you wish to perform certain
initializations once per document, then you should use \fB\f(BIbegin_pod()\fB\fR.
.SH "\fB\fP\f(BIend_input()\fP\fB\fP"
.IX Header "end_input()"
.Vb 1
\&            $parser\->end_input();
.Ve
.PP
This method is invoked by \fB\f(BIparse_from_filehandle()\fB\fR immediately \fIafter\fR
processing input from a filehandle. The base class implementation does
nothing, however, subclasses may override it to perform any per-file
cleanup actions.
.PP
Please note that if multiple files are parsed for a single \s-1POD\s0 document
(perhaps the result of some kind of \f(CW\*(C`=include\*(C'\fR directive) this method
is invoked for every file that is parsed. If you wish to perform certain
cleanup actions once per document, then you should use \fB\f(BIend_pod()\fB\fR.
.SH "\fB\fP\f(BIend_pod()\fP\fB\fP"
.IX Header "end_pod()"
.Vb 1
\&            $parser\->end_pod();
.Ve
.PP
This method is invoked at the end of processing for each \s-1POD\s0 document
that is encountered in the input. Subclasses should override this method
to perform any per-document finalization.
.SH "\fB\fP\f(BIpreprocess_line()\fP\fB\fP"
.IX Header "preprocess_line()"
.Vb 1
\&          $textline = $parser\->preprocess_line($text, $line_num);
.Ve
.PP
This method should be overridden by subclasses that wish to perform
any kind of preprocessing for each \fIline\fR of input (\fIbefore\fR it has
been determined whether or not it is part of a \s-1POD\s0 paragraph). The
parameter \f(CW$text\fR is the input line; and the parameter \f(CW$line_num\fR is
the line number of the corresponding text line.
.PP
The value returned should correspond to the new text to use in its
place.  If the empty string or an undefined value is returned then no
further processing will be performed for this line.
.PP
Please note that the \fB\f(BIpreprocess_line()\fB\fR method is invoked \fIbefore\fR
the \fB\f(BIpreprocess_paragraph()\fB\fR method. After all (possibly preprocessed)
lines in a paragraph have been assembled together and it has been
determined that the paragraph is part of the \s-1POD\s0 documentation from one
of the selected sections, then \fB\f(BIpreprocess_paragraph()\fB\fR is invoked.
.PP
The base class implementation of this method returns the given text.
.SH "\fB\fP\f(BIpreprocess_paragraph()\fP\fB\fP"
.IX Header "preprocess_paragraph()"
.Vb 1
\&            $textblock = $parser\->preprocess_paragraph($text, $line_num);
.Ve
.PP
This method should be overridden by subclasses that wish to perform any
kind of preprocessing for each block (paragraph) of \s-1POD\s0 documentation
that appears in the input stream. The parameter \f(CW$text\fR is the \s-1POD\s0
paragraph from the input file; and the parameter \f(CW$line_num\fR is the
line number for the beginning of the corresponding paragraph.
.PP
The value returned should correspond to the new text to use in its
place If the empty string is returned or an undefined value is
returned, then the given \f(CW$text\fR is ignored (not processed).
.PP
This method is invoked after gathering up all the lines in a paragraph
and after determining the cutting state of the paragraph,
but before trying to further parse or interpret them. After
\&\fB\f(BIpreprocess_paragraph()\fB\fR returns, the current cutting state (which
is returned by \f(CW\*(C`$self\->cutting()\*(C'\fR) is examined. If it evaluates
to true then input text (including the given \f(CW$text\fR) is cut (not
processed) until the next \s-1POD\s0 directive is encountered.
.PP
Please note that the \fB\f(BIpreprocess_line()\fB\fR method is invoked \fIbefore\fR
the \fB\f(BIpreprocess_paragraph()\fB\fR method. After all (possibly preprocessed)
lines in a paragraph have been assembled together and either it has been
determined that the paragraph is part of the \s-1POD\s0 documentation from one
of the selected sections or the \f(CW\*(C`\-want_nonPODs\*(C'\fR option is true,
then \fB\f(BIpreprocess_paragraph()\fB\fR is invoked.
.PP
The base class implementation of this method returns the given text.
.SH "METHODS FOR PARSING AND PROCESSING"
.IX Header "METHODS FOR PARSING AND PROCESSING"
\&\fBPod::Parser\fR provides several methods to process input text. These
methods typically won't need to be overridden (and in some cases they
can't be overridden), but subclasses may want to invoke them to exploit
their functionality.
.SH "\fB\fP\f(BIparse_text()\fP\fB\fP"
.IX Header "parse_text()"
.Vb 3
\&            $ptree1 = $parser\->parse_text($text, $line_num);
\&            $ptree2 = $parser\->parse_text({%opts}, $text, $line_num);
\&            $ptree3 = $parser\->parse_text(\e%opts, $text, $line_num);
.Ve
.PP
This method is useful if you need to perform your own interpolation 
of interior sequences and can't rely upon \fBinterpolate\fR to expand
them in simple bottom-up order.
.PP
The parameter \f(CW$text\fR is a string or block of text to be parsed
for interior sequences; and the parameter \f(CW$line_num\fR is the
line number corresponding to the beginning of \f(CW$text\fR.
.PP
\&\fB\f(BIparse_text()\fB\fR will parse the given text into a parse-tree of \*(L"nodes.\*(R"
and interior-sequences.  Each \*(L"node\*(R" in the parse tree is either a
text-string, or a \fBPod::InteriorSequence\fR.  The result returned is a
parse-tree of type \fBPod::ParseTree\fR. Please see Pod::InputObjects
for more information about \fBPod::InteriorSequence\fR and \fBPod::ParseTree\fR.
.PP
If desired, an optional hash-ref may be specified as the first argument
to customize certain aspects of the parse-tree that is created and
returned. The set of recognized option keywords are:
.IP "\fB\-expand_seq\fR => \fIcode-ref\fR|\fImethod-name\fR" 3
.IX Item "-expand_seq => code-ref|method-name"
Normally, the parse-tree returned by \fB\f(BIparse_text()\fB\fR will contain an
unexpanded \f(CW\*(C`Pod::InteriorSequence\*(C'\fR object for each interior-sequence
encountered. Specifying \fB\-expand_seq\fR tells \fB\f(BIparse_text()\fB\fR to \*(L"expand\*(R"
every interior-sequence it sees by invoking the referenced function
(or named method of the parser object) and using the return value as the
expanded result.
.Sp
If a subroutine reference was given, it is invoked as:
.Sp
.Vb 1
\&  &$code_ref( $parser, $sequence )
.Ve
.Sp
and if a method-name was given, it is invoked as:
.Sp
.Vb 1
\&  $parser\->method_name( $sequence )
.Ve
.Sp
where \f(CW$parser\fR is a reference to the parser object, and \f(CW$sequence\fR
is a reference to the interior-sequence object.
[\fI\s-1NOTE\s0\fR: If the \fB\f(BIinterior_sequence()\fB\fR method is specified, then it is
invoked according to the interface specified in \*(L"\fIinterior_sequence()\fR\*(R"].
.IP "\fB\-expand_text\fR => \fIcode-ref\fR|\fImethod-name\fR" 3
.IX Item "-expand_text => code-ref|method-name"
Normally, the parse-tree returned by \fB\f(BIparse_text()\fB\fR will contain a
text-string for each contiguous sequence of characters outside of an
interior-sequence. Specifying \fB\-expand_text\fR tells \fB\f(BIparse_text()\fB\fR to
\&\*(L"preprocess\*(R" every such text-string it sees by invoking the referenced
function (or named method of the parser object) and using the return value
as the preprocessed (or \*(L"expanded\*(R") result. [Note that if the result is
an interior-sequence, then it will \fInot\fR be expanded as specified by the
\&\fB\-expand_seq\fR option; Any such recursive expansion needs to be handled by
the specified callback routine.]
.Sp
If a subroutine reference was given, it is invoked as:
.Sp
.Vb 1
\&  &$code_ref( $parser, $text, $ptree_node )
.Ve
.Sp
and if a method-name was given, it is invoked as:
.Sp
.Vb 1
\&  $parser\->method_name( $text, $ptree_node )
.Ve
.Sp
where \f(CW$parser\fR is a reference to the parser object, \f(CW$text\fR is the
text-string encountered, and \f(CW$ptree_node\fR is a reference to the current
node in the parse-tree (usually an interior-sequence object or else the
top-level node of the parse-tree).
.IP "\fB\-expand_ptree\fR => \fIcode-ref\fR|\fImethod-name\fR" 3
.IX Item "-expand_ptree => code-ref|method-name"
Rather than returning a \f(CW\*(C`Pod::ParseTree\*(C'\fR, pass the parse-tree as an
argument to the referenced subroutine (or named method of the parser
object) and return the result instead of the parse-tree object.
.Sp
If a subroutine reference was given, it is invoked as:
.Sp
.Vb 1
\&  &$code_ref( $parser, $ptree )
.Ve
.Sp
and if a method-name was given, it is invoked as:
.Sp
.Vb 1
\&  $parser\->method_name( $ptree )
.Ve
.Sp
where \f(CW$parser\fR is a reference to the parser object, and \f(CW$ptree\fR
is a reference to the parse-tree object.
.SH "\fB\fP\f(BIinterpolate()\fP\fB\fP"
.IX Header "interpolate()"
.Vb 1
\&            $textblock = $parser\->interpolate($text, $line_num);
.Ve
.PP
This method translates all text (including any embedded interior sequences)
in the given text string \f(CW$text\fR and returns the interpolated result. The
parameter \f(CW$line_num\fR is the line number corresponding to the beginning
of \f(CW$text\fR.
.PP
\&\fB\f(BIinterpolate()\fB\fR merely invokes a private method to recursively expand
nested interior sequences in bottom-up order (innermost sequences are
expanded first). If there is a need to expand nested sequences in
some alternate order, use \fBparse_text\fR instead.
.SH "\fB\fP\f(BIparse_from_filehandle()\fP\fB\fP"
.IX Header "parse_from_filehandle()"
.Vb 1
\&            $parser\->parse_from_filehandle($in_fh,$out_fh);
.Ve
.PP
This method takes an input filehandle (which is assumed to already be
opened for reading) and reads the entire input stream looking for blocks
(paragraphs) of \s-1POD\s0 documentation to be processed. If no first argument
is given the default input filehandle \f(CW\*(C`STDIN\*(C'\fR is used.
.PP
The \f(CW$in_fh\fR parameter may be any object that provides a \fB\f(BIgetline()\fB\fR
method to retrieve a single line of input text (hence, an appropriate
wrapper object could be used to parse PODs from a single string or an
array of strings).
.PP