Upgrade to Pod-Parser-1.36.
[perl.git] / lib / Pod / Parser.pm
index 1f4a33d..5e261a6 100644 (file)
@@ -8,9 +8,11 @@
 #############################################################################
 
 package Pod::Parser;
+use strict;
 
-use vars qw($VERSION);
-$VERSION = 1.35;  ## Current version of this package
+## These "variables" are used as local "glob aliases" for performance
+use vars qw($VERSION @ISA %myData %myOpts @input_stack);
+$VERSION = '1.36_01';  ## Current version of this package
 require  5.005;    ## requires this Perl version or later
 
 #############################################################################
@@ -118,7 +120,7 @@ You may also want to override the B<begin_input()> and B<end_input()>
 methods for your subclass (to perform any needed per-file and/or
 per-document initialization or cleanup).
 
-If you need to perform any preprocesssing of input before it is parsed
+If you need to perform any preprocessing of input before it is parsed
 you may want to override one or more of B<preprocess_line()> and/or
 B<preprocess_paragraph()>.
 
@@ -199,23 +201,18 @@ for the setting and unsetting of parse-options.
 
 #############################################################################
 
-use vars qw(@ISA);
-use strict;
 #use diagnostics;
 use Pod::InputObjects;
 use Carp;
 use Exporter;
 BEGIN {
-   if ($] < 5.6) {
+   if ($] < 5.006) {
       require Symbol;
       import Symbol;
    }
 }
 @ISA = qw(Exporter);
 
-## These "variables" are used as local "glob aliases" for performance
-use vars qw(%myData %myOpts @input_stack);
-
 #############################################################################
 
 =head1 RECOMMENDED SUBROUTINE/METHOD OVERRIDES
@@ -445,11 +442,10 @@ subclasses returns a blessed reference to the initialized object (hash-table).
 
 sub new {
     ## Determine if we were called via an object-ref or a classname
-    my $this = shift;
+    my ($this,%params) = @_;
     my $class = ref($this) || $this;
     ## Any remaining arguments are treated as initial values for the
     ## hash that is used to represent this object.
-    my %params = @_;
     my $self = { %params };
     ## Bless ourselves into the desired class and perform any initialization
     bless $self, $class;
@@ -757,9 +753,9 @@ sub parse_text {
         ## more than just the sequence object, we also need to pass the
         ## sequence name and text.
         $xseq_sub = sub {
-            my ($self, $iseq) = @_;
-            my $args = join("", $iseq->parse_tree->children);
-            return  $self->interior_sequence($iseq->name, $args, $iseq);
+            my ($sself, $iseq) = @_;
+            my $args = join('', $iseq->parse_tree->children);
+            return  $sself->interior_sequence($iseq->name, $args, $iseq);
         };
     }
     ref $xseq_sub    or  $xseq_sub   = sub { shift()->$expand_seq(@_) };
@@ -803,7 +799,7 @@ sub parse_text {
         ## Look for sequence ending
         elsif ( @seq_stack > 1 ) {
             ## Make sure we match the right kind of closing delimiter
-            my ($seq_end, $post_seq) = ("", "");
+            my ($seq_end, $post_seq) = ('', '');
             if ( ($ldelim eq '<'   and  /\A(.*?)(>)/s)
                  or  /\A(.*?)(\s+$rdelim)/s )
             {
@@ -861,7 +857,7 @@ sub parse_text {
                     " at line $line in file $file\n";
        (ref $errorsub) and &{$errorsub}($errmsg)
            or (defined $errorsub) and $self->$errorsub($errmsg)
-               or  warn($errmsg);
+               or  carp($errmsg);
        $seq_stack[-1]->append($expand_seq ? &$xseq_sub($self,$seq) : $seq);
        $seq = $seq_stack[-1];
     }
@@ -893,7 +889,7 @@ sub interpolate {
     my($self, $text, $line_num) = @_;
     my %parse_opts = ( -expand_seq => 'interior_sequence' );
     my $ptree = $self->parse_text( \%parse_opts, $text, $line_num );
-    return  join "", $ptree->children();
+    return  join '', $ptree->children();
 }
 
 ##---------------------------------------------------------------------------
@@ -966,7 +962,7 @@ sub parse_paragraph {
         ## and whatever sequence of characters was used to separate them
         $pfx = $1;
         $_ = substr($text, length $pfx);
-        ($cmd, $sep, $text) = split /(\s+)/, $_, 2; 
+        ($cmd, $sep, $text) = split /(\s+)/, $_, 2;
         ## If this is a "cut" directive then we dont need to do anything
         ## except return to "cutting" mode.
         if ($cmd eq 'cut') {
@@ -1145,7 +1141,10 @@ closes the input and output files.
 
 If the special input filename "-" or "<&STDIN" is given then the STDIN
 filehandle is used for input (and no open or close is performed). If no
-input filename is specified then "-" is implied.
+input filename is specified then "-" is implied. Filehandle references,
+or objects that support the regular IO operations (like C<E<lt>$fhE<gt>>
+or C<$fh-<Egt>getline>) are also accepted; the handles must already be 
+opened.
 
 If a second argument is given then it should be the name of the desired
 output file. If the special output filename "-" or ">&STDOUT" is given
@@ -1154,8 +1153,9 @@ performed). If the special output filename ">&STDERR" is given then the
 STDERR filehandle is used for output (and no open or close is
 performed). If no output filehandle is currently in use and no output
 filename is specified, then "-" is implied.
-Alternatively, an L<IO::String> object is also accepted as an output
-file handle.
+Alternatively, filehandle references or objects that support the regular
+IO operations (like C<print>, e.g. L<IO::String>) are also accepted;
+the object must already be opened.
 
 This method does I<not> usually need to be overridden by subclasses.
 
@@ -1188,7 +1188,7 @@ sub parse_from_file {
     {
         ## Not a filename, just a string implying STDIN
         $infile ||= '-';
-        $myData{_INFILE} = "<standard input>";
+        $myData{_INFILE} = '<standard input>';
         $in_fh = \*STDIN;
     }
     else {
@@ -1235,13 +1235,13 @@ sub parse_from_file {
         else {
             ## Not a filename, just a string implying STDOUT
             $outfile ||= '-';
-            $myData{_OUTFILE} = "<standard output>";
+            $myData{_OUTFILE} = '<standard output>';
             $out_fh  = \*STDOUT;
         }
     }
     elsif ($outfile =~ /^>&(STDERR|2)$/i) {
         ## Not a filename, just a string implying STDERR
-        $myData{_OUTFILE} = "<standard error>";
+        $myData{_OUTFILE} = '<standard error>';
         $out_fh  = \*STDERR;
     }
     else {
@@ -1258,7 +1258,7 @@ sub parse_from_file {
     ## have to parse the input and close the handles when we're finished.
     $self->parse_from_filehandle(\%opts, $in_fh, $out_fh);
 
-    $close_input  and 
+    $close_input  and
         close($in_fh) || croak "Can't close $infile after reading: $!\n";
     $close_output  and
         close($out_fh) || croak "Can't close $outfile after writing: $!\n";
@@ -1283,17 +1283,17 @@ instance data fields:
 
 Specifies the method or subroutine to use when printing error messages
 about POD syntax. The supplied method/subroutine I<must> return TRUE upon
-successful printing of the message. If C<undef> is given, then the B<warn>
+successful printing of the message. If C<undef> is given, then the B<carp>
 builtin is used to issue error messages (this is the default behavior).
 
             my $errorsub = $parser->errorsub()
             my $errmsg = "This is an error message!\n"
             (ref $errorsub) and &{$errorsub}($errmsg)
                 or (defined $errorsub) and $parser->$errorsub($errmsg)
-                    or  warn($errmsg);
+                    or  carp($errmsg);
 
 Returns a method name, or else a reference to the user-supplied subroutine
-used to print error messages. Returns C<undef> if the B<warn> builtin
+used to print error messages. Returns C<undef> if the B<carp> builtin
 is used to issue error messages (this is the default behavior).
 
 =cut
@@ -1813,6 +1813,16 @@ Brad Appleton E<lt>bradapp@enteract.comE<gt>
 Based on code for B<Pod::Text> written by
 Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
 
+=head1 LICENSE
+
+Pod-Parser is free software; you can redistribute it and/or modify it
+under the terms of the Artistic License distributed with Perl version
+5.000 or (at your option) any later version. Please refer to the
+Artistic License that came with your Perl distribution for more
+details. If your version of Perl was not distributed under the
+terms of the Artistic License, than you may distribute PodParser
+under the same terms as Perl itself.
+
 =cut
 
 1;