.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\" ========================================================================
.de Sh \" Subsection heading
.de Sp \" Vertical space (when we can't use .PP)
.de Vb \" Begin verbatim text
.de Ve \" End verbatim text
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. | will give a
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
. tm Index:\\$1\t\\n%\t"\\$2"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. \" simple accents for nroff and troff
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
.\" ========================================================================
.IX Title "Pod::InputObjects 3"
.TH Pod::InputObjects 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide"
Pod::InputObjects \- objects representing POD input paragraphs, commands, etc.
\& use Pod::InputObjects;
This module defines some basic input objects used by \fBPod::Parser\fR when
reading and parsing \s-1POD\s0 text from an input source. The following objects
.IP "package \fBPod::Paragraph\fR" 4
.IX Item "package Pod::Paragraph"
An object corresponding to a paragraph of \s-1POD\s0 input text. It may be a
plain paragraph, a verbatim paragraph, or a command paragraph (see
.IP "package \fBPod::InteriorSequence\fR" 4
.IX Item "package Pod::InteriorSequence"
An object corresponding to an interior sequence command from the \s-1POD\s0
input text (see perlpod).
.IP "package \fBPod::ParseTree\fR" 4
.IX Item "package Pod::ParseTree"
An object corresponding to a tree of parsed \s-1POD\s0 text. Each \*(L"node\*(R" in
a parse-tree (or \fIptree\fR) is either a text-string or a reference to
a \fBPod::InteriorSequence\fR object. The nodes appear in the parse-tree
in the order in which they were parsed from left\-to\-right.
Each of these input objects are described in further detail in the
.SH "\fBPod::Paragraph\fP"
.IX Header "Pod::Paragraph"
An object representing a paragraph of \s-1POD\s0 input text.
It has the following methods/attributes:
.Sh "Pod::Paragraph\->\fB\fP\f(BInew()\fP\fB\fP"
.IX Subsection "Pod::Paragraph->new()"
\& my $pod_para1 = Pod::Paragraph->new(-text => $text);
\& my $pod_para2 = Pod::Paragraph->new(-name => $cmd,
\& my $pod_para3 = new Pod::Paragraph(-text => $text);
\& my $pod_para4 = new Pod::Paragraph(-name => $cmd,
\& my $pod_para5 = Pod::Paragraph->new(-name => $cmd,
\& -line => $line_number);
This is a class method that constructs a \f(CW\*(C`Pod::Paragraph\*(C'\fR object and
returns a reference to the new paragraph object. It may be given one or
two keyword arguments. The \f(CW\*(C`\-text\*(C'\fR keyword indicates the corresponding
text of the \s-1POD\s0 paragraph. The \f(CW\*(C`\-name\*(C'\fR keyword indicates the name of
the corresponding \s-1POD\s0 command, such as \f(CW\*(C`head1\*(C'\fR or \f(CW\*(C`item\*(C'\fR (it should
\&\fInot\fR contain the \f(CW\*(C`=\*(C'\fR prefix); this is needed only if the \s-1POD\s0
paragraph corresponds to a command paragraph. The \f(CW\*(C`\-file\*(C'\fR and \f(CW\*(C`\-line\*(C'\fR
keywords indicate the filename and line number corresponding to the
beginning of the paragraph
.Sh "$pod_para\->\fB\fP\f(BIcmd_name()\fP\fB\fP"
.IX Subsection "$pod_para->cmd_name()"
\& my $para_cmd = $pod_para->cmd_name();
If this paragraph is a command paragraph, then this method will return
the name of the command (\fIwithout\fR any leading \f(CW\*(C`=\*(C'\fR prefix).
.Sh "$pod_para\->\fB\fP\f(BItext()\fP\fB\fP"
.IX Subsection "$pod_para->text()"
\& my $para_text = $pod_para->text();
This method will return the corresponding text of the paragraph.
.Sh "$pod_para\->\fB\fP\f(BIraw_text()\fP\fB\fP"
.IX Subsection "$pod_para->raw_text()"
\& my $raw_pod_para = $pod_para->raw_text();
This method will return the \fIraw\fR text of the \s-1POD\s0 paragraph, exactly
as it appeared in the input.
.Sh "$pod_para\->\fB\fP\f(BIcmd_prefix()\fP\fB\fP"
.IX Subsection "$pod_para->cmd_prefix()"
\& my $prefix = $pod_para->cmd_prefix();
If this paragraph is a command paragraph, then this method will return
the prefix used to denote the command (which should be the string \*(L"=\*(R"
.Sh "$pod_para\->\fB\fP\f(BIcmd_separator()\fP\fB\fP"
.IX Subsection "$pod_para->cmd_separator()"
\& my $separator = $pod_para->cmd_separator();
If this paragraph is a command paragraph, then this method will return
the text used to separate the command name from the rest of the
.Sh "$pod_para\->\fB\fP\f(BIparse_tree()\fP\fB\fP"
.IX Subsection "$pod_para->parse_tree()"
\& my $ptree = $pod_parser->parse_text( $pod_para->text() );
\& $pod_para->parse_tree( $ptree );
\& $ptree = $pod_para->parse_tree();
This method will get/set the corresponding parse-tree of the paragraph's text.
.Sh "$pod_para\->\fB\fP\f(BIfile_line()\fP\fB\fP"
.IX Subsection "$pod_para->file_line()"
\& my ($filename, $line_number) = $pod_para->file_line();
\& my $position = $pod_para->file_line();
Returns the current filename and line number for the paragraph
object. If called in a list context, it returns a list of two
elements: first the filename, then the line number. If called in
a scalar context, it returns a string containing the filename, followed
by a colon (':'), followed by the line number.
.SH "\fBPod::InteriorSequence\fP"
.IX Header "Pod::InteriorSequence"
An object representing a \s-1POD\s0 interior sequence command.
It has the following methods/attributes:
.Sh "Pod::InteriorSequence\->\fB\fP\f(BInew()\fP\fB\fP"
.IX Subsection "Pod::InteriorSequence->new()"
\& my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd
\& -ldelim => $delimiter);
\& my $pod_seq2 = new Pod::InteriorSequence(-name => $cmd,
\& -ldelim => $delimiter);
\& my $pod_seq3 = new Pod::InteriorSequence(-name => $cmd,
\& -ldelim => $delimiter,
\& -line => $line_number);
\& my $pod_seq4 = new Pod::InteriorSequence(-name => $cmd, $ptree);
\& my $pod_seq5 = new Pod::InteriorSequence($cmd, $ptree);
This is a class method that constructs a \f(CW\*(C`Pod::InteriorSequence\*(C'\fR object
and returns a reference to the new interior sequence object. It should
be given two keyword arguments. The \f(CW\*(C`\-ldelim\*(C'\fR keyword indicates the
corresponding left-delimiter of the interior sequence (e.g. '<').
The \f(CW\*(C`\-name\*(C'\fR keyword indicates the name of the corresponding interior
sequence command, such as \f(CW\*(C`I\*(C'\fR or \f(CW\*(C`B\*(C'\fR or \f(CW\*(C`C\*(C'\fR. The \f(CW\*(C`\-file\*(C'\fR and
\&\f(CW\*(C`\-line\*(C'\fR keywords indicate the filename and line number corresponding
to the beginning of the interior sequence. If the \f(CW$ptree\fR argument is
given, it must be the last argument, and it must be either string, or
else an array-ref suitable for passing to \fBPod::ParseTree::new\fR (or
it may be a reference to a Pod::ParseTree object).
.Sh "$pod_seq\->\fB\fP\f(BIcmd_name()\fP\fB\fP"
.IX Subsection "$pod_seq->cmd_name()"
\& my $seq_cmd = $pod_seq->cmd_name();
The name of the interior sequence command.
.Sh "$pod_seq\->\fB\fP\f(BIprepend()\fP\fB\fP"
.IX Subsection "$pod_seq->prepend()"
\& $pod_seq->prepend($text);
\& $pod_seq1->prepend($pod_seq2);
Prepends the given string or parse-tree or sequence object to the parse-tree
of this interior sequence.
.Sh "$pod_seq\->\fB\fP\f(BIappend()\fP\fB\fP"
.IX Subsection "$pod_seq->append()"
\& $pod_seq->append($text);
\& $pod_seq1->append($pod_seq2);
Appends the given string or parse-tree or sequence object to the parse-tree
of this interior sequence.
.Sh "$pod_seq\->\fB\fP\f(BInested()\fP\fB\fP"
.IX Subsection "$pod_seq->nested()"
\& $outer_seq = $pod_seq->nested || print "not nested";
If this interior sequence is nested inside of another interior
sequence, then the outer/parent sequence that contains it is
returned. Otherwise \f(CW\*(C`undef\*(C'\fR is returned.
.Sh "$pod_seq\->\fB\fP\f(BIraw_text()\fP\fB\fP"
.IX Subsection "$pod_seq->raw_text()"
\& my $seq_raw_text = $pod_seq->raw_text();
This method will return the \fIraw\fR text of the \s-1POD\s0 interior sequence,
exactly as it appeared in the input.
.Sh "$pod_seq\->\fB\fP\f(BIleft_delimiter()\fP\fB\fP"
.IX Subsection "$pod_seq->left_delimiter()"
\& my $ldelim = $pod_seq->left_delimiter();
The leftmost delimiter beginning the argument text to the interior
sequence (should be \*(L"<\*(R").
.Sh "$pod_seq\->\fB\fP\f(BIright_delimiter()\fP\fB\fP"
.IX Subsection "$pod_seq->right_delimiter()"
The rightmost delimiter beginning the argument text to the interior
sequence (should be \*(L">\*(R").
.Sh "$pod_seq\->\fB\fP\f(BIparse_tree()\fP\fB\fP"
.IX Subsection "$pod_seq->parse_tree()"
\& my $ptree = $pod_parser->parse_text($paragraph_text);
\& $pod_seq->parse_tree( $ptree );
\& $ptree = $pod_seq->parse_tree();
This method will get/set the corresponding parse-tree of the interior
.Sh "$pod_seq\->\fB\fP\f(BIfile_line()\fP\fB\fP"
.IX Subsection "$pod_seq->file_line()"
\& my ($filename, $line_number) = $pod_seq->file_line();
\& my $position = $pod_seq->file_line();
Returns the current filename and line number for the interior sequence
object. If called in a list context, it returns a list of two
elements: first the filename, then the line number. If called in
a scalar context, it returns a string containing the filename, followed
by a colon (':'), followed by the line number.
.Sh "Pod::InteriorSequence::\fB\s-1\fP\f(BIDESTROY\s0()\fP\fB\fP"
.IX Subsection "Pod::InteriorSequence::DESTROY()"
This method performs any necessary cleanup for the interior\-sequence.
If you override this method then it is \fBimperative\fR that you invoke
the parent method from within your own method, otherwise
\&\fIinterior-sequence storage will not be reclaimed upon destruction!\fR
.SH "\fBPod::ParseTree\fP"
.IX Header "Pod::ParseTree"
This object corresponds to a tree of parsed \s-1POD\s0 text. As \s-1POD\s0 text is
scanned from left to right, it is parsed into an ordered list of
text-strings and \fBPod::InteriorSequence\fR objects (in order of
appearance). A \fBPod::ParseTree\fR object corresponds to this list of
strings and sequences. Each interior sequence in the parse-tree may
itself contain a parse-tree (since interior sequences may be nested).
.Sh "Pod::ParseTree\->\fB\fP\f(BInew()\fP\fB\fP"
.IX Subsection "Pod::ParseTree->new()"
\& my $ptree1 = Pod::ParseTree->new;
\& my $ptree2 = new Pod::ParseTree;
\& my $ptree4 = Pod::ParseTree->new($array_ref);
\& my $ptree3 = new Pod::ParseTree($array_ref);
This is a class method that constructs a \f(CW\*(C`Pod::Parse_tree\*(C'\fR object and
returns a reference to the new parse\-tree. If a single-argument is given,
it must be a reference to an array, and is used to initialize the root
.Sh "$ptree\->\fB\fP\f(BItop()\fP\fB\fP"
.IX Subsection "$ptree->top()"
\& my $top_node = $ptree->top();
\& $ptree->top( $top_node );
\& $ptree->top( @children );
This method gets/sets the top node of the parse\-tree. If no arguments are
given, it returns the topmost node in the tree (the root), which is also
a \fBPod::ParseTree\fR. If it is given a single argument that is a reference,
then the reference is assumed to a parse-tree and becomes the new top node.
Otherwise, if arguments are given, they are treated as the new list of
children for the top node.
.Sh "$ptree\->\fB\fP\f(BIchildren()\fP\fB\fP"
.IX Subsection "$ptree->children()"
This method gets/sets the children of the top node in the parse\-tree.
If no arguments are given, it returns the list (array) of children
(each of which should be either a string or a \fBPod::InteriorSequence\fR.
Otherwise, if arguments are given, they are treated as the new list of
children for the top node.
.Sh "$ptree\->\fB\fP\f(BIprepend()\fP\fB\fP"
.IX Subsection "$ptree->prepend()"
This method prepends the given text or parse-tree to the current parse\-tree.
If the first item on the parse-tree is text and the argument is also text,
then the text is prepended to the first item (not added as a separate string).
Otherwise the argument is added as a new string or parse-tree \fIbefore\fR
.Sh "$ptree\->\fB\fP\f(BIappend()\fP\fB\fP"
.IX Subsection "$ptree->append()"
This method appends the given text or parse-tree to the current parse\-tree.
If the last item on the parse-tree is text and the argument is also text,
then the text is appended to the last item (not added as a separate string).
Otherwise the argument is added as a new string or parse-tree \fIafter\fR
.Sh "$ptree\->\fB\fP\f(BIraw_text()\fP\fB\fP"
.IX Subsection "$ptree->raw_text()"
\& my $ptree_raw_text = $ptree->raw_text();
This method will return the \fIraw\fR text of the \s-1POD\s0 parse-tree
exactly as it appeared in the input.
.Sh "Pod::ParseTree::\fB\s-1\fP\f(BIDESTROY\s0()\fP\fB\fP"
.IX Subsection "Pod::ParseTree::DESTROY()"
This method performs any necessary cleanup for the parse\-tree.
If you override this method then it is \fBimperative\fR
that you invoke the parent method from within your own method,
otherwise \fIparse-tree storage will not be reclaimed upon destruction!\fR
See Pod::Parser, Pod::Select
Please report bugs using <http://rt.cpan.org>.
Brad Appleton <bradapp@enteract.com>
projects / OpenSPARC-T2-SAM / blob