package Pod::InputObjects;
use vars qw($VERSION);
-$VERSION = 1.12; ## Current version of this package
+$VERSION = 1.30; ## Current version of this package
require 5.005; ## requires this Perl version or later
#############################################################################
=begin __PRIVATE__
-=item B<Pod::InputSource>
+=item
package B<Pod::InputSource>
An object corresponding to a source of POD input text. It is mostly a
wrapper around a filehandle or C<IO::Handle>-type object (or anything
=end __PRIVATE__
-=item B<Pod::Paragraph>
+=item
package B<Pod::Paragraph>
An object corresponding to a paragraph of POD input text. It may be a
plain paragraph, a verbatim paragraph, or a command paragraph (see
L<perlpod>).
-=item B<Pod::InteriorSequence>
+=item
package B<Pod::InteriorSequence>
An object corresponding to an interior sequence command from the POD
input text (see L<perlpod>).
-=item B<Pod::ParseTree>
+=item
package B<Pod::ParseTree>
An object corresponding to a tree of parsed POD text. Each "node" in
a parse-tree (or I<ptree>) is either a text-string or a reference to
a B<Pod::InteriorSequence> object. The nodes appear in the parse-tree
-in they order in which they were parsed from left-to-right.
+in the order in which they were parsed from left-to-right.
=back
##---------------------------------------------------------------------------
-=head2 B<new()>
+=head2 Pod::Paragraph-E<gt>B<new()>
my $pod_para1 = Pod::Paragraph->new(-text => $text);
my $pod_para2 = Pod::Paragraph->new(-name => $cmd,
## If they are in the argument list, they will override the defaults.
my $self = {
-name => undef,
- -text => (@_ == 1) ? $_[0] : undef,
+ -text => (@_ == 1) ? shift : undef,
-file => '<unknown-file>',
-line => 0,
-prefix => '=',
##---------------------------------------------------------------------------
-=head2 B<cmd_name()>
+=head2 $pod_para-E<gt>B<cmd_name()>
my $para_cmd = $pod_para->cmd_name();
##---------------------------------------------------------------------------
-=head2 B<text()>
+=head2 $pod_para-E<gt>B<text()>
my $para_text = $pod_para->text();
##---------------------------------------------------------------------------
-=head2 B<raw_text()>
+=head2 $pod_para-E<gt>B<raw_text()>
my $raw_pod_para = $pod_para->raw_text();
##---------------------------------------------------------------------------
-=head2 B<cmd_prefix()>
+=head2 $pod_para-E<gt>B<cmd_prefix()>
my $prefix = $pod_para->cmd_prefix();
##---------------------------------------------------------------------------
-=head2 B<cmd_separator()>
+=head2 $pod_para-E<gt>B<cmd_separator()>
my $separator = $pod_para->cmd_separator();
##---------------------------------------------------------------------------
-=head2 B<parse_tree()>
+=head2
$pod_para-E<gt>B<parse_tree()>
my $ptree = $pod_parser->parse_text( $pod_para->text() );
$pod_para->parse_tree( $ptree );
##---------------------------------------------------------------------------
-=head2 B<file_line()>
+=head2 $pod_para-E<gt>B<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 an array context, it returns a list of two
+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.
##---------------------------------------------------------------------------
-=head2 B<new()>
+=head2 Pod::InteriorSequence-E<gt>B<new()>
my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd
-ldelim => $delimiter);
to the beginning of the interior sequence. If the C<$ptree> argument is
given, it must be the last argument, and it must be either string, or
else an array-ref suitable for passing to B<Pod::ParseTree::new> (or
-it may be a reference to an Pod::ParseTree object).
+it may be a reference to a Pod::ParseTree object).
=cut
##---------------------------------------------------------------------------
-=head2 B<cmd_name()>
+=head2 $pod_seq-E<gt>B<cmd_name()>
my $seq_cmd = $pod_seq->cmd_name();
##---------------------------------------------------------------------------
-=head2 B<prepend()>
+=head2
$pod_seq-E<gt>B<prepend()>
$pod_seq->prepend($text);
$pod_seq1->prepend($pod_seq2);
##---------------------------------------------------------------------------
-=head2 B<append()>
+=head2
$pod_seq-E<gt>B<append()>
$pod_seq->append($text);
$pod_seq1->append($pod_seq2);
##---------------------------------------------------------------------------
-=head2 B<nested()>
+=head2 $pod_seq-E<gt>B<nested()>
$outer_seq = $pod_seq->nested || print "not nested";
##---------------------------------------------------------------------------
-=head2 B<raw_text()>
+=head2 $pod_seq-E<gt>B<raw_text()>
my $seq_raw_text = $pod_seq->raw_text();
##---------------------------------------------------------------------------
-=head2 B<left_delimiter()>
+=head2 $pod_seq-E<gt>B<left_delimiter()>
my $ldelim = $pod_seq->left_delimiter();
##---------------------------------------------------------------------------
-=head2 B<right_delimiter()>
+=head2 $pod_seq-E<gt>B<right_delimiter()>
The rightmost delimiter beginning the argument text to the interior
sequence (should be ">").
##---------------------------------------------------------------------------
-=head2 B<parse_tree()>
+=head2
$pod_seq-E<gt>B<parse_tree()>
my $ptree = $pod_parser->parse_text($paragraph_text);
$pod_seq->parse_tree( $ptree );
##---------------------------------------------------------------------------
-=head2 B<file_line()>
+=head2 $pod_seq-E<gt>B<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 an array context, it returns a list of two
+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.
##---------------------------------------------------------------------------
-=head2 B<DESTROY()>
+=head2 Pod::InteriorSequence::B<DESTROY()>
This method performs any necessary cleanup for the interior-sequence.
If you override this method then it is B<imperative> that you invoke
##---------------------------------------------------------------------------
-=head2 B<new()>
+=head2 Pod::ParseTree-E<gt>B<new()>
my $ptree1 = Pod::ParseTree->new;
my $ptree2 = new Pod::ParseTree;
##---------------------------------------------------------------------------
-=head2 B<top()>
+=head2 $ptree-E<gt>B<top()>
my $top_node = $ptree->top();
$ptree->top( $top_node );
##---------------------------------------------------------------------------
-=head2 B<children()>
+=head2 $ptree-E<gt>B<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
##---------------------------------------------------------------------------
-=head2 B<prepend()>
+=head2
$ptree-E<gt>B<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,
##---------------------------------------------------------------------------
-=head2 B<append()>
+=head2
$ptree-E<gt>B<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,
sub append {
my $self = shift;
local *ptree = $self;
+ my $can_append = @ptree && !(ref $ptree[-1]);
for (@_) {
- next unless length;
- if (@ptree and !(ref $ptree[-1]) and !(ref $_)) {
+ if (ref) {
+ push @ptree, $_;
+ }
+ elsif(!length) {
+ next;
+ }
+ elsif ($can_append) {
$ptree[-1] .= $_;
}
else {
}
}
-=head2 B<raw_text()>
+=head2 $ptree-E<gt>B<raw_text()>
my $ptree_raw_text = $ptree->raw_text();
my $self = shift;
local *ptree = $self;
for (@ptree) {
- next unless (length and ref and ref ne 'SCALAR');
+ next unless (defined and length and ref and ref ne 'SCALAR');
$_->_unset_child2parent_links()
if UNIVERSAL::isa($_, 'Pod::InteriorSequence');
}
## nothing to do, Pod::ParseTrees cant have parent pointers
}
-=head2 B<DESTROY()>
+=head2 Pod::ParseTree::B<DESTROY()>
This method performs any necessary cleanup for the parse-tree.
If you override this method then it is B<imperative>
=head1 AUTHOR
+Please report bugs using L<http://rt.cpan.org>.
+
Brad Appleton E<lt>bradapp@enteract.comE<gt>
=cut
https://perl5.git.perl.org / perl5.git / blobdiff