This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Pod-Usage from version 1.70 to 2.01
authorSteve Hay <steve.m.hay@googlemail.com>
Wed, 14 Oct 2020 07:07:08 +0000 (08:07 +0100)
committerSteve Hay <steve.m.hay@googlemail.com>
Wed, 14 Oct 2020 07:14:05 +0000 (08:14 +0100)
16 files changed:
Porting/Maintainers.pl
cpan/Pod-Usage/lib/Pod/Usage.pm
cpan/Pod-Usage/scripts/pod2usage.PL
cpan/Pod-Usage/t/inc/Pod/InputObjects.pm
cpan/Pod-Usage/t/inc/Pod/Parser.pm
cpan/Pod-Usage/t/inc/Pod/PlainText.pm
cpan/Pod-Usage/t/inc/Pod/Select.pm
cpan/Pod-Usage/t/pod/headwithmarkup.t
cpan/Pod-Usage/t/pod/p2u_data.pl
cpan/Pod-Usage/t/pod/pod2usage.t
cpan/Pod-Usage/t/pod/pod2usage2.t
cpan/Pod-Usage/t/pod/selectheaders.pl
cpan/Pod-Usage/t/pod/selectheaders.t
cpan/Pod-Usage/t/pod/selectsections.pl
cpan/Pod-Usage/t/pod/selectsections.t
cpan/Pod-Usage/t/pod/testp2pt.pl

index 1ac24a7..e8e9cb2 100755 (executable)
@@ -952,8 +952,12 @@ use File::Glob qw(:case);
     },
 
     'Pod::Usage' => {
-        'DISTRIBUTION' => 'MAREKR/Pod-Usage-1.70.tar.gz',
+        'DISTRIBUTION' => 'ATOOMIC/Pod-Usage-2.01.tar.gz',
         'FILES'        => q[cpan/Pod-Usage],
+        'EXCLUDED' => [
+            qr{^t/00-},
+            qr{^xt/}
+       ],
     },
 
     'podlators' => {
index fe5e555..c290f2b 100644 (file)
@@ -9,19 +9,19 @@
 #############################################################################
 
 package Pod::Usage;
-use strict;
 
-use vars qw($VERSION @ISA @EXPORT);
-$VERSION = '1.70';  ## Current version of this package
+use strict;
 require  5.006;    ## requires this Perl version or later
 
-#use diagnostics;
 use Carp;
 use Config;
 use Exporter;
 use File::Spec;
 
-@EXPORT = qw(&pod2usage);
+our $VERSION = '2.01';
+
+our @EXPORT = qw(&pod2usage);
+our @ISA;
 BEGIN {
     $Pod::Usage::Formatter ||= 'Pod::Text';
     eval "require $Pod::Usage::Formatter";
@@ -103,13 +103,13 @@ sub pod2usage {
 
         my @paths = (ref $pathspec) ? @$pathspec : split($pathsep, $pathspec);
         for my $dirname (@paths) {
-            $_ = File::Spec->catfile($dirname, $basename)  if length;
+            $_ = length($dirname) ? File::Spec->catfile($dirname, $basename) : $basename;
             last if (-e $_) && ($opts{'-input'} = $_);
         }
     }
 
     ## Now create a pod reader and constrain it to the desired sections.
-    my $parser = new Pod::Usage(USAGE_OPTIONS => \%opts);
+    my $parser = Pod::Usage->new(USAGE_OPTIONS => \%opts);
     if ($opts{'-verbose'} == 0) {
         $parser->select('(?:SYNOPSIS|USAGE)\s*');
     }
@@ -386,9 +386,11 @@ sub preprocess_paragraph {
 
 __END__
 
+=for stopwords pod2usage verboseness downcased MSWin32 Marek Rouchal Christiansen ATOOMIC rjbs McDougall
+
 =head1 NAME
 
-Pod::Usage - print a usage message from embedded pod documentation
+Pod::Usage - extracts POD documentation and shows usage information
 
 =head1 SYNOPSIS
 
@@ -404,13 +406,13 @@ Pod::Usage - print a usage message from embedded pod documentation
   pod2usage($exit_status);
 
   pod2usage( { -message => $message_text ,
-               -exitval => $exit_status  ,  
-               -verbose => $verbose_level,  
+               -exitval => $exit_status  ,
+               -verbose => $verbose_level,
                -output  => $filehandle } );
 
   pod2usage(   -msg     => $message_text ,
-               -exitval => $exit_status  ,  
-               -verbose => $verbose_level,  
+               -exitval => $exit_status  ,
+               -verbose => $verbose_level,
                -output  => $filehandle );
 
   pod2usage(   -verbose => 2,
@@ -456,39 +458,39 @@ keys:
 =item C<-msg> I<string>
 
 The text of a message to print immediately prior to printing the
-program's usage message. 
+program's usage message.
 
 =item C<-exitval> I<value>
 
 The desired exit status to pass to the B<exit()> function.
-This should be an integer, or else the string "NOEXIT" to
+This should be an integer, or else the string C<NOEXIT> to
 indicate that control should simply be returned without
 terminating the invoking process.
 
 =item C<-verbose> I<value>
 
 The desired level of "verboseness" to use when printing the usage message.
-If the value is 0, then only the "SYNOPSIS" section of the pod documentation
-is printed. If the value is 1, then the "SYNOPSIS" section, along with any
-section entitled "OPTIONS", "ARGUMENTS", or "OPTIONS AND ARGUMENTS" is
-printed. If the corresponding value is 2 or more then the entire manpage is
-printed, using L<perldoc> if available; otherwise L<Pod::Text> is used for
-the formatting. For better readability, the all-capital headings are
-downcased, e.g. C<SYNOPSIS> =E<gt> C<Synopsis>.
+If the value is 0, then only the "SYNOPSIS" and/or "USAGE" sections of the
+pod documentation are printed. If the value is 1, then the "SYNOPSIS" and/or
+"USAGE" sections, along with any section entitled "OPTIONS", "ARGUMENTS", or
+"OPTIONS AND ARGUMENTS" is printed. If the corresponding value is 2 or more
+then the entire manpage is printed, using L<perldoc> if available; otherwise
+L<Pod::Text> is used for the formatting. For better readability, the
+all-capital headings are downcased, e.g. C<SYNOPSIS> =E<gt> C<Synopsis>.
 
 The special verbosity level 99 requires to also specify the -sections
 parameter; then these sections are extracted and printed.
 
 =item C<-sections> I<spec>
 
-There are two ways to specify the selection. Either a string (scalar) 
+There are two ways to specify the selection. Either a string (scalar)
 representing a selection regexp for sections to be printed when -verbose
 is set to 99, e.g.
 
   "NAME|SYNOPSIS|DESCRIPTION|VERSION"
 
 With the above regexp all content following (and including) any of the
-given C<=head1> headings will be shown. It is possible to restrict the 
+given C<=head1> headings will be shown. It is possible to restrict the
 output to particular subsections only, e.g.:
 
   "DESCRIPTION/Algorithm"
@@ -507,7 +509,7 @@ Alternatively, an array reference of section specifications can be used:
   pod2usage(-verbose => 99, -sections => [
     qw(DESCRIPTION DESCRIPTION/Introduction) ] );
 
-This will print only the content of C<=head1 DESCRIPTION> and the 
+This will print only the content of C<=head1 DESCRIPTION> and the
 C<=head2 Introduction> sections, but no other C<=head2>, and no other
 C<=head1> either.
 
@@ -541,17 +543,16 @@ MSWin32 and DOS).
 
 =item C<-noperldoc>
 
-By default, Pod::Usage will call L<perldoc> when -verbose >= 2 is
-specified. This does not work well e.g. if the script was packed
-with L<PAR>. The -noperldoc option suppresses the external call to
-L<perldoc> and uses the simple text formatter (L<Pod::Text>) to 
-output the POD.
+By default, Pod::Usage will call L<perldoc> when -verbose >= 2 is specified.
+This does not work well e.g. if the script was packed with L<PAR>. This option
+suppresses the external call to L<perldoc> and uses the simple text formatter
+(L<Pod::Text>) to output the POD.
 
 =item C<-perlcmd>
 
 By default, Pod::Usage will call L<perldoc> when -verbose >= 2 is
 specified. In case of special or unusual Perl installations,
-the -perlcmd option may be used to supply the path to a L<perl> executable
+this option may be used to supply the path to a L<perl> executable
 which should run L<perldoc>.
 
 =item C<-perldoc> I<path-to-perldoc>
@@ -564,7 +565,7 @@ the correct path to L<perldoc>.
 =item C<-perldocopt> I<string>
 
 By default, Pod::Usage will call L<perldoc> when -verbose >= 2 is specified.
-The -perldocopt option may be used to supply options to L<perldoc>. The
+This option may be used to supply options to L<perldoc>. The
 string may contain several, space-separated options.
 
 =back
@@ -672,7 +673,7 @@ more verbose description of program usage in this case.
 
 =back
 
-B<pod2usage> doesn't force the above conventions upon you, but it will
+B<pod2usage> does not force the above conventions upon you, but it will
 use them by default if you don't expressly tell it to do otherwise.  The
 ability of B<pod2usage()> to accept a single number or a string makes it
 convenient to use as an innocent looking error message handling function:
@@ -861,7 +862,7 @@ things:
 
 By default, B<pod2usage()> will use C<$0> as the path to the pod input
 file.  Unfortunately, not all systems on which Perl runs will set C<$0>
-properly (although if C<$0> isn't found, B<pod2usage()> will search
+properly (although if C<$0> is not found, B<pod2usage()> will search
 C<$ENV{PATH}> or else the list specified by the C<-pathlist> option).
 If this is the case for your system, you may need to explicitly specify
 the path to the pod docs for the invoking script using something
@@ -878,12 +879,27 @@ the script:
     use FindBin;
     pod2usage(-input => $FindBin::Bin . "/" . $FindBin::Script);
 
-=head1 AUTHOR
+=head1 SUPPORT
 
-Please report bugs using L<http://rt.cpan.org>.
+This module is managed in a GitHub repository,
+L<https://github.com/Dual-Life/Pod-Usage> Feel free to fork and contribute, or
+to clone and send patches!
+
+Please use L<https://github.com/Dual-Life/Pod-Usage/issues/new> to file a bug
+report.  The previous ticketing system,
+L<https://rt.cpan.org/Dist/Display.html?Queue=Pod-Usage>, is deprecated for
+this package.
+
+More general questions or discussion about POD should be sent to the
+C<pod-people@perl.org> mail list. Send an empty email to
+C<pod-people-subscribe@perl.org> to subscribe.
+
+=head1 AUTHOR
 
 Marek Rouchal E<lt>marekr@cpan.orgE<gt>
 
+Nicolas R E<lt>nicolas@atoomic.orgE<gt>
+
 Brad Appleton E<lt>bradapp@enteract.comE<gt>
 
 Based on code for B<Pod::Text::pod2text()> written by
@@ -895,10 +911,13 @@ Pod::Usage (the distribution) is licensed under the same terms as Perl.
 
 =head1 ACKNOWLEDGMENTS
 
+Nicolas R (ATOOMIC) for setting up the Github repo and modernizing this
+package.
+
 rjbs for refactoring Pod::Usage to not use Pod::Parser any more.
 
-Steven McDougall E<lt>swmcd@world.std.comE<gt> for his help and patience
-with re-writing this manpage.
+Steven McDougall E<lt>swmcd@world.std.comE<gt> for his help and patience with
+re-writing this manpage.
 
 =head1 SEE ALSO
 
index a51df22..573559d 100644 (file)
@@ -1,5 +1,7 @@
 #!/usr/local/bin/perl
 
+use strict;
+use warnings;
 use Config;
 use File::Basename qw(&basename &dirname);
 use Cwd;
@@ -13,19 +15,19 @@ use Cwd;
 
 # This forces PL files to create target in same directory as PL file.
 # This is so that make depend always knows where to find PL derivatives.
-$origdir = cwd;
-chdir(dirname($0));
-$file = basename($0, '.PL');
+my $origdir = cwd;
+chdir( dirname($0) );
+my $file = basename( $0, '.PL' );
 $file .= '.com' if $^O eq 'VMS';
 
-open OUT,">$file" or die "Can't create $file: $!";
+open my $OUT, '>', $file or die "Can't create $file: $!";
 
 print "Extracting $file (with variable substitutions)\n";
 
 # In this section, perl variables will be expanded during extraction.
 # You can use $Config{...} to use Configure variables.
 
-print OUT <<"!GROK!THIS!";
+print {$OUT} <<"!GROK!THIS!";
 $Config{'startperl'}
     eval 'exec perl -S \$0 "\$@"'
         if 0;
@@ -33,7 +35,7 @@ $Config{'startperl'}
 
 # In the following, perl variables are not expanded during extraction.
 
-print OUT <<'!NO!SUBS!';
+print {$OUT} <<'!NO!SUBS!';
 
 #############################################################################
 # pod2usage -- command to print usage messages from embedded pod docs
@@ -195,7 +197,7 @@ pod2usage(\%usage);
 
 !NO!SUBS!
 
-close OUT or die "Can't close $file: $!";
-chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
+close($OUT) or die "Can't close $file: $!";
+chmod( 0755, $file ) or die "Can't reset permissions for $file: $!\n";
 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
-chdir $origdir;
+chdir($origdir);
index c19d4c5..f357042 100644 (file)
-#############################################################################\r
-# Pod/InputObjects.pm -- package which defines objects for input streams\r
-# and paragraphs and commands when parsing POD docs.\r
-#\r
-# Copyright (C) 1996-2000 by Bradford Appleton. All rights reserved.\r
-# This file is part of "PodParser". PodParser is free software;\r
-# you can redistribute it and/or modify it under the same terms\r
-# as Perl itself.\r
-#############################################################################\r
-\r
-package Pod::InputObjects;\r
-use strict;\r
-\r
-use vars qw($VERSION);\r
-$VERSION = '1.60';  ## Current version of this package\r
-require  5.005;    ## requires this Perl version or later\r
-\r
-#############################################################################\r
-\r
-=head1 NAME\r
-\r
-Pod::InputObjects - objects representing POD input paragraphs, commands, etc.\r
-\r
-=head1 SYNOPSIS\r
-\r
-    use Pod::InputObjects;\r
-\r
-=head1 REQUIRES\r
-\r
-perl5.004, Carp\r
-\r
-=head1 EXPORTS\r
-\r
-Nothing.\r
-\r
-=head1 DESCRIPTION\r
-\r
-This module defines some basic input objects used by B<Pod::Parser> when\r
-reading and parsing POD text from an input source. The following objects\r
-are defined:\r
-\r
-=begin __PRIVATE__\r
-\r
-=over 4\r
-\r
-=item package B<Pod::InputSource>\r
-\r
-An object corresponding to a source of POD input text. It is mostly a\r
-wrapper around a filehandle or C<IO::Handle>-type object (or anything\r
-that implements the C<getline()> method) which keeps track of some\r
-additional information relevant to the parsing of PODs.\r
-\r
-=back\r
-\r
-=end __PRIVATE__\r
-\r
-=over 4\r
-\r
-=item package B<Pod::Paragraph>\r
-\r
-An object corresponding to a paragraph of POD input text. It may be a\r
-plain paragraph, a verbatim paragraph, or a command paragraph (see\r
-L<perlpod>).\r
-\r
-=item package B<Pod::InteriorSequence>\r
-\r
-An object corresponding to an interior sequence command from the POD\r
-input text (see L<perlpod>).\r
-\r
-=item package B<Pod::ParseTree>\r
-\r
-An object corresponding to a tree of parsed POD text. Each "node" in\r
-a parse-tree (or I<ptree>) is either a text-string or a reference to\r
-a B<Pod::InteriorSequence> object. The nodes appear in the parse-tree\r
-in the order in which they were parsed from left-to-right.\r
-\r
-=back\r
-\r
-Each of these input objects are described in further detail in the\r
-sections which follow.\r
-\r
-=cut\r
-\r
-#############################################################################\r
-\r
-package Pod::InputSource;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=begin __PRIVATE__\r
-\r
-=head1 B<Pod::InputSource>\r
-\r
-This object corresponds to an input source or stream of POD\r
-documentation. When parsing PODs, it is necessary to associate and store\r
-certain context information with each input source. All of this\r
-information is kept together with the stream itself in one of these\r
-C<Pod::InputSource> objects. Each such object is merely a wrapper around\r
-an C<IO::Handle> object of some kind (or at least something that\r
-implements the C<getline()> method). They have the following\r
-methods/attributes:\r
-\r
-=end __PRIVATE__\r
-\r
-=cut\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=begin __PRIVATE__\r
-\r
-=head2 B<new()>\r
-\r
-        my $pod_input1 = Pod::InputSource->new(-handle => $filehandle);\r
-        my $pod_input2 = new Pod::InputSource(-handle => $filehandle,\r
-                                              -name   => $name);\r
-        my $pod_input3 = new Pod::InputSource(-handle => \*STDIN);\r
-        my $pod_input4 = Pod::InputSource->new(-handle => \*STDIN,\r
-                                               -name => "(STDIN)");\r
-\r
-This is a class method that constructs a C<Pod::InputSource> object and\r
-returns a reference to the new input source object. It takes one or more\r
-keyword arguments in the form of a hash. The keyword C<-handle> is\r
-required and designates the corresponding input handle. The keyword\r
-C<-name> is optional and specifies the name associated with the input\r
-handle (typically a file name).\r
-\r
-=end __PRIVATE__\r
-\r
-=cut\r
-\r
-sub new {\r
-    ## Determine if we were called via an object-ref or a classname\r
-    my $this = shift;\r
-    my $class = ref($this) || $this;\r
-\r
-    ## Any remaining arguments are treated as initial values for the\r
-    ## hash that is used to represent this object. Note that we default\r
-    ## certain values by specifying them *before* the arguments passed.\r
-    ## If they are in the argument list, they will override the defaults.\r
-    my $self = { -name        => '(unknown)',\r
-                 -handle      => undef,\r
-                 -was_cutting => 0,\r
-                 @_ };\r
-\r
-    ## Bless ourselves into the desired class and perform any initialization\r
-    bless $self, $class;\r
-    return $self;\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=begin __PRIVATE__\r
-\r
-=head2 B<name()>\r
-\r
-        my $filename = $pod_input->name();\r
-        $pod_input->name($new_filename_to_use);\r
-\r
-This method gets/sets the name of the input source (usually a filename).\r
-If no argument is given, it returns a string containing the name of\r
-the input source; otherwise it sets the name of the input source to the\r
-contents of the given argument.\r
-\r
-=end __PRIVATE__\r
-\r
-=cut\r
-\r
-sub name {\r
-   (@_ > 1)  and  $_[0]->{'-name'} = $_[1];\r
-   return $_[0]->{'-name'};\r
-}\r
-\r
-## allow 'filename' as an alias for 'name'\r
-*filename = \&name;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=begin __PRIVATE__\r
-\r
-=head2 B<handle()>\r
-\r
-        my $handle = $pod_input->handle();\r
-\r
-Returns a reference to the handle object from which input is read (the\r
-one used to contructed this input source object).\r
-\r
-=end __PRIVATE__\r
-\r
-=cut\r
-\r
-sub handle {\r
-   return $_[0]->{'-handle'};\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=begin __PRIVATE__\r
-\r
-=head2 B<was_cutting()>\r
-\r
-        print "Yes.\n" if ($pod_input->was_cutting());\r
-\r
-The value of the C<cutting> state (that the B<cutting()> method would\r
-have returned) immediately before any input was read from this input\r
-stream. After all input from this stream has been read, the C<cutting>\r
-state is restored to this value.\r
-\r
-=end __PRIVATE__\r
-\r
-=cut\r
-\r
-sub was_cutting {\r
-   (@_ > 1)  and  $_[0]->{-was_cutting} = $_[1];\r
-   return $_[0]->{-was_cutting};\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-#############################################################################\r
-\r
-package Pod::Paragraph;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head1 B<Pod::Paragraph>\r
-\r
-An object representing a paragraph of POD input text.\r
-It has the following methods/attributes:\r
-\r
-=cut\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 Pod::Paragraph-E<gt>B<new()>\r
-\r
-        my $pod_para1 = Pod::Paragraph->new(-text => $text);\r
-        my $pod_para2 = Pod::Paragraph->new(-name => $cmd,\r
-                                            -text => $text);\r
-        my $pod_para3 = new Pod::Paragraph(-text => $text);\r
-        my $pod_para4 = new Pod::Paragraph(-name => $cmd,\r
-                                           -text => $text);\r
-        my $pod_para5 = Pod::Paragraph->new(-name => $cmd,\r
-                                            -text => $text,\r
-                                            -file => $filename,\r
-                                            -line => $line_number);\r
-\r
-This is a class method that constructs a C<Pod::Paragraph> object and\r
-returns a reference to the new paragraph object. It may be given one or\r
-two keyword arguments. The C<-text> keyword indicates the corresponding\r
-text of the POD paragraph. The C<-name> keyword indicates the name of\r
-the corresponding POD command, such as C<head1> or C<item> (it should\r
-I<not> contain the C<=> prefix); this is needed only if the POD\r
-paragraph corresponds to a command paragraph. The C<-file> and C<-line>\r
-keywords indicate the filename and line number corresponding to the\r
-beginning of the paragraph \r
-\r
-=cut\r
-\r
-sub new {\r
-    ## Determine if we were called via an object-ref or a classname\r
-    my $this = shift;\r
-    my $class = ref($this) || $this;\r
-\r
-    ## Any remaining arguments are treated as initial values for the\r
-    ## hash that is used to represent this object. Note that we default\r
-    ## certain values by specifying them *before* the arguments passed.\r
-    ## If they are in the argument list, they will override the defaults.\r
-    my $self = {\r
-          -name       => undef,\r
-          -text       => (@_ == 1) ? shift : undef,\r
-          -file       => '<unknown-file>',\r
-          -line       => 0,\r
-          -prefix     => '=',\r
-          -separator  => ' ',\r
-          -ptree => [],\r
-          @_\r
-    };\r
-\r
-    ## Bless ourselves into the desired class and perform any initialization\r
-    bless $self, $class;\r
-    return $self;\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_para-E<gt>B<cmd_name()>\r
-\r
-        my $para_cmd = $pod_para->cmd_name();\r
-\r
-If this paragraph is a command paragraph, then this method will return \r
-the name of the command (I<without> any leading C<=> prefix).\r
-\r
-=cut\r
-\r
-sub cmd_name {\r
-   (@_ > 1)  and  $_[0]->{'-name'} = $_[1];\r
-   return $_[0]->{'-name'};\r
-}\r
-\r
-## let name() be an alias for cmd_name()\r
-*name = \&cmd_name;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_para-E<gt>B<text()>\r
-\r
-        my $para_text = $pod_para->text();\r
-\r
-This method will return the corresponding text of the paragraph.\r
-\r
-=cut\r
-\r
-sub text {\r
-   (@_ > 1)  and  $_[0]->{'-text'} = $_[1];\r
-   return $_[0]->{'-text'};\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_para-E<gt>B<raw_text()>\r
-\r
-        my $raw_pod_para = $pod_para->raw_text();\r
-\r
-This method will return the I<raw> text of the POD paragraph, exactly\r
-as it appeared in the input.\r
-\r
-=cut\r
-\r
-sub raw_text {\r
-   return $_[0]->{'-text'}  unless (defined $_[0]->{'-name'});\r
-   return $_[0]->{'-prefix'} . $_[0]->{'-name'} .\r
-          $_[0]->{'-separator'} . $_[0]->{'-text'};\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_para-E<gt>B<cmd_prefix()>\r
-\r
-        my $prefix = $pod_para->cmd_prefix();\r
-\r
-If this paragraph is a command paragraph, then this method will return \r
-the prefix used to denote the command (which should be the string "="\r
-or "==").\r
-\r
-=cut\r
-\r
-sub cmd_prefix {\r
-   return $_[0]->{'-prefix'};\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_para-E<gt>B<cmd_separator()>\r
-\r
-        my $separator = $pod_para->cmd_separator();\r
-\r
-If this paragraph is a command paragraph, then this method will return\r
-the text used to separate the command name from the rest of the\r
-paragraph (if any).\r
-\r
-=cut\r
-\r
-sub cmd_separator {\r
-   return $_[0]->{'-separator'};\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_para-E<gt>B<parse_tree()>\r
-\r
-        my $ptree = $pod_parser->parse_text( $pod_para->text() );\r
-        $pod_para->parse_tree( $ptree );\r
-        $ptree = $pod_para->parse_tree();\r
-\r
-This method will get/set the corresponding parse-tree of the paragraph's text.\r
-\r
-=cut\r
-\r
-sub parse_tree {\r
-   (@_ > 1)  and  $_[0]->{'-ptree'} = $_[1];\r
-   return $_[0]->{'-ptree'};\r
-}\r
-\r
-## let ptree() be an alias for parse_tree()\r
-*ptree = \&parse_tree;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_para-E<gt>B<file_line()>\r
-\r
-        my ($filename, $line_number) = $pod_para->file_line();\r
-        my $position = $pod_para->file_line();\r
-\r
-Returns the current filename and line number for the paragraph\r
-object.  If called in a list context, it returns a list of two\r
-elements: first the filename, then the line number. If called in\r
-a scalar context, it returns a string containing the filename, followed\r
-by a colon (':'), followed by the line number.\r
-\r
-=cut\r
-\r
-sub file_line {\r
-   my @loc = ($_[0]->{'-file'} || '<unknown-file>',\r
-              $_[0]->{'-line'} || 0);\r
-   return (wantarray) ? @loc : join(':', @loc);\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-#############################################################################\r
-\r
-package Pod::InteriorSequence;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head1 B<Pod::InteriorSequence>\r
-\r
-An object representing a POD interior sequence command.\r
-It has the following methods/attributes:\r
-\r
-=cut\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 Pod::InteriorSequence-E<gt>B<new()>\r
-\r
-        my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd\r
-                                                  -ldelim => $delimiter);\r
-        my $pod_seq2 = new Pod::InteriorSequence(-name => $cmd,\r
-                                                 -ldelim => $delimiter);\r
-        my $pod_seq3 = new Pod::InteriorSequence(-name => $cmd,\r
-                                                 -ldelim => $delimiter,\r
-                                                 -file => $filename,\r
-                                                 -line => $line_number);\r
-\r
-        my $pod_seq4 = new Pod::InteriorSequence(-name => $cmd, $ptree);\r
-        my $pod_seq5 = new Pod::InteriorSequence($cmd, $ptree);\r
-\r
-This is a class method that constructs a C<Pod::InteriorSequence> object\r
-and returns a reference to the new interior sequence object. It should\r
-be given two keyword arguments.  The C<-ldelim> keyword indicates the\r
-corresponding left-delimiter of the interior sequence (e.g. 'E<lt>').\r
-The C<-name> keyword indicates the name of the corresponding interior\r
-sequence command, such as C<I> or C<B> or C<C>. The C<-file> and\r
-C<-line> keywords indicate the filename and line number corresponding\r
-to the beginning of the interior sequence. If the C<$ptree> argument is\r
-given, it must be the last argument, and it must be either string, or\r
-else an array-ref suitable for passing to B<Pod::ParseTree::new> (or\r
-it may be a reference to a Pod::ParseTree object).\r
-\r
-=cut\r
-\r
-sub new {\r
-    ## Determine if we were called via an object-ref or a classname\r
-    my $this = shift;\r
-    my $class = ref($this) || $this;\r
-\r
-    ## See if first argument has no keyword\r
-    if (((@_ <= 2) or (@_ % 2)) and $_[0] !~ /^-\w/) {\r
-       ## Yup - need an implicit '-name' before first parameter\r
-       unshift @_, '-name';\r
-    }\r
-\r
-    ## See if odd number of args\r
-    if ((@_ % 2) != 0) {\r
-       ## Yup - need an implicit '-ptree' before the last parameter\r
-       splice @_, $#_, 0, '-ptree';\r
-    }\r
-\r
-    ## Any remaining arguments are treated as initial values for the\r
-    ## hash that is used to represent this object. Note that we default\r
-    ## certain values by specifying them *before* the arguments passed.\r
-    ## If they are in the argument list, they will override the defaults.\r
-    my $self = {\r
-          -name       => (@_ == 1) ? $_[0] : undef,\r
-          -file       => '<unknown-file>',\r
-          -line       => 0,\r
-          -ldelim     => '<',\r
-          -rdelim     => '>',\r
-          @_\r
-    };\r
-\r
-    ## Initialize contents if they havent been already\r
-    my $ptree = $self->{'-ptree'} || new Pod::ParseTree();\r
-    if ( ref $ptree =~ /^(ARRAY)?$/ ) {\r
-        ## We have an array-ref, or a normal scalar. Pass it as an\r
-        ## an argument to the ptree-constructor\r
-        $ptree = new Pod::ParseTree($1 ? [$ptree] : $ptree);\r
-    }\r
-    $self->{'-ptree'} = $ptree;\r
-\r
-    ## Bless ourselves into the desired class and perform any initialization\r
-    bless $self, $class;\r
-    return $self;\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_seq-E<gt>B<cmd_name()>\r
-\r
-        my $seq_cmd = $pod_seq->cmd_name();\r
-\r
-The name of the interior sequence command.\r
-\r
-=cut\r
-\r
-sub cmd_name {\r
-   (@_ > 1)  and  $_[0]->{'-name'} = $_[1];\r
-   return $_[0]->{'-name'};\r
-}\r
-\r
-## let name() be an alias for cmd_name()\r
-*name = \&cmd_name;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-## Private subroutine to set the parent pointer of all the given\r
-## children that are interior-sequences to be $self\r
-\r
-sub _set_child2parent_links {\r
-   my ($self, @children) = @_;\r
-   ## Make sure any sequences know who their parent is\r
-   for (@children) {\r
-      next  unless (length  and  ref  and  ref ne 'SCALAR');\r
-      if (UNIVERSAL::isa($_, 'Pod::InteriorSequence') or\r
-          UNIVERSAL::can($_, 'nested'))\r
-      {\r
-          $_->nested($self);\r
-      }\r
-   }\r
-}\r
-\r
-## Private subroutine to unset child->parent links\r
-\r
-sub _unset_child2parent_links {\r
-   my $self = shift;\r
-   $self->{'-parent_sequence'} = undef;\r
-   my $ptree = $self->{'-ptree'};\r
-   for (@$ptree) {\r
-      next  unless (length  and  ref  and  ref ne 'SCALAR');\r
-      $_->_unset_child2parent_links()\r
-          if UNIVERSAL::isa($_, 'Pod::InteriorSequence');\r
-   }\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_seq-E<gt>B<prepend()>\r
-\r
-        $pod_seq->prepend($text);\r
-        $pod_seq1->prepend($pod_seq2);\r
-\r
-Prepends the given string or parse-tree or sequence object to the parse-tree\r
-of this interior sequence.\r
-\r
-=cut\r
-\r
-sub prepend {\r
-   my $self  = shift;\r
-   $self->{'-ptree'}->prepend(@_);\r
-   _set_child2parent_links($self, @_);\r
-   return $self;\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_seq-E<gt>B<append()>\r
-\r
-        $pod_seq->append($text);\r
-        $pod_seq1->append($pod_seq2);\r
-\r
-Appends the given string or parse-tree or sequence object to the parse-tree\r
-of this interior sequence.\r
-\r
-=cut\r
-\r
-sub append {\r
-   my $self = shift;\r
-   $self->{'-ptree'}->append(@_);\r
-   _set_child2parent_links($self, @_);\r
-   return $self;\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_seq-E<gt>B<nested()>\r
-\r
-        $outer_seq = $pod_seq->nested || print "not nested";\r
-\r
-If this interior sequence is nested inside of another interior\r
-sequence, then the outer/parent sequence that contains it is\r
-returned. Otherwise C<undef> is returned.\r
-\r
-=cut\r
-\r
-sub nested {\r
-   my $self = shift;\r
-  (@_ == 1)  and  $self->{'-parent_sequence'} = shift;\r
-   return  $self->{'-parent_sequence'} || undef;\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_seq-E<gt>B<raw_text()>\r
-\r
-        my $seq_raw_text = $pod_seq->raw_text();\r
-\r
-This method will return the I<raw> text of the POD interior sequence,\r
-exactly as it appeared in the input.\r
-\r
-=cut\r
-\r
-sub raw_text {\r
-   my $self = shift;\r
-   my $text = $self->{'-name'} . $self->{'-ldelim'};\r
-   for ( $self->{'-ptree'}->children ) {\r
-      $text .= (ref $_) ? $_->raw_text : $_;\r
-   }\r
-   $text .= $self->{'-rdelim'};\r
-   return $text;\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_seq-E<gt>B<left_delimiter()>\r
-\r
-        my $ldelim = $pod_seq->left_delimiter();\r
-\r
-The leftmost delimiter beginning the argument text to the interior\r
-sequence (should be "<").\r
-\r
-=cut\r
-\r
-sub left_delimiter {\r
-   (@_ > 1)  and  $_[0]->{'-ldelim'} = $_[1];\r
-   return $_[0]->{'-ldelim'};\r
-}\r
-\r
-## let ldelim() be an alias for left_delimiter()\r
-*ldelim = \&left_delimiter;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_seq-E<gt>B<right_delimiter()>\r
-\r
-The rightmost delimiter beginning the argument text to the interior\r
-sequence (should be ">").\r
-\r
-=cut\r
-\r
-sub right_delimiter {\r
-   (@_ > 1)  and  $_[0]->{'-rdelim'} = $_[1];\r
-   return $_[0]->{'-rdelim'};\r
-}\r
-\r
-## let rdelim() be an alias for right_delimiter()\r
-*rdelim = \&right_delimiter;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_seq-E<gt>B<parse_tree()>\r
-\r
-        my $ptree = $pod_parser->parse_text($paragraph_text);\r
-        $pod_seq->parse_tree( $ptree );\r
-        $ptree = $pod_seq->parse_tree();\r
-\r
-This method will get/set the corresponding parse-tree of the interior\r
-sequence's text.\r
-\r
-=cut\r
-\r
-sub parse_tree {\r
-   (@_ > 1)  and  $_[0]->{'-ptree'} = $_[1];\r
-   return $_[0]->{'-ptree'};\r
-}\r
-\r
-## let ptree() be an alias for parse_tree()\r
-*ptree = \&parse_tree;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $pod_seq-E<gt>B<file_line()>\r
-\r
-        my ($filename, $line_number) = $pod_seq->file_line();\r
-        my $position = $pod_seq->file_line();\r
-\r
-Returns the current filename and line number for the interior sequence\r
-object.  If called in a list context, it returns a list of two\r
-elements: first the filename, then the line number. If called in\r
-a scalar context, it returns a string containing the filename, followed\r
-by a colon (':'), followed by the line number.\r
-\r
-=cut\r
-\r
-sub file_line {\r
-   my @loc = ($_[0]->{'-file'}  || '<unknown-file>',\r
-              $_[0]->{'-line'}  || 0);\r
-   return (wantarray) ? @loc : join(':', @loc);\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 Pod::InteriorSequence::B<DESTROY()>\r
-\r
-This method performs any necessary cleanup for the interior-sequence.\r
-If you override this method then it is B<imperative> that you invoke\r
-the parent method from within your own method, otherwise\r
-I<interior-sequence storage will not be reclaimed upon destruction!>\r
-\r
-=cut\r
-\r
-sub DESTROY {\r
-   ## We need to get rid of all child->parent pointers throughout the\r
-   ## tree so their reference counts will go to zero and they can be\r
-   ## garbage-collected\r
-   _unset_child2parent_links(@_);\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-#############################################################################\r
-\r
-package Pod::ParseTree;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head1 B<Pod::ParseTree>\r
-\r
-This object corresponds to a tree of parsed POD text. As POD text is\r
-scanned from left to right, it is parsed into an ordered list of\r
-text-strings and B<Pod::InteriorSequence> objects (in order of\r
-appearance). A B<Pod::ParseTree> object corresponds to this list of\r
-strings and sequences. Each interior sequence in the parse-tree may\r
-itself contain a parse-tree (since interior sequences may be nested).\r
-\r
-=cut\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 Pod::ParseTree-E<gt>B<new()>\r
-\r
-        my $ptree1 = Pod::ParseTree->new;\r
-        my $ptree2 = new Pod::ParseTree;\r
-        my $ptree4 = Pod::ParseTree->new($array_ref);\r
-        my $ptree3 = new Pod::ParseTree($array_ref);\r
-\r
-This is a class method that constructs a C<Pod::Parse_tree> object and\r
-returns a reference to the new parse-tree. If a single-argument is given,\r
-it must be a reference to an array, and is used to initialize the root\r
-(top) of the parse tree.\r
-\r
-=cut\r
-\r
-sub new {\r
-    ## Determine if we were called via an object-ref or a classname\r
-    my $this = shift;\r
-    my $class = ref($this) || $this;\r
-\r
-    my $self = (@_ == 1  and  ref $_[0]) ? $_[0] : [];\r
-\r
-    ## Bless ourselves into the desired class and perform any initialization\r
-    bless $self, $class;\r
-    return $self;\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $ptree-E<gt>B<top()>\r
-\r
-        my $top_node = $ptree->top();\r
-        $ptree->top( $top_node );\r
-        $ptree->top( @children );\r
-\r
-This method gets/sets the top node of the parse-tree. If no arguments are\r
-given, it returns the topmost node in the tree (the root), which is also\r
-a B<Pod::ParseTree>. If it is given a single argument that is a reference,\r
-then the reference is assumed to a parse-tree and becomes the new top node.\r
-Otherwise, if arguments are given, they are treated as the new list of\r
-children for the top node.\r
-\r
-=cut\r
-\r
-sub top {\r
-   my $self = shift;\r
-   if (@_ > 0) {\r
-      @{ $self } = (@_ == 1  and  ref $_[0]) ? ${ @_ } : @_;\r
-   }\r
-   return $self;\r
-}\r
-\r
-## let parse_tree() & ptree() be aliases for the 'top' method\r
-*parse_tree = *ptree = \&top;\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $ptree-E<gt>B<children()>\r
-\r
-This method gets/sets the children of the top node in the parse-tree.\r
-If no arguments are given, it returns the list (array) of children\r
-(each of which should be either a string or a B<Pod::InteriorSequence>.\r
-Otherwise, if arguments are given, they are treated as the new list of\r
-children for the top node.\r
-\r
-=cut\r
-\r
-sub children {\r
-   my $self = shift;\r
-   if (@_ > 0) {\r
-      @{ $self } = (@_ == 1  and  ref $_[0]) ? ${ @_ } : @_;\r
-   }\r
-   return @{ $self };\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $ptree-E<gt>B<prepend()>\r
-\r
-This method prepends the given text or parse-tree to the current parse-tree.\r
-If the first item on the parse-tree is text and the argument is also text,\r
-then the text is prepended to the first item (not added as a separate string).\r
-Otherwise the argument is added as a new string or parse-tree I<before>\r
-the current one.\r
-\r
-=cut\r
-\r
-use vars qw(@ptree);  ## an alias used for performance reasons\r
-\r
-sub prepend {\r
-   my $self = shift;\r
-   local *ptree = $self;\r
-   for (@_) {\r
-      next  unless length;\r
-      if (@ptree && !(ref $ptree[0]) && !(ref $_)) {\r
-         $ptree[0] = $_ . $ptree[0];\r
-      }\r
-      else {\r
-         unshift @ptree, $_;\r
-      }\r
-   }\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-=head2 $ptree-E<gt>B<append()>\r
-\r
-This method appends the given text or parse-tree to the current parse-tree.\r
-If the last item on the parse-tree is text and the argument is also text,\r
-then the text is appended to the last item (not added as a separate string).\r
-Otherwise the argument is added as a new string or parse-tree I<after>\r
-the current one.\r
-\r
-=cut\r
-\r
-sub append {\r
-   my $self = shift;\r
-   local *ptree = $self;\r
-   my $can_append = @ptree && !(ref $ptree[-1]);\r
-   for (@_) {\r
-      if (ref) {\r
-         push @ptree, $_;\r
-      }\r
-      elsif(!length) {\r
-         next;\r
-      }\r
-      elsif ($can_append) {\r
-         $ptree[-1] .= $_;\r
-      }\r
-      else {\r
-         push @ptree, $_;\r
-      }\r
-   }\r
-}\r
-\r
-=head2 $ptree-E<gt>B<raw_text()>\r
-\r
-        my $ptree_raw_text = $ptree->raw_text();\r
-\r
-This method will return the I<raw> text of the POD parse-tree\r
-exactly as it appeared in the input.\r
-\r
-=cut\r
-\r
-sub raw_text {\r
-   my $self = shift;\r
-   my $text = '';\r
-   for ( @$self ) {\r
-      $text .= (ref $_) ? $_->raw_text : $_;\r
-   }\r
-   return $text;\r
-}\r
-\r
-##---------------------------------------------------------------------------\r
-\r
-## Private routines to set/unset child->parent links\r
-\r
-sub _unset_child2parent_links {\r
-   my $self = shift;\r
-   local *ptree = $self;\r
-   for (@ptree) {\r
-       next  unless (defined and length  and  ref  and  ref ne 'SCALAR');\r
-       $_->_unset_child2parent_links()\r
-           if UNIVERSAL::isa($_, 'Pod::InteriorSequence');\r
-   }\r
-}\r
-\r
-sub _set_child2parent_links {\r
-    ## nothing to do, Pod::ParseTrees cant have parent pointers\r
-}\r
-\r
-=head2 Pod::ParseTree::B<DESTROY()>\r
-\r
-This method performs any necessary cleanup for the parse-tree.\r
-If you override this method then it is B<imperative>\r
-that you invoke the parent method from within your own method,\r
-otherwise I<parse-tree storage will not be reclaimed upon destruction!>\r
-\r
-=cut\r
-\r
-sub DESTROY {\r
-   ## We need to get rid of all child->parent pointers throughout the\r
-   ## tree so their reference counts will go to zero and they can be\r
-   ## garbage-collected\r
-   _unset_child2parent_links(@_);\r
-}\r
-\r
-#############################################################################\r
-\r
-=head1 SEE ALSO\r
-\r
-B<Pod::InputObjects> is part of the L<Pod::Parser> distribution.\r
-\r
-See L<Pod::Parser>, L<Pod::Select>\r
-\r
-=head1 AUTHOR\r
-\r
-Please report bugs using L<http://rt.cpan.org>.\r
-\r
-Brad Appleton E<lt>bradapp@enteract.comE<gt>\r
-\r
-=cut\r
-\r
-1;\r
+#############################################################################
+# Pod/InputObjects.pm -- package which defines objects for input streams
+# and paragraphs and commands when parsing POD docs.
+#
+# Copyright (C) 1996-2000 by Bradford Appleton. All rights reserved.
+# This file is part of "PodParser". PodParser is free software;
+# you can redistribute it and/or modify it under the same terms
+# as Perl itself.
+#############################################################################
+
+package Pod::InputObjects;
+use strict;
+use warnings;
+
+use vars qw($VERSION);
+$VERSION = '1.60';  ## Current version of this package
+require  5.005;    ## requires this Perl version or later
+
+#############################################################################
+
+=head1 NAME
+
+Pod::InputObjects - objects representing POD input paragraphs, commands, etc.
+
+=head1 SYNOPSIS
+
+    use Pod::InputObjects;
+
+=head1 REQUIRES
+
+perl5.004, Carp
+
+=head1 EXPORTS
+
+Nothing.
+
+=head1 DESCRIPTION
+
+This module defines some basic input objects used by B<Pod::Parser> when
+reading and parsing POD text from an input source. The following objects
+are defined:
+
+=begin __PRIVATE__
+
+=over 4
+
+=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
+that implements the C<getline()> method) which keeps track of some
+additional information relevant to the parsing of PODs.
+
+=back
+
+=end __PRIVATE__
+
+=over 4
+
+=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 package B<Pod::InteriorSequence>
+
+An object corresponding to an interior sequence command from the POD
+input text (see L<perlpod>).
+
+=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 the order in which they were parsed from left-to-right.
+
+=back
+
+Each of these input objects are described in further detail in the
+sections which follow.
+
+=cut
+
+#############################################################################
+
+package Pod::InputSource;
+
+##---------------------------------------------------------------------------
+
+=begin __PRIVATE__
+
+=head1 B<Pod::InputSource>
+
+This object corresponds to an input source or stream of POD
+documentation. When parsing PODs, it is necessary to associate and store
+certain context information with each input source. All of this
+information is kept together with the stream itself in one of these
+C<Pod::InputSource> objects. Each such object is merely a wrapper around
+an C<IO::Handle> object of some kind (or at least something that
+implements the C<getline()> method). They have the following
+methods/attributes:
+
+=end __PRIVATE__
+
+=cut
+
+##---------------------------------------------------------------------------
+
+=begin __PRIVATE__
+
+=head2 B<new()>
+
+        my $pod_input1 = Pod::InputSource->new(-handle => $filehandle);
+        my $pod_input2 = Pod::InputSource->new(-handle => $filehandle,
+                                               -name   => $name);
+        my $pod_input3 = Pod::InputSource->new(-handle => \*STDIN);
+        my $pod_input4 = Pod::InputSource->new(-handle => \*STDIN,
+                                               -name => "(STDIN)");
+
+This is a class method that constructs a C<Pod::InputSource> object and
+returns a reference to the new input source object. It takes one or more
+keyword arguments in the form of a hash. The keyword C<-handle> is
+required and designates the corresponding input handle. The keyword
+C<-name> is optional and specifies the name associated with the input
+handle (typically a file name).
+
+=end __PRIVATE__
+
+=cut
+
+sub new {
+    ## Determine if we were called via an object-ref or a classname
+    my $this = shift;
+    my $class = ref($this) || $this;
+
+    ## Any remaining arguments are treated as initial values for the
+    ## hash that is used to represent this object. Note that we default
+    ## certain values by specifying them *before* the arguments passed.
+    ## If they are in the argument list, they will override the defaults.
+    my $self = { -name        => '(unknown)',
+                 -handle      => undef,
+                 -was_cutting => 0,
+                 @_ };
+
+    ## Bless ourselves into the desired class and perform any initialization
+    bless $self, $class;
+    return $self;
+}
+
+##---------------------------------------------------------------------------
+
+=begin __PRIVATE__
+
+=head2 B<name()>
+
+        my $filename = $pod_input->name();
+        $pod_input->name($new_filename_to_use);
+
+This method gets/sets the name of the input source (usually a filename).
+If no argument is given, it returns a string containing the name of
+the input source; otherwise it sets the name of the input source to the
+contents of the given argument.
+
+=end __PRIVATE__
+
+=cut
+
+sub name {
+   (@_ > 1)  and  $_[0]->{'-name'} = $_[1];
+   return $_[0]->{'-name'};
+}
+
+## allow 'filename' as an alias for 'name'
+*filename = \&name;
+
+##---------------------------------------------------------------------------
+
+=begin __PRIVATE__
+
+=head2 B<handle()>
+
+        my $handle = $pod_input->handle();
+
+Returns a reference to the handle object from which input is read (the
+one used to contructed this input source object).
+
+=end __PRIVATE__
+
+=cut
+
+sub handle {
+   return $_[0]->{'-handle'};
+}
+
+##---------------------------------------------------------------------------
+
+=begin __PRIVATE__
+
+=head2 B<was_cutting()>
+
+        print "Yes.\n" if ($pod_input->was_cutting());
+
+The value of the C<cutting> state (that the B<cutting()> method would
+have returned) immediately before any input was read from this input
+stream. After all input from this stream has been read, the C<cutting>
+state is restored to this value.
+
+=end __PRIVATE__
+
+=cut
+
+sub was_cutting {
+   (@_ > 1)  and  $_[0]->{-was_cutting} = $_[1];
+   return $_[0]->{-was_cutting};
+}
+
+##---------------------------------------------------------------------------
+
+#############################################################################
+
+package Pod::Paragraph;
+
+##---------------------------------------------------------------------------
+
+=head1 B<Pod::Paragraph>
+
+An object representing a paragraph of POD input text.
+It has the following methods/attributes:
+
+=cut
+
+##---------------------------------------------------------------------------
+
+=head2 Pod::Paragraph-E<gt>B<new()>
+
+        my $pod_para1 = Pod::Paragraph->new(-text => $text);
+        my $pod_para2 = Pod::Paragraph->new(-name => $cmd,
+                                            -text => $text);
+        my $pod_para3 = Pod::Paragraph->new(-text => $text);
+        my $pod_para4 = Pod::Paragraph->new(-name => $cmd,
+                                           -text => $text);
+        my $pod_para5 = Pod::Paragraph->new(-name => $cmd,
+                                            -text => $text,
+                                            -file => $filename,
+                                            -line => $line_number);
+
+This is a class method that constructs a C<Pod::Paragraph> object and
+returns a reference to the new paragraph object. It may be given one or
+two keyword arguments. The C<-text> keyword indicates the corresponding
+text of the POD paragraph. The C<-name> keyword indicates the name of
+the corresponding POD command, such as C<head1> or C<item> (it should
+I<not> contain the C<=> prefix); this is needed only if the POD
+paragraph corresponds to a command paragraph. The C<-file> and C<-line>
+keywords indicate the filename and line number corresponding to the
+beginning of the paragraph 
+
+=cut
+
+sub new {
+    ## Determine if we were called via an object-ref or a classname
+    my $this = shift;
+    my $class = ref($this) || $this;
+
+    ## Any remaining arguments are treated as initial values for the
+    ## hash that is used to represent this object. Note that we default
+    ## certain values by specifying them *before* the arguments passed.
+    ## If they are in the argument list, they will override the defaults.
+    my $self = {
+          -name       => undef,
+          -text       => (@_ == 1) ? shift : undef,
+          -file       => '<unknown-file>',
+          -line       => 0,
+          -prefix     => '=',
+          -separator  => ' ',
+          -ptree => [],
+          @_
+    };
+
+    ## Bless ourselves into the desired class and perform any initialization
+    bless $self, $class;
+    return $self;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_para-E<gt>B<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 (I<without> any leading C<=> prefix).
+
+=cut
+
+sub cmd_name {
+   (@_ > 1)  and  $_[0]->{'-name'} = $_[1];
+   return $_[0]->{'-name'};
+}
+
+## let name() be an alias for cmd_name()
+*name = \&cmd_name;
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_para-E<gt>B<text()>
+
+        my $para_text = $pod_para->text();
+
+This method will return the corresponding text of the paragraph.
+
+=cut
+
+sub text {
+   (@_ > 1)  and  $_[0]->{'-text'} = $_[1];
+   return $_[0]->{'-text'};
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_para-E<gt>B<raw_text()>
+
+        my $raw_pod_para = $pod_para->raw_text();
+
+This method will return the I<raw> text of the POD paragraph, exactly
+as it appeared in the input.
+
+=cut
+
+sub raw_text {
+   return $_[0]->{'-text'}  unless (defined $_[0]->{'-name'});
+   return $_[0]->{'-prefix'} . $_[0]->{'-name'} .
+          $_[0]->{'-separator'} . $_[0]->{'-text'};
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_para-E<gt>B<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 "="
+or "==").
+
+=cut
+
+sub cmd_prefix {
+   return $_[0]->{'-prefix'};
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_para-E<gt>B<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
+paragraph (if any).
+
+=cut
+
+sub cmd_separator {
+   return $_[0]->{'-separator'};
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_para-E<gt>B<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.
+
+=cut
+
+sub parse_tree {
+   (@_ > 1)  and  $_[0]->{'-ptree'} = $_[1];
+   return $_[0]->{'-ptree'};
+}
+
+## let ptree() be an alias for parse_tree()
+*ptree = \&parse_tree;
+
+##---------------------------------------------------------------------------
+
+=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 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.
+
+=cut
+
+sub file_line {
+   my @loc = ($_[0]->{'-file'} || '<unknown-file>',
+              $_[0]->{'-line'} || 0);
+   return (wantarray) ? @loc : join(':', @loc);
+}
+
+##---------------------------------------------------------------------------
+
+#############################################################################
+
+package Pod::InteriorSequence;
+
+##---------------------------------------------------------------------------
+
+=head1 B<Pod::InteriorSequence>
+
+An object representing a POD interior sequence command.
+It has the following methods/attributes:
+
+=cut
+
+##---------------------------------------------------------------------------
+
+=head2 Pod::InteriorSequence-E<gt>B<new()>
+
+        my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd
+                                                  -ldelim => $delimiter);
+        my $pod_seq2 = Pod::InteriorSequence->new(-name => $cmd,
+                                                 -ldelim => $delimiter);
+        my $pod_seq3 = Pod::InteriorSequence->new(-name => $cmd,
+                                                 -ldelim => $delimiter,
+                                                 -file => $filename,
+                                                 -line => $line_number);
+
+        my $pod_seq4 = Pod::InteriorSequence->new(-name => $cmd, $ptree);
+        my $pod_seq5 = Pod::InteriorSequence->new($cmd, $ptree);
+
+This is a class method that constructs a C<Pod::InteriorSequence> object
+and returns a reference to the new interior sequence object. It should
+be given two keyword arguments.  The C<-ldelim> keyword indicates the
+corresponding left-delimiter of the interior sequence (e.g. 'E<lt>').
+The C<-name> keyword indicates the name of the corresponding interior
+sequence command, such as C<I> or C<B> or C<C>. The C<-file> and
+C<-line> keywords indicate the filename and line number corresponding
+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 a Pod::ParseTree object).
+
+=cut
+
+sub new {
+    ## Determine if we were called via an object-ref or a classname
+    my $this = shift;
+    my $class = ref($this) || $this;
+
+    ## See if first argument has no keyword
+    if (((@_ <= 2) or (@_ % 2)) and $_[0] !~ /^-\w/) {
+       ## Yup - need an implicit '-name' before first parameter
+       unshift @_, '-name';
+    }
+
+    ## See if odd number of args
+    if ((@_ % 2) != 0) {
+       ## Yup - need an implicit '-ptree' before the last parameter
+       splice @_, $#_, 0, '-ptree';
+    }
+
+    ## Any remaining arguments are treated as initial values for the
+    ## hash that is used to represent this object. Note that we default
+    ## certain values by specifying them *before* the arguments passed.
+    ## If they are in the argument list, they will override the defaults.
+    my $self = {
+          -name       => (@_ == 1) ? $_[0] : undef,
+          -file       => '<unknown-file>',
+          -line       => 0,
+          -ldelim     => '<',
+          -rdelim     => '>',
+          @_
+    };
+
+    ## Initialize contents if they havent been already
+    my $ptree = $self->{'-ptree'} || Pod::ParseTree->new();
+    if ( ref $ptree =~ /^(ARRAY)?$/ ) {
+        ## We have an array-ref, or a normal scalar. Pass it as an
+        ## an argument to the ptree-constructor
+        $ptree = Pod::ParseTree->new($1 ? [$ptree] : $ptree);
+    }
+    $self->{'-ptree'} = $ptree;
+
+    ## Bless ourselves into the desired class and perform any initialization
+    bless $self, $class;
+    return $self;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<cmd_name()>
+
+        my $seq_cmd = $pod_seq->cmd_name();
+
+The name of the interior sequence command.
+
+=cut
+
+sub cmd_name {
+   (@_ > 1)  and  $_[0]->{'-name'} = $_[1];
+   return $_[0]->{'-name'};
+}
+
+## let name() be an alias for cmd_name()
+*name = \&cmd_name;
+
+##---------------------------------------------------------------------------
+
+## Private subroutine to set the parent pointer of all the given
+## children that are interior-sequences to be $self
+
+sub _set_child2parent_links {
+   my ($self, @children) = @_;
+   ## Make sure any sequences know who their parent is
+   for (@children) {
+      next  unless (length  and  ref  and  ref ne 'SCALAR');
+      if (UNIVERSAL::isa($_, 'Pod::InteriorSequence') or
+          UNIVERSAL::can($_, 'nested'))
+      {
+          $_->nested($self);
+      }
+   }
+}
+
+## Private subroutine to unset child->parent links
+
+sub _unset_child2parent_links {
+   my $self = shift;
+   $self->{'-parent_sequence'} = undef;
+   my $ptree = $self->{'-ptree'};
+   for (@$ptree) {
+      next  unless (length  and  ref  and  ref ne 'SCALAR');
+      $_->_unset_child2parent_links()
+          if UNIVERSAL::isa($_, 'Pod::InteriorSequence');
+   }
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<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.
+
+=cut
+
+sub prepend {
+   my $self  = shift;
+   $self->{'-ptree'}->prepend(@_);
+   _set_child2parent_links($self, @_);
+   return $self;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<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.
+
+=cut
+
+sub append {
+   my $self = shift;
+   $self->{'-ptree'}->append(@_);
+   _set_child2parent_links($self, @_);
+   return $self;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<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 C<undef> is returned.
+
+=cut
+
+sub nested {
+   my $self = shift;
+  (@_ == 1)  and  $self->{'-parent_sequence'} = shift;
+   return  $self->{'-parent_sequence'} || undef;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<raw_text()>
+
+        my $seq_raw_text = $pod_seq->raw_text();
+
+This method will return the I<raw> text of the POD interior sequence,
+exactly as it appeared in the input.
+
+=cut
+
+sub raw_text {
+   my $self = shift;
+   my $text = $self->{'-name'} . $self->{'-ldelim'};
+   for ( $self->{'-ptree'}->children ) {
+      $text .= (ref $_) ? $_->raw_text : $_;
+   }
+   $text .= $self->{'-rdelim'};
+   return $text;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<left_delimiter()>
+
+        my $ldelim = $pod_seq->left_delimiter();
+
+The leftmost delimiter beginning the argument text to the interior
+sequence (should be "<").
+
+=cut
+
+sub left_delimiter {
+   (@_ > 1)  and  $_[0]->{'-ldelim'} = $_[1];
+   return $_[0]->{'-ldelim'};
+}
+
+## let ldelim() be an alias for left_delimiter()
+*ldelim = \&left_delimiter;
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<right_delimiter()>
+
+The rightmost delimiter beginning the argument text to the interior
+sequence (should be ">").
+
+=cut
+
+sub right_delimiter {
+   (@_ > 1)  and  $_[0]->{'-rdelim'} = $_[1];
+   return $_[0]->{'-rdelim'};
+}
+
+## let rdelim() be an alias for right_delimiter()
+*rdelim = \&right_delimiter;
+
+##---------------------------------------------------------------------------
+
+=head2 $pod_seq-E<gt>B<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
+sequence's text.
+
+=cut
+
+sub parse_tree {
+   (@_ > 1)  and  $_[0]->{'-ptree'} = $_[1];
+   return $_[0]->{'-ptree'};
+}
+
+## let ptree() be an alias for parse_tree()
+*ptree = \&parse_tree;
+
+##---------------------------------------------------------------------------
+
+=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 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.
+
+=cut
+
+sub file_line {
+   my @loc = ($_[0]->{'-file'}  || '<unknown-file>',
+              $_[0]->{'-line'}  || 0);
+   return (wantarray) ? @loc : join(':', @loc);
+}
+
+##---------------------------------------------------------------------------
+
+=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
+the parent method from within your own method, otherwise
+I<interior-sequence storage will not be reclaimed upon destruction!>
+
+=cut
+
+sub DESTROY {
+   ## We need to get rid of all child->parent pointers throughout the
+   ## tree so their reference counts will go to zero and they can be
+   ## garbage-collected
+   _unset_child2parent_links(@_);
+}
+
+##---------------------------------------------------------------------------
+
+#############################################################################
+
+package Pod::ParseTree;
+
+##---------------------------------------------------------------------------
+
+=head1 B<Pod::ParseTree>
+
+This object corresponds to a tree of parsed POD text. As POD text is
+scanned from left to right, it is parsed into an ordered list of
+text-strings and B<Pod::InteriorSequence> objects (in order of
+appearance). A B<Pod::ParseTree> 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).
+
+=cut
+
+##---------------------------------------------------------------------------
+
+=head2 Pod::ParseTree-E<gt>B<new()>
+
+        my $ptree1 = Pod::ParseTree->new;
+        my $ptree2 = Pod::ParseTree->new($array_ref);
+
+This is a class method that constructs a C<Pod::Parse_tree> 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
+(top) of the parse tree.
+
+=cut
+
+sub new {
+    ## Determine if we were called via an object-ref or a classname
+    my $this = shift;
+    my $class = ref($this) || $this;
+
+    my $self = (@_ == 1  and  ref $_[0]) ? $_[0] : [];
+
+    ## Bless ourselves into the desired class and perform any initialization
+    bless $self, $class;
+    return $self;
+}
+
+##---------------------------------------------------------------------------
+
+=head2 $ptree-E<gt>B<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 B<Pod::ParseTree>. 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.
+
+=cut
+
+sub top {
+   my $self = shift;
+   if (@_ > 0) {
+      @{ $self } = (@_ == 1  and  ref $_[0]) ? ${ @_ } : @_;
+   }
+   return $self;
+}
+
+## let parse_tree() & ptree() be aliases for the 'top' method
+*parse_tree = *ptree = \&top;
+
+##---------------------------------------------------------------------------
+
+=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
+(each of which should be either a string or a B<Pod::InteriorSequence>.
+Otherwise, if arguments are given, they are treated as the new list of
+children for the top node.
+
+=cut
+
+sub children {
+   my $self = shift;
+   if (@_ > 0) {
+      @{ $self } = (@_ == 1  and  ref $_[0]) ? ${ @_ } : @_;
+   }
+   return @{ $self };
+}
+
+##---------------------------------------------------------------------------
+
+=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,
+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 I<before>
+the current one.
+
+=cut
+
+use vars qw(@ptree);  ## an alias used for performance reasons
+
+sub prepend {
+   my $self = shift;
+   local *ptree = $self;
+   for (@_) {
+      next  unless length;
+      if (@ptree && !(ref $ptree[0]) && !(ref $_)) {
+         $ptree[0] = $_ . $ptree[0];
+      }
+      else {
+         unshift @ptree, $_;
+      }
+   }
+}
+
+##---------------------------------------------------------------------------
+
+=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,
+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 I<after>
+the current one.
+
+=cut
+
+sub append {
+   my $self = shift;
+   local *ptree = $self;
+   my $can_append = @ptree && !(ref $ptree[-1]);
+   for (@_) {
+      if (ref) {
+         push @ptree, $_;
+      }
+      elsif(!length) {
+         next;
+      }
+      elsif ($can_append) {
+         $ptree[-1] .= $_;
+      }
+      else {
+         push @ptree, $_;
+      }
+   }
+}
+
+=head2 $ptree-E<gt>B<raw_text()>
+
+        my $ptree_raw_text = $ptree->raw_text();
+
+This method will return the I<raw> text of the POD parse-tree
+exactly as it appeared in the input.
+
+=cut
+
+sub raw_text {
+   my $self = shift;
+   my $text = '';
+   for ( @$self ) {
+      $text .= (ref $_) ? $_->raw_text : $_;
+   }
+   return $text;
+}
+
+##---------------------------------------------------------------------------
+
+## Private routines to set/unset child->parent links
+
+sub _unset_child2parent_links {
+   my $self = shift;
+   local *ptree = $self;
+   for (@ptree) {
+       next  unless (defined and length  and  ref  and  ref ne 'SCALAR');
+       $_->_unset_child2parent_links()
+           if UNIVERSAL::isa($_, 'Pod::InteriorSequence');
+   }
+}
+
+sub _set_child2parent_links {
+    ## nothing to do, Pod::ParseTrees cant have parent pointers
+}
+
+=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>
+that you invoke the parent method from within your own method,
+otherwise I<parse-tree storage will not be reclaimed upon destruction!>
+
+=cut
+
+sub DESTROY {
+   ## We need to get rid of all child->parent pointers throughout the
+   ## tree so their reference counts will go to zero and they can be
+   ## garbage-collected
+   _unset_child2parent_links(@_);
+}
+
+#############################################################################
+
+=head1 SEE ALSO
+
+B<Pod::InputObjects> is part of the L<Pod::Parser> distribution.
+
+See L<Pod::Parser>, L<Pod::Select>
+
+=head1 AUTHOR
+
+Please report bugs using L<http://rt.cpan.org>.
+
+Brad Appleton E<lt>bradapp@enteract.comE<gt>
+
+=cut
+
+1;
index 4b4fecf..25d5620 100644 (file)
@@ -9,6 +9,7 @@
 \r
 package Pod::Parser;\r
 use strict;\r
+use warnings;\r
 \r
 ## These "variables" are used as local "glob aliases" for performance\r
 use vars qw($VERSION @ISA %myData %myOpts @input_stack);\r
@@ -67,7 +68,7 @@ Pod::Parser - base class for creating POD filters and translators
 \r
     ## Create a parser object and have it parse file whose name was\r
     ## given on the command-line (use STDIN if no files were given).\r
-    $parser = new MyParser();\r
+    $parser = MyParser->new();\r
     $parser->parse_from_filehandle(\*STDIN)  if (@ARGV == 0);\r
     for (@ARGV) { $parser->parse_from_file($_); }\r
 \r
@@ -212,7 +213,7 @@ use Exporter;
 BEGIN {\r
    if ($] < 5.006) {\r
       require Symbol;\r
-      import Symbol;\r
+      Symbol->import;\r
    }\r
 }\r
 @ISA = qw(Exporter);\r
@@ -416,8 +417,7 @@ subclass objects as well as base class objects, provided you use
 any of the following constructor invocation styles:\r
 \r
     my $parser1 = MyParser->new();\r
-    my $parser2 = new MyParser();\r
-    my $parser3 = $parser2->new();\r
+    my $parser2 = $parser1->new();\r
 \r
 where C<MyParser> is some subclass of B<Pod::Parser>.\r
 \r
@@ -434,7 +434,7 @@ associative array (or hash-table) my be passed to the B<new()>
 constructor, as in:\r
 \r
     my $parser1 = MyParser->new( MYDATA => $value1, MOREDATA => $value2 );\r
-    my $parser2 = new MyParser( -myflag => 1 );\r
+    my $parser2 = MyParser->new( -myflag => 1 );\r
 \r
 All arguments passed to the B<new()> constructor will be treated as\r
 key/value pairs in a hash-table. The newly constructed object will be\r
@@ -977,7 +977,7 @@ sub parse_paragraph {
         }\r
     }\r
     ## Save the attributes indicating how the command was specified.\r
-    $pod_para = new Pod::Paragraph(\r
+    $pod_para = Pod::Paragraph->new(\r
           -name      => $cmd,\r
           -text      => $text,\r
           -prefix    => $pfx,\r
@@ -1563,7 +1563,7 @@ sub _push_input_stream {
     $myData{_INFILE}  = '(unknown)'  unless (defined  $myData{_INFILE});\r
     $myData{_INPUT}   = $in_fh;\r
     my $input_top     = $myData{_TOP_STREAM}\r
-                      = new Pod::InputSource(\r
+                      = Pod::InputSource->new(\r
                             -name        => $myData{_INFILE},\r
                             -handle      => $in_fh,\r
                             -was_cutting => $myData{_CUTTING}\r
@@ -1712,7 +1712,7 @@ following:
 \r
     package main;\r
     ...\r
-    my $parser = new MyPodParserTree(...);\r
+    my $parser = MyPodParserTree->new(...);\r
     $parser->parse_from_file(...);\r
     my $paragraphs_ref = $parser->{'-paragraphs'};\r
 \r
@@ -1727,7 +1727,7 @@ interface for all parse-tree nodes. The result would look something like:
 \r
     sub begin_pod {\r
         my $self = shift;\r
-        $self->{'-ptree'} = new Pod::ParseTree;  ## initialize parse-tree\r
+        $self->{'-ptree'} = Pod::ParseTree->new();  ## initialize parse-tree\r
     }\r
 \r
     sub parse_tree {\r
@@ -1759,7 +1759,7 @@ interface for all parse-tree nodes. The result would look something like:
 \r
     package main;\r
     ...\r
-    my $parser = new MyPodParserTree2(...);\r
+    my $parser = MyPodParserTree2->new(...);\r
     $parser->parse_from_file(...);\r
     my $ptree = $parser->parse_tree;\r
     ...\r
index e8dc001..733d2a0 100644 (file)
@@ -17,6 +17,7 @@
 \r
 package Pod::PlainText;\r
 use strict;\r
+use warnings;\r
 \r
 require 5.005;\r
 \r
@@ -34,7 +35,7 @@ $VERSION = '2.06';
 BEGIN {\r
    if ($] < 5.006) {\r
       require Symbol;\r
-      import Symbol;\r
+      Symbol->import;\r
    }\r
 }\r
 \r
index 148b5d1..5065506 100644 (file)
@@ -9,6 +9,7 @@
 \r
 package Pod::Select;\r
 use strict;\r
+use warnings;\r
 \r
 use vars qw($VERSION @ISA @EXPORT $MAX_HEADING_LEVEL %myData @section_headings @selected_sections);\r
 $VERSION = '1.60'; ## Current version of this package\r
@@ -44,7 +45,7 @@ or
     use Pod::Select;\r
 \r
     ## Create a parser object for selecting POD sections from the input\r
-    $parser = new Pod::Select();\r
+    $parser = Pod::Select->new();\r
 \r
     ## Select all the POD sections for each file in @filelist\r
     ## and print the result to tmp.out.\r
@@ -575,7 +576,7 @@ filenames are given).
 sub podselect {\r
     my(@argv) = @_;\r
     my %defaults = ();\r
-    my $pod_parser = new Pod::Select(%defaults);\r
+    my $pod_parser = Pod::Select->new(%defaults);\r
     my $num_inputs = 0;\r
     my $output = '>&STDOUT';\r
     my %opts;\r
index adba2be..ef745d1 100644 (file)
@@ -1,5 +1,8 @@
 use Test::More tests => 1;
 
+use strict;
+use warnings;
+
 my $blib = $ENV{PERL_CORE} ? '-I../../lib' : '-Mblib';
 
 my $pl = $0;
index ec0e3a7..4569043 100644 (file)
@@ -1,4 +1,7 @@
 use Pod::Usage;
+use strict;
+use warnings;
+
 pod2usage(-verbose => 2, -exit => 17, -input => \*DATA);
 
 __DATA__
index cf2c31b..3ee7450 100644 (file)
@@ -1,9 +1,12 @@
+use strict;
+use warnings;
+
 BEGIN {
    use File::Basename;
    my $THISDIR = dirname $0;
    unshift @INC, $THISDIR;
    require "testp2pt.pl";
-   import TestPodIncPlainText;
+   TestPodIncPlainText->import;
 }
 
 my %options = map { $_ => 1 } @ARGV;  ## convert cmdline to options-hash
index a6552c5..8616422 100644 (file)
@@ -1,14 +1,17 @@
 #!/usr/bin/perl -w
 
-use Test::More;
 use strict;
+use warnings;
+use Test::More;
+use File::Basename qw(fileparse);
+use File::Spec;
 
 BEGIN {
   if ($^O eq 'MSWin32' || $^O eq 'VMS') {
     plan skip_all => "Not portable on Win32 or VMS\n";
   }
   else {
-    plan tests => 33;
+    plan tests => 42;
   }
   use_ok ("Pod::Usage");
 }
@@ -16,24 +19,32 @@ BEGIN {
 sub getoutput
 {
   my ($code) = @_;
-  my $pid = open(TEST_IN, "-|");
-  unless(defined $pid) {
-    die "Cannot fork: $!";
-  }
-  if($pid) {
+  my $pid = open(my $in, "-|");
+  die "Cannot fork: $!" unless defined $pid;
+  if ($pid) {
     # parent
-    my @out = <TEST_IN>;
-    close(TEST_IN);
+    my @out = <$in>;
+    close($in);
+
     my $exit = $?>>8;
     s/^/#/ for @out;
+
     local $" = "";
+
     print "#EXIT=$exit OUTPUT=+++#@out#+++\n";
-    return($exit, join("",@out));
+    waitpid( $pid, 1 );
+
+    return ($exit, join("", @out) );
   }
   # child
-  open(STDERR, ">&STDOUT");
+  open (STDERR, ">&STDOUT");
+
   Test::More->builder->no_ending(1);
-  &$code;
+  local $SIG{ALRM} = sub { die "Alarm reached" };
+  alarm(600);
+
+  # this could hang
+  $code->();
   print "--NORMAL-RETURN--\n";
   exit 0;
 }
@@ -69,17 +80,17 @@ ok (compare ($text, <<'EOT'), "Output test pod2usage (-message => '...', -verbos
 #You naughty person, what did you say?
 # Usage:
 #     frobnicate [ -r | --recursive ] [ -f | --force ] file ...
-# 
+#
 # Options:
 #     -r | --recursive
 #         Run recursively.
-# 
+#
 #     -f | --force
 #         Just do it!
-# 
+#
 #     -n number
 #         Specify number of frobs, default is 42.
-# 
+#
 EOT
 
 ($exit, $text) = getoutput( sub { pod2usage(
@@ -214,7 +225,7 @@ is ($exit, 0,                 "Exit status pod2usage with USAGE and verbose=99")
 ok (compare ($text, <<'EOT'), "Output test pod2usage with USAGE and verbose=99") or diag "Got:\n$text\n";
 #Usage:
 #    This is a test for CPAN#33020
-# 
+#
 EOT
 
 # test with self
@@ -238,13 +249,13 @@ ok (compare ($text, <<'EOT'), "Output test pod2usage with self") or diag "Got:\n
 #      pod2usage($exit_status);
 #
 #      pod2usage( { -message => $message_text ,
-#                   -exitval => $exit_status  ,  
-#                   -verbose => $verbose_level,  
+#                   -exitval => $exit_status  ,
+#                   -verbose => $verbose_level,
 #                   -output  => $filehandle } );
 #
 #      pod2usage(   -msg     => $message_text ,
-#                   -exitval => $exit_status  ,  
-#                   -verbose => $verbose_level,  
+#                   -exitval => $exit_status  ,
+#                   -verbose => $verbose_level,
 #                   -output  => $filehandle   );
 #
 #      pod2usage(   -verbose => 2,
@@ -323,6 +334,58 @@ ok (compare ($text, <<'EOT'), "Output test pod2usage with subheadings in OPTIONS
 #    from the values by whitespace or the "=" character.
 #
 EOT
+
+# test various use cases of calling pod2usage to increase coverage
+($exit, $text) = getoutput( sub {
+  pod2usage({ -input => $pod_file2,
+            -exitval => 3, -verbose => 0 }) } );
+is ($exit, 3,                 "Exit status pod2usage with hash options");
+like ($text, qr/^\s*$/s, "Output test pod2usage with hash options is empty") or diag "Got:\n$text\n";
+
+# call with single string option
+($exit, $text) = getoutput( sub {
+  pod2usage('Just print this') } );
+is ($exit, 2,                 "Exit status pod2usage with single string option");
+like ($text, qr/^#Just print this/, "Output test pod2usage with single string options has first line") or diag "Got:\n$text\n";
+
+# call with search path and relative file name
+my ($file, $dir) = fileparse($0);
+($exit, $text) = getoutput( sub {
+  pod2usage({ -input => $file, -pathlist => [ $dir ], -exit => 0, -verbose => 2 } ) } );
+is ($exit, 0,                 "Exit status pod2usage with relative path");
+like ($text, qr/frobnicate - do what I mean/, "Output test pod2usage with relative path works OK") or diag "Got:\n$text\n";
+
+# trigger specific perldoc case
+# ...and one coverage line
+{ no warnings;
+  *Pod::Usage::initialize = sub { 1; };
+}
+
+SKIP: {
+    my $perldoc = $^X . 'doc';
+    skip "Missing perldoc binary", 2 unless -x $perldoc;
+
+    my $out = qx[$perldoc 2>&1] || '';
+    skip "Need perl-doc package", 2 if $out =~ qr[You need to install the perl-doc package to use this program];
+
+    ($exit, $text) = getoutput( sub {
+        require Pod::Perldoc;
+      my $devnull = File::Spec->devnull();
+      open(SAVE_STDOUT, '>&', \*STDOUT);
+      open(STDOUT, '>', $devnull);
+      pod2usage({ -verbose => 2, -input => $0, -output => \*STDOUT, -exit => 0, -message => 'Special perldoc case', -perldocopt => '-i' });
+      open(STDOUT, '>&', \*SAVE_STDOUT);
+      } );
+    is ($exit, 0,                 "Exit status pod2usage with special perldoc case");
+    # output went to devnull
+    like ($text, qr/^\s*$/s, "Output test pod2usage with special perldoc case") or diag "Got:\n$text\n";
+
+}
+
+# bad regexp syntax
+($exit, $text) = getoutput( sub { pod2usage( -verbose => 99, -sections => 'DESCRIPTION{BLAH') } );
+like ($text, qr/Bad regular expression/, "Output test pod2usage with bad section regexp");
+
 } # end SKIP
 
 __END__
index d0b557f..1fd6a7f 100644 (file)
@@ -1,5 +1,6 @@
 #!/usr/bin/perl -w
 use strict;
+use warnings;
 use Pod::Usage;
 
 my $h2 = shift @ARGV || '.*';
index ff138a3..0badc2f 100644 (file)
@@ -1,5 +1,8 @@
 use Test::More tests => 2;
 
+use strict;
+use warnings;
+
 my $blib = $ENV{PERL_CORE} ? '-I../../lib' : '-Mblib';
 
 my $pl = $0;
index 0f1ad82..29c4d26 100644 (file)
@@ -1,4 +1,7 @@
 #!/usr/bin/env perl
+use strict;
+use warnings;
+
 use Pod::Usage;
 
 my @tests = (
index d71c487..c6c1801 100644 (file)
@@ -1,5 +1,8 @@
 use Test::More tests => 2;
 
+use strict;
+use warnings;
+
 my $blib = $ENV{PERL_CORE} ? '-I../../lib' : '-Mblib';
 
 my $pl = $0;
index 1ba8022..f33fd4a 100644 (file)
@@ -10,7 +10,7 @@ BEGIN {
    my $THISDIR = abs_path(dirname $0);
    unshift @INC, $THISDIR;
    require "testcmp.pl";
-   import TestCompare;
+   TestCompare->import;
    # RT#130418: previous use of dirname() was failing on VMS
    $PARENTDIR = File::Spec->catdir($THISDIR, File::Spec->updir());
    push @INC, map { File::Spec->catdir($_, 'lib') } ($PARENTDIR, $THISDIR);