pod::parser.3

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

Using \f(CW\*(C`$in_fh\->getline()\*(C'\fR, input is read line-by-line and assembled
into paragraphs or \*(L"blocks\*(R" (which are separated by lines containing
nothing but whitespace). For each block of \s-1POD\s0 documentation
encountered it will invoke a method to parse the given paragraph.
.PP
If a second argument is given then it should correspond to a filehandle where
output should be sent (otherwise the default output filehandle is
\&\f(CW\*(C`STDOUT\*(C'\fR if no output filehandle is currently in use).
.PP
\&\fB\s-1NOTE:\s0\fR For performance reasons, this method caches the input stream at
the top of the stack in a local variable. Any attempts by clients to
change the stack contents during processing when in the midst executing
of this method \fIwill not affect\fR the input stream used by the current
invocation of this method.
.PP
This method does \fInot\fR usually need to be overridden by subclasses.
.SH "\fB\fP\f(BIparse_from_file()\fP\fB\fP"
.IX Header "parse_from_file()"
.Vb 1
\&            $parser\->parse_from_file($filename,$outfile);
.Ve
.PP
This method takes a filename and does the following:
.IP "\(bu" 2
opens the input and output files for reading
(creating the appropriate filehandles)
.IP "\(bu" 2
invokes the \fB\f(BIparse_from_filehandle()\fB\fR method passing it the
corresponding input and output filehandles.
.IP "\(bu" 2
closes the input and output files.
.PP
If the special input filename \*(L"\-\*(R" or \*(L"<&STDIN\*(R" is given then the \s-1STDIN\s0
filehandle is used for input (and no open or close is performed). If no
input filename is specified then \*(L"\-\*(R" is implied.
.PP
If a second argument is given then it should be the name of the desired
output file. If the special output filename \*(L"\-\*(R" or \*(L">&STDOUT\*(R" is given
then the \s-1STDOUT\s0 filehandle is used for output (and no open or close is
performed). If the special output filename \*(L">&STDERR\*(R" is given then the
\&\s-1STDERR\s0 filehandle is used for output (and no open or close is
performed). If no output filehandle is currently in use and no output
filename is specified, then \*(L"\-\*(R" is implied.
Alternatively, an IO::String object is also accepted as an output
file handle.
.PP
This method does \fInot\fR usually need to be overridden by subclasses.
.SH "ACCESSOR METHODS"
.IX Header "ACCESSOR METHODS"
Clients of \fBPod::Parser\fR should use the following methods to access
instance data fields:
.SH "\fB\fP\f(BIerrorsub()\fP\fB\fP"
.IX Header "errorsub()"
.Vb 3
\&            $parser\->errorsub("method_name");
\&            $parser\->errorsub(\e&warn_user);
\&            $parser\->errorsub(sub { print STDERR, @_ });
.Ve
.PP
Specifies the method or subroutine to use when printing error messages
about \s-1POD\s0 syntax. The supplied method/subroutine \fImust\fR return \s-1TRUE\s0 upon
successful printing of the message. If \f(CW\*(C`undef\*(C'\fR is given, then the \fBwarn\fR
builtin is used to issue error messages (this is the default behavior).
.PP
.Vb 5
\&            my $errorsub = $parser\->errorsub()
\&            my $errmsg = "This is an error message!\en"
\&            (ref $errorsub) and &{$errorsub}($errmsg)
\&                or (defined $errorsub) and $parser\->$errorsub($errmsg)
\&                    or  warn($errmsg);
.Ve
.PP
Returns a method name, or else a reference to the user-supplied subroutine
used to print error messages. Returns \f(CW\*(C`undef\*(C'\fR if the \fBwarn\fR builtin
is used to issue error messages (this is the default behavior).
.SH "\fB\fP\f(BIcutting()\fP\fB\fP"
.IX Header "cutting()"
.Vb 1
\&            $boolean = $parser\->cutting();
.Ve
.PP
Returns the current \f(CW\*(C`cutting\*(C'\fR state: a boolean-valued scalar which
evaluates to true if text from the input file is currently being \*(L"cut\*(R"
(meaning it is \fInot\fR considered part of the \s-1POD\s0 document).
.PP
.Vb 1
\&            $parser\->cutting($boolean);
.Ve
.PP
Sets the current \f(CW\*(C`cutting\*(C'\fR state to the given value and returns the
result.
.SH "\fB\fP\f(BIparseopts()\fP\fB\fP"
.IX Header "parseopts()"
When invoked with no additional arguments, \fBparseopts\fR returns a hashtable
of all the current parsing options.
.PP
.Vb 3
\&            ## See if we are parsing non\-POD sections as well as POD ones
\&            my %opts = $parser\->parseopts();
\&            $opts{\*(Aq\-want_nonPODs}\*(Aq and print "\-want_nonPODs\en";
.Ve
.PP
When invoked using a single string, \fBparseopts\fR treats the string as the
name of a parse-option and returns its corresponding value if it exists
(returns \f(CW\*(C`undef\*(C'\fR if it doesn't).
.PP
.Vb 3
\&            ## Did we ask to see \*(Aq=cut\*(Aq paragraphs?
\&            my $want_cut = $parser\->parseopts(\*(Aq\-process_cut_cmd\*(Aq);
\&            $want_cut and print "\-process_cut_cmd\en";
.Ve
.PP
When invoked with multiple arguments, \fBparseopts\fR treats them as
key/value pairs and the specified parse-option names are set to the
given values. Any unspecified parse-options are unaffected.
.PP
.Vb 2
\&            ## Set them back to the default
\&            $parser\->parseopts(\-warnings => 0);
.Ve
.PP
When passed a single hash-ref, \fBparseopts\fR uses that hash to completely
reset the existing parse-options, all previous parse-option values
are lost.
.PP
.Vb 2
\&            ## Reset all options to default 
\&            $parser\->parseopts( { } );
.Ve
.PP
See \*(L"\s-1PARSING\s0 \s-1OPTIONS\s0\*(R" for more information on the name and meaning of each
parse-option currently recognized.
.SH "\fB\fP\f(BIoutput_file()\fP\fB\fP"
.IX Header "output_file()"
.Vb 1
\&            $fname = $parser\->output_file();
.Ve
.PP
Returns the name of the output file being written.
.SH "\fB\fP\f(BIoutput_handle()\fP\fB\fP"
.IX Header "output_handle()"
.Vb 1
\&            $fhandle = $parser\->output_handle();
.Ve
.PP
Returns the output filehandle object.
.SH "\fB\fP\f(BIinput_file()\fP\fB\fP"
.IX Header "input_file()"
.Vb 1
\&            $fname = $parser\->input_file();
.Ve
.PP
Returns the name of the input file being read.
.SH "\fB\fP\f(BIinput_handle()\fP\fB\fP"
.IX Header "input_handle()"
.Vb 1
\&            $fhandle = $parser\->input_handle();
.Ve
.PP
Returns the current input filehandle object.
.SH "PRIVATE METHODS AND DATA"
.IX Header "PRIVATE METHODS AND DATA"
\&\fBPod::Parser\fR makes use of several internal methods and data fields
which clients should not need to see or use. For the sake of avoiding
name collisions for client data and methods, these methods and fields
are briefly discussed here. Determined hackers may obtain further
information about them by reading the \fBPod::Parser\fR source code.
.PP
Private data fields are stored in the hash-object whose reference is
returned by the \fB\f(BInew()\fB\fR constructor for this class. The names of all
private methods and data-fields used by \fBPod::Parser\fR begin with a
prefix of \*(L"_\*(R" and match the regular expression \f(CW\*(C`/^_\ew+$/\*(C'\fR.
.SH "TREE-BASED PARSING"
.IX Header "TREE-BASED PARSING"
If straightforward stream-based parsing wont meet your needs (as is
likely the case for tasks such as translating PODs into structured
markup languages like \s-1HTML\s0 and \s-1XML\s0) then you may need to take the
tree-based approach. Rather than doing everything in one pass and
calling the \fB\f(BIinterpolate()\fB\fR method to expand sequences into text, it
may be desirable to instead create a parse-tree using the \fB\f(BIparse_text()\fB\fR
method to return a tree-like structure which may contain an ordered
list of children (each of which may be a text-string, or a similar
tree-like structure).
.PP
Pay special attention to \*(L"\s-1METHODS\s0 \s-1FOR\s0 \s-1PARSING\s0 \s-1AND\s0 \s-1PROCESSING\s0\*(R" and
to the objects described in Pod::InputObjects. The former describes
the gory details and parameters for how to customize and extend the
parsing behavior of \fBPod::Parser\fR. \fBPod::InputObjects\fR provides
several objects that may all be used interchangeably as parse-trees. The
most obvious one is the \fBPod::ParseTree\fR object. It defines the basic
interface and functionality that all things trying to be a \s-1POD\s0 parse-tree
should do. A \fBPod::ParseTree\fR is defined such that each \*(L"node\*(R" may be a
text-string, or a reference to another parse-tree.  Each \fBPod::Paragraph\fR
object and each \fBPod::InteriorSequence\fR object also supports the basic
parse-tree interface.
.PP
The \fB\f(BIparse_text()\fB\fR method takes a given paragraph of text, and
returns a parse-tree that contains one or more children, each of which
may be a text-string, or an InteriorSequence object. There are also
callback-options that may be passed to \fB\f(BIparse_text()\fB\fR to customize
the way it expands or transforms interior-sequences, as well as the
returned result. These callbacks can be used to create a parse-tree
with custom-made objects (which may or may not support the parse-tree
interface, depending on how you choose to do it).
.PP
If you wish to turn an entire \s-1POD\s0 document into a parse-tree, that process
is fairly straightforward. The \fB\f(BIparse_text()\fB\fR method is the key to doing
this successfully. Every paragraph-callback (i.e. the polymorphic methods
for \fB\f(BIcommand()\fB\fR, \fB\f(BIverbatim()\fB\fR, and \fB\f(BItextblock()\fB\fR paragraphs) takes
a \fBPod::Paragraph\fR object as an argument. Each paragraph object has a
\&\fB\f(BIparse_tree()\fB\fR method that can be used to get or set a corresponding
parse-tree. So for each of those paragraph-callback methods, simply call
\&\fB\f(BIparse_text()\fB\fR with the options you desire, and then use the returned
parse-tree to assign to the given paragraph object.
.PP
That gives you a parse-tree for each paragraph \- so now all you need is
an ordered list of paragraphs. You can maintain that yourself as a data
element in the object/hash. The most straightforward way would be simply
to use an array-ref, with the desired set of custom \*(L"options\*(R" for each
invocation of \fBparse_text\fR. Let's assume the desired option-set is
given by the hash \f(CW%options\fR. Then we might do something like the
following:
.PP
.Vb 1
\&    package MyPodParserTree;
\&
\&    @ISA = qw( Pod::Parser );
\&
\&    ...
\&
\&    sub begin_pod {
\&        my $self = shift;
\&        $self\->{\*(Aq\-paragraphs\*(Aq} = [];  ## initialize paragraph list
\&    }
\&
\&    sub command { 
\&        my ($parser, $command, $paragraph, $line_num, $pod_para) = @_;
\&        my $ptree = $parser\->parse_text({%options}, $paragraph, ...);
\&        $pod_para\->parse_tree( $ptree );
\&        push @{ $self\->{\*(Aq\-paragraphs\*(Aq} }, $pod_para;
\&    }
\&
\&    sub verbatim { 
\&        my ($parser, $paragraph, $line_num, $pod_para) = @_;
\&        push @{ $self\->{\*(Aq\-paragraphs\*(Aq} }, $pod_para;
\&    }
\&
\&    sub textblock { 
\&        my ($parser, $paragraph, $line_num, $pod_para) = @_;
\&        my $ptree = $parser\->parse_text({%options}, $paragraph, ...);
\&        $pod_para\->parse_tree( $ptree );
\&        push @{ $self\->{\*(Aq\-paragraphs\*(Aq} }, $pod_para;
\&    }
\&
\&    ...
\&
\&    package main;
\&    ...
\&    my $parser = new MyPodParserTree(...);
\&    $parser\->parse_from_file(...);
\&    my $paragraphs_ref = $parser\->{\*(Aq\-paragraphs\*(Aq};
.Ve
.PP
Of course, in this module-author's humble opinion, I'd be more inclined to
use the existing \fBPod::ParseTree\fR object than a simple array. That way
everything in it, paragraphs and sequences, all respond to the same core
interface for all parse-tree nodes. The result would look something like:
.PP
.Vb 1
\&    package MyPodParserTree2;
\&
\&    ...
\&
\&    sub begin_pod {
\&        my $self = shift;
\&        $self\->{\*(Aq\-ptree\*(Aq} = new Pod::ParseTree;  ## initialize parse\-tree
\&    }
\&
\&    sub parse_tree {
\&        ## convenience method to get/set the parse\-tree for the entire POD
\&        (@_ > 1)  and  $_[0]\->{\*(Aq\-ptree\*(Aq} = $_[1];
\&        return $_[0]\->{\*(Aq\-ptree\*(Aq};
\&    }
\&
\&    sub command { 
\&        my ($parser, $command, $paragraph, $line_num, $pod_para) = @_;
\&        my $ptree = $parser\->parse_text({<<options>>}, $paragraph, ...);
\&        $pod_para\->parse_tree( $ptree );
\&        $parser\->parse_tree()\->append( $pod_para );
\&    }
\&
\&    sub verbatim { 
\&        my ($parser, $paragraph, $line_num, $pod_para) = @_;
\&        $parser\->parse_tree()\->append( $pod_para );
\&    }
\&
\&    sub textblock { 
\&        my ($parser, $paragraph, $line_num, $pod_para) = @_;
\&        my $ptree = $parser\->parse_text({<<options>>}, $paragraph, ...);
\&        $pod_para\->parse_tree( $ptree );
\&        $parser\->parse_tree()\->append( $pod_para );
\&    }
\&
\&    ...
\&
\&    package main;
\&    ...
\&    my $parser = new MyPodParserTree2(...);
\&    $parser\->parse_from_file(...);
\&    my $ptree = $parser\->parse_tree;
\&    ...
.Ve
.PP
Now you have the entire \s-1POD\s0 document as one great big parse-tree. You
can even use the \fB\-expand_seq\fR option to \fBparse_text\fR to insert
whole different kinds of objects. Just don't expect \fBPod::Parser\fR
to know what to do with them after that. That will need to be in your
code. Or, alternatively, you can insert any object you like so long as
it conforms to the \fBPod::ParseTree\fR interface.
.PP
One could use this to create subclasses of \fBPod::Paragraphs\fR and
\&\fBPod::InteriorSequences\fR for specific commands (or to create your own
custom node-types in the parse-tree) and add some kind of \fB\f(BIemit()\fB\fR
method to each custom node/subclass object in the tree. Then all you'd
need to do is recursively walk the tree in the desired order, processing
the children (most likely from left to right) by formatting them if
they are text-strings, or by calling their \fB\f(BIemit()\fB\fR method if they
are objects/references.
.SH "CAVEATS"
.IX Header "CAVEATS"
Please note that \s-1POD\s0 has the notion of \*(L"paragraphs\*(R": this is something
starting \fIafter\fR a blank (read: empty) line, with the single exception
of the file start, which is also starting a paragraph. That means that
especially a command (e.g. \f(CW\*(C`=head1\*(C'\fR) \fImust\fR be preceded with a blank
line; \f(CW\*(C`_\|_END_\|_\*(C'\fR is \fInot\fR a blank line.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Pod::InputObjects, Pod::Select
.PP
\&\fBPod::InputObjects\fR defines \s-1POD\s0 input objects corresponding to
command paragraphs, parse-trees, and interior-sequences.
.PP
\&\fBPod::Select\fR is a subclass of \fBPod::Parser\fR which provides the ability
to selectively include and/or exclude sections of a \s-1POD\s0 document from being
translated based upon the current heading, subheading, subsubheading, etc.
.SH "AUTHOR"
.IX Header "AUTHOR"
Please report bugs using <http://rt.cpan.org>.
.PP
Brad Appleton <[e-mail]>
.PP
Based on code for \fBPod::Text\fR written by
Tom Christiansen <[e-mail]>