1N/A############################################################################# 1N/A# and paragraphs and commands when parsing POD docs. 1N/A# Copyright (C) 1996-2000 by Bradford Appleton. All rights reserved. 1N/A# This file is part of "PodParser". PodParser is free software; 1N/A# you can redistribute it and/or modify it under the same terms 1N/A############################################################################# 1N/A$
VERSION =
1.14;
## Current version of this package 1N/Arequire 5.005;
## requires this Perl version or later 1N/A############################################################################# 1N/APod::InputObjects - objects representing POD input paragraphs, commands, etc. 1N/A use Pod::InputObjects; 1N/AThis module defines some basic input objects used by B<Pod::Parser> when 1N/Areading and parsing POD text from an input source. The following objects 1N/A=item package B<Pod::InputSource> 1N/AAn object corresponding to a source of POD input text. It is mostly a 1N/Awrapper around a filehandle or C<IO::Handle>-type object (or anything 1N/Athat implements the C<getline()> method) which keeps track of some 1N/Aadditional information relevant to the parsing of PODs. 1N/A=item package B<Pod::Paragraph> 1N/AAn object corresponding to a paragraph of POD input text. It may be a 1N/Aplain paragraph, a verbatim paragraph, or a command paragraph (see 1N/A=item package B<Pod::InteriorSequence> 1N/AAn object corresponding to an interior sequence command from the POD 1N/Ainput text (see L<perlpod>). 1N/A=item package B<Pod::ParseTree> 1N/AAn object corresponding to a tree of parsed POD text. Each "node" in 1N/Aa parse-tree (or I<ptree>) is either a text-string or a reference to 1N/Aa B<Pod::InteriorSequence> object. The nodes appear in the parse-tree 1N/Ain the order in which they were parsed from left-to-right. 1N/AEach of these input objects are described in further detail in the 1N/Asections which follow. 1N/A############################################################################# 1N/A############################################################################# 1N/A##--------------------------------------------------------------------------- 1N/A=head1 B<Pod::InputSource> 1N/AThis object corresponds to an input source or stream of POD 1N/Adocumentation. When parsing PODs, it is necessary to associate and store 1N/Acertain context information with each input source. All of this 1N/Ainformation is kept together with the stream itself in one of these 1N/AC<Pod::InputSource> objects. Each such object is merely a wrapper around 1N/Aan C<IO::Handle> object of some kind (or at least something that 1N/Aimplements the C<getline()> method). They have the following 1N/A##--------------------------------------------------------------------------- 1N/A my $pod_input1 = Pod::InputSource->new(-handle => $filehandle); 1N/A my $pod_input2 = new Pod::InputSource(-handle => $filehandle, 1N/A my $pod_input3 = new Pod::InputSource(-handle => \*STDIN); 1N/A my $pod_input4 = Pod::InputSource->new(-handle => \*STDIN, 1N/A -name => "(STDIN)"); 1N/AThis is a class method that constructs a C<Pod::InputSource> object and 1N/Areturns a reference to the new input source object. It takes one or more 1N/Akeyword arguments in the form of a hash. The keyword C<-handle> is 1N/Arequired and designates the corresponding input handle. The keyword 1N/AC<-name> is optional and specifies the name associated with the input 1N/Ahandle (typically a file name). 1N/A ## Determine if we were called via an object-ref or a classname 1N/A ## Any remaining arguments are treated as initial values for the 1N/A ## hash that is used to represent this object. Note that we default 1N/A ## certain values by specifying them *before* the arguments passed. 1N/A ## If they are in the argument list, they will override the defaults. 1N/A ## Bless ourselves into the desired class and perform any initialization 1N/A##--------------------------------------------------------------------------- 1N/A my $filename = $pod_input->name(); 1N/A $pod_input->name($new_filename_to_use); 1N/AThis method gets/sets the name of the input source (usually a filename). 1N/AIf no argument is given, it returns a string containing the name of 1N/Athe input source; otherwise it sets the name of the input source to the 1N/Acontents of the given argument. 1N/A (@_ >
1)
and $_[
0]->{
'-name'} = $_[
1];
1N/A return $_[
0]->{
'-name'};
1N/A## allow 'filename' as an alias for 'name' 1N/A##--------------------------------------------------------------------------- 1N/A my $handle = $pod_input->handle(); 1N/AReturns a reference to the handle object from which input is read (the 1N/Aone used to contructed this input source object). 1N/A return $_[
0]->{
'-handle'};
1N/A##--------------------------------------------------------------------------- 1N/A=head2 B<was_cutting()> 1N/A print "Yes.\n" if ($pod_input->was_cutting()); 1N/AThe value of the C<cutting> state (that the B<cutting()> method would 1N/Ahave returned) immediately before any input was read from this input 1N/Astream. After all input from this stream has been read, the C<cutting> 1N/Astate is restored to this value. 1N/A##--------------------------------------------------------------------------- 1N/A############################################################################# 1N/A##--------------------------------------------------------------------------- 1N/A=head1 B<Pod::Paragraph> 1N/AAn object representing a paragraph of POD input text. 1N/A##--------------------------------------------------------------------------- 1N/A=head2 Pod::Paragraph-E<gt>B<new()> 1N/A my $pod_para1 = Pod::Paragraph->new(-text => $text); 1N/A my $pod_para2 = Pod::Paragraph->new(-name => $cmd, 1N/A my $pod_para3 = new Pod::Paragraph(-text => $text); 1N/A my $pod_para4 = new Pod::Paragraph(-name => $cmd, 1N/A my $pod_para5 = Pod::Paragraph->new(-name => $cmd, 1N/A -line => $line_number); 1N/AThis is a class method that constructs a C<Pod::Paragraph> object and 1N/Areturns a reference to the new paragraph object. It may be given one or 1N/Atwo keyword arguments. The C<-text> keyword indicates the corresponding 1N/Atext of the POD paragraph. The C<-name> keyword indicates the name of 1N/Athe corresponding POD command, such as C<head1> or C<item> (it should 1N/AI<not> contain the C<=> prefix); this is needed only if the POD 1N/Aparagraph corresponds to a command paragraph. The C<-file> and C<-line> 1N/Akeywords indicate the filename and line number corresponding to the 1N/Abeginning of the paragraph 1N/A ## Determine if we were called via an object-ref or a classname 1N/A ## Any remaining arguments are treated as initial values for the 1N/A ## hash that is used to represent this object. Note that we default 1N/A ## certain values by specifying them *before* the arguments passed. 1N/A ## If they are in the argument list, they will override the defaults. 1N/A -
text => (@_ ==
1) ?
shift :
undef,
1N/A ## Bless ourselves into the desired class and perform any initialization 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_para-E<gt>B<cmd_name()> 1N/A my $para_cmd = $pod_para->cmd_name(); 1N/AIf this paragraph is a command paragraph, then this method will return 1N/Athe name of the command (I<without> any leading C<=> prefix). 1N/A (@_ >
1)
and $_[
0]->{
'-name'} = $_[
1];
1N/A return $_[
0]->{
'-name'};
1N/A## let name() be an alias for cmd_name() 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_para-E<gt>B<text()> 1N/A my $para_text = $pod_para->text(); 1N/AThis method will return the corresponding text of the paragraph. 1N/A (@_ >
1)
and $_[
0]->{
'-text'} = $_[
1];
1N/A return $_[
0]->{
'-text'};
1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_para-E<gt>B<raw_text()> 1N/A my $raw_pod_para = $pod_para->raw_text(); 1N/AThis method will return the I<raw> text of the POD paragraph, exactly 1N/Aas it appeared in the input. 1N/A return $_[
0]->{
'-text'}
unless (
defined $_[
0]->{
'-name'});
1N/A return $_[
0]->{
'-prefix'} . $_[
0]->{
'-name'} .
1N/A $_[
0]->{
'-separator'} . $_[
0]->{
'-text'};
1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_para-E<gt>B<cmd_prefix()> 1N/A my $prefix = $pod_para->cmd_prefix(); 1N/AIf this paragraph is a command paragraph, then this method will return 1N/Athe prefix used to denote the command (which should be the string "=" 1N/A return $_[
0]->{
'-prefix'};
1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_para-E<gt>B<cmd_separator()> 1N/A my $separator = $pod_para->cmd_separator(); 1N/AIf this paragraph is a command paragraph, then this method will return 1N/Athe text used to separate the command name from the rest of the 1N/A return $_[
0]->{
'-separator'};
1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_para-E<gt>B<parse_tree()> 1N/A my $ptree = $pod_parser->parse_text( $pod_para->text() ); 1N/A $pod_para->parse_tree( $ptree ); 1N/A $ptree = $pod_para->parse_tree(); 1N/AThis method will get/set the corresponding parse-tree of the paragraph's text. 1N/A (@_ >
1)
and $_[
0]->{
'-ptree'} = $_[
1];
1N/A return $_[
0]->{
'-ptree'};
1N/A## let ptree() be an alias for parse_tree() 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_para-E<gt>B<file_line()> 1N/A my ($filename, $line_number) = $pod_para->file_line(); 1N/A my $position = $pod_para->file_line(); 1N/AReturns the current filename and line number for the paragraph 1N/Aobject. If called in a list context, it returns a list of two 1N/Aelements: first the filename, then the line number. If called in 1N/Aa scalar context, it returns a string containing the filename, followed 1N/Aby a colon (':'), followed by the line number. 1N/A my @
loc = ($_[
0]->{
'-file'} ||
'<unknown-file>',
1N/A $_[
0]->{
'-line'} ||
0);
1N/A##--------------------------------------------------------------------------- 1N/A############################################################################# 1N/A##--------------------------------------------------------------------------- 1N/A=head1 B<Pod::InteriorSequence> 1N/AAn object representing a POD interior sequence command. 1N/A##--------------------------------------------------------------------------- 1N/A=head2 Pod::InteriorSequence-E<gt>B<new()> 1N/A my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd 1N/A -ldelim => $delimiter); 1N/A my $pod_seq2 = new Pod::InteriorSequence(-name => $cmd, 1N/A -ldelim => $delimiter); 1N/A my $pod_seq3 = new Pod::InteriorSequence(-name => $cmd, 1N/A -ldelim => $delimiter, 1N/A -line => $line_number); 1N/A my $pod_seq4 = new Pod::InteriorSequence(-name => $cmd, $ptree); 1N/A my $pod_seq5 = new Pod::InteriorSequence($cmd, $ptree); 1N/AThis is a class method that constructs a C<Pod::InteriorSequence> object 1N/Aand returns a reference to the new interior sequence object. It should 1N/Abe given two keyword arguments. The C<-ldelim> keyword indicates the 1N/Acorresponding left-delimiter of the interior sequence (e.g. 'E<lt>'). 1N/AThe C<-name> keyword indicates the name of the corresponding interior 1N/Asequence command, such as C<I> or C<B> or C<C>. The C<-file> and 1N/AC<-line> keywords indicate the filename and line number corresponding 1N/Ato the beginning of the interior sequence. If the C<$ptree> argument is 1N/Agiven, it must be the last argument, and it must be either string, or 1N/Aelse an array-ref suitable for passing to B<Pod::ParseTree::new> (or 1N/Ait may be a reference to a Pod::ParseTree object). 1N/A ## Determine if we were called via an object-ref or a classname 1N/A ## See if first argument has no keyword 1N/A if (((@_ <=
2)
or (@_ %
2))
and $_[
0] !~ /^-\w/) {
1N/A ## Yup - need an implicit '-name' before first parameter 1N/A unshift @_,
'-name';
1N/A ## See if odd number of args 1N/A if ((@_ %
2) !=
0) {
1N/A ## Yup - need an implicit '-ptree' before the last parameter 1N/A splice @_, $
#_, 0, '-ptree'; 1N/A ## Any remaining arguments are treated as initial values for the 1N/A ## hash that is used to represent this object. Note that we default 1N/A ## certain values by specifying them *before* the arguments passed. 1N/A ## If they are in the argument list, they will override the defaults. 1N/A -
name => (@_ ==
1) ? $_[
0] :
undef,
1N/A ## Initialize contents if they havent been already 1N/A ## We have an array-ref, or a normal scalar. Pass it as an 1N/A ## an argument to the ptree-constructor 1N/A ## Bless ourselves into the desired class and perform any initialization 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_seq-E<gt>B<cmd_name()> 1N/A my $seq_cmd = $pod_seq->cmd_name(); 1N/AThe name of the interior sequence command. 1N/A (@_ >
1)
and $_[
0]->{
'-name'} = $_[
1];
1N/A return $_[
0]->{
'-name'};
1N/A## let name() be an alias for cmd_name() 1N/A##--------------------------------------------------------------------------- 1N/A## Private subroutine to set the parent pointer of all the given 1N/A## children that are interior-sequences to be $self 1N/A ## Make sure any sequences know who their parent is 1N/A next unless (
length and ref and ref ne 'SCALAR');
1N/A## Private subroutine to unset child->parent links 1N/A $
self->{
'-parent_sequence'} =
undef;
1N/A next unless (
length and ref and ref ne 'SCALAR');
1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_seq-E<gt>B<prepend()> 1N/A $pod_seq->prepend($text); 1N/A $pod_seq1->prepend($pod_seq2); 1N/APrepends the given string or parse-tree or sequence object to the parse-tree 1N/Aof this interior sequence. 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_seq-E<gt>B<append()> 1N/A $pod_seq->append($text); 1N/A $pod_seq1->append($pod_seq2); 1N/AAppends the given string or parse-tree or sequence object to the parse-tree 1N/Aof this interior sequence. 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_seq-E<gt>B<nested()> 1N/A $outer_seq = $pod_seq->nested || print "not nested"; 1N/AIf this interior sequence is nested inside of another interior 1N/Areturned. Otherwise C<undef> is returned. 1N/A (@_ ==
1)
and $
self->{
'-parent_sequence'} =
shift;
1N/A return $
self->{
'-parent_sequence'} ||
undef;
1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_seq-E<gt>B<raw_text()> 1N/A my $seq_raw_text = $pod_seq->raw_text(); 1N/AThis method will return the I<raw> text of the POD interior sequence, 1N/Aexactly as it appeared in the input. 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_seq-E<gt>B<left_delimiter()> 1N/A my $ldelim = $pod_seq->left_delimiter(); 1N/AThe leftmost delimiter beginning the argument text to the interior 1N/Asequence (should be "<"). 1N/A (@_ >
1)
and $_[
0]->{
'-ldelim'} = $_[
1];
1N/A return $_[
0]->{
'-ldelim'};
1N/A## let ldelim() be an alias for left_delimiter() 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_seq-E<gt>B<right_delimiter()> 1N/AThe rightmost delimiter beginning the argument text to the interior 1N/Asequence (should be ">"). 1N/A (@_ >
1)
and $_[
0]->{
'-rdelim'} = $_[
1];
1N/A return $_[
0]->{
'-rdelim'};
1N/A## let rdelim() be an alias for right_delimiter() 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_seq-E<gt>B<parse_tree()> 1N/A my $ptree = $pod_parser->parse_text($paragraph_text); 1N/A $pod_seq->parse_tree( $ptree ); 1N/A $ptree = $pod_seq->parse_tree(); 1N/AThis method will get/set the corresponding parse-tree of the interior 1N/A (@_ >
1)
and $_[
0]->{
'-ptree'} = $_[
1];
1N/A return $_[
0]->{
'-ptree'};
1N/A## let ptree() be an alias for parse_tree() 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $pod_seq-E<gt>B<file_line()> 1N/A my ($filename, $line_number) = $pod_seq->file_line(); 1N/A my $position = $pod_seq->file_line(); 1N/AReturns the current filename and line number for the interior sequence 1N/Aobject. If called in a list context, it returns a list of two 1N/Aelements: first the filename, then the line number. If called in 1N/Aa scalar context, it returns a string containing the filename, followed 1N/Aby a colon (':'), followed by the line number. 1N/A my @
loc = ($_[
0]->{
'-file'} ||
'<unknown-file>',
1N/A $_[
0]->{
'-line'} ||
0);
1N/A##--------------------------------------------------------------------------- 1N/A=head2 Pod::InteriorSequence::B<DESTROY()> 1N/AThis method performs any necessary cleanup for the interior-sequence. 1N/AIf you override this method then it is B<imperative> that you invoke 1N/Athe parent method from within your own method, otherwise 1N/AI<interior-sequence storage will not be reclaimed upon destruction!> 1N/A ## We need to get rid of all child->parent pointers throughout the 1N/A ## tree so their reference counts will go to zero and they can be 1N/A ## garbage-collected 1N/A##--------------------------------------------------------------------------- 1N/A############################################################################# 1N/A##--------------------------------------------------------------------------- 1N/A=head1 B<Pod::ParseTree> 1N/AThis object corresponds to a tree of parsed POD text. As POD text is 1N/Ascanned from left to right, it is parsed into an ordered list of 1N/Atext-strings and B<Pod::InteriorSequence> objects (in order of 1N/Aappearance). A B<Pod::ParseTree> object corresponds to this list of 1N/Astrings and sequences. Each interior sequence in the parse-tree may 1N/Aitself contain a parse-tree (since interior sequences may be nested). 1N/A##--------------------------------------------------------------------------- 1N/A=head2 Pod::ParseTree-E<gt>B<new()> 1N/A my $ptree1 = Pod::ParseTree->new; 1N/A my $ptree2 = new Pod::ParseTree; 1N/A my $ptree4 = Pod::ParseTree->new($array_ref); 1N/A my $ptree3 = new Pod::ParseTree($array_ref); 1N/AThis is a class method that constructs a C<Pod::Parse_tree> object and 1N/Areturns a reference to the new parse-tree. If a single-argument is given, 1N/Ait must be a reference to an array, and is used to initialize the root 1N/A(top) of the parse tree. 1N/A ## Determine if we were called via an object-ref or a classname 1N/A my $
self = (@_ ==
1 and ref $_[
0]) ? $_[
0] : [];
1N/A ## Bless ourselves into the desired class and perform any initialization 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $ptree-E<gt>B<top()> 1N/A my $top_node = $ptree->top(); 1N/A $ptree->top( $top_node ); 1N/A $ptree->top( @children ); 1N/AThis method gets/sets the top node of the parse-tree. If no arguments are 1N/Agiven, it returns the topmost node in the tree (the root), which is also 1N/Aa B<Pod::ParseTree>. If it is given a single argument that is a reference, 1N/Athen the reference is assumed to a parse-tree and becomes the new top node. 1N/AOtherwise, if arguments are given, they are treated as the new list of 1N/Achildren for the top node. 1N/A @{ $
self } = (@_ ==
1 and ref $_[
0]) ? ${ @_ } : @_;
1N/A## let parse_tree() & ptree() be aliases for the 'top' method 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $ptree-E<gt>B<children()> 1N/AThis method gets/sets the children of the top node in the parse-tree. 1N/AIf no arguments are given, it returns the list (array) of children 1N/A(each of which should be either a string or a B<Pod::InteriorSequence>. 1N/AOtherwise, if arguments are given, they are treated as the new list of 1N/Achildren for the top node. 1N/A @{ $
self } = (@_ ==
1 and ref $_[
0]) ? ${ @_ } : @_;
1N/A##--------------------------------------------------------------------------- 1N/A=head2 $ptree-E<gt>B<prepend()> 1N/AThis method prepends the given text or parse-tree to the current parse-tree. 1N/AIf the first item on the parse-tree is text and the argument is also text, 1N/Athen the text is prepended to the first item (not added as a separate string). 1N/AOtherwise the argument is added as a new string or parse-tree I<before> 1N/Ause vars qw(@
ptree);
## an alias used for performance reasons 1N/A##--------------------------------------------------------------------------- 1N/A=head2 $ptree-E<gt>B<append()> 1N/AThis method appends the given text or parse-tree to the current parse-tree. 1N/AIf the last item on the parse-tree is text and the argument is also text, 1N/Athen the text is appended to the last item (not added as a separate string). 1N/AOtherwise the argument is added as a new string or parse-tree I<after> 1N/A=head2 $ptree-E<gt>B<raw_text()> 1N/A my $ptree_raw_text = $ptree->raw_text(); 1N/AThis method will return the I<raw> text of the POD parse-tree 1N/Aexactly as it appeared in the input. 1N/A##--------------------------------------------------------------------------- 1N/A next unless (
defined and length and ref and ref ne 'SCALAR');
1N/A ## nothing to do, Pod::ParseTrees cant have parent pointers 1N/A=head2 Pod::ParseTree::B<DESTROY()> 1N/AThis method performs any necessary cleanup for the parse-tree. 1N/AIf you override this method then it is B<imperative> 1N/Athat you invoke the parent method from within your own method, 1N/Aotherwise I<parse-tree storage will not be reclaimed upon destruction!> 1N/A ## We need to get rid of all child->parent pointers throughout the 1N/A ## tree so their reference counts will go to zero and they can be 1N/A ## garbage-collected 1N/A############################################################################# 1N/ASee L<Pod::Parser>, L<Pod::Select> 1N/ABrad Appleton E<lt>bradapp@enteract.comE<gt>