X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FPod%2FParser.pm;h=85551faca8896393e45ecf5096c6aefc5c63efef;hb=8e5f3f285c3a089acb6e38e5ef624a23fca2164f;hp=a00f0ee83ba67fd3f72fe51e17f61a2488d46fb4;hpb=48f30392d43cee251b79c036ba2aa18edf85fc30;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/Pod/Parser.pm b/lib/Pod/Parser.pm index a00f0ee..85551fa 100644 --- a/lib/Pod/Parser.pm +++ b/lib/Pod/Parser.pm @@ -10,8 +10,8 @@ package Pod::Parser; use vars qw($VERSION); -$VERSION = 1.11; ## Current version of this package -require 5.004; ## requires this Perl version or later +$VERSION = 1.13; ## Current version of this package +require 5.005; ## requires this Perl version or later ############################################################################# @@ -71,7 +71,7 @@ Pod::Parser - base class for creating POD filters and translators =head1 REQUIRES -perl5.004, Pod::InputObjects, Exporter, Carp +perl5.005, Pod::InputObjects, Exporter, Symbol, Carp =head1 EXPORTS @@ -151,7 +151,7 @@ to do more sophisticated tree-based parsing. See L<"TREE-BASED PARSING">. A I is simply a named option of B with a value that corresponds to a certain specified behavior. These various -behaviors of B may be enabled/disabled by setting or +behaviors of B may be enabled/disabled by setting or unsetting one or more I using the B method. The set of currently accepted parse-options is as follows: @@ -172,7 +172,7 @@ paragraph, or some other input paragraph. Normally (by default) B handles the C<=cut> POD directive by itself and does not pass it on to the caller for processing. Setting -this option to non-empty, non-zero value will cause B to +this option to a non-empty, non-zero value will cause B to pass the C<=cut> directive to the caller just like any other POD command (and hence it may be processed by the B method). @@ -181,6 +181,15 @@ B will still interpret the C<=cut> directive to mean that to capture the actual C<=cut> paragraph itself for whatever purpose it desires. +=item B<-warnings> (default: unset) + +Normally (by default) B recognizes a bare minimum of +pod syntax errors and warnings and issues diagnostic messages +for errors, but not for warnings. (Use B to do more +thorough checking of POD syntax.) Setting this option to a non-empty, +non-zero value will cause B to issue diagnostics for +the few warnings it recognizes as well as the errors. + =back Please see L<"parseopts()"> for a complete description of the interface @@ -196,6 +205,12 @@ use strict; use Pod::InputObjects; use Carp; use Exporter; +BEGIN { + if ($] < 5.6) { + require Symbol; + import Symbol; + } +} @ISA = qw(Exporter); ## These "variables" are used as local "glob aliases" for performance @@ -632,7 +647,7 @@ their functionality. This method is useful if you need to perform your own interpolation of interior sequences and can't rely upon B to expand -them in simple bottom-up order order. +them in simple bottom-up order. The parameter C<$text> is a string or block of text to be parsed for interior sequences; and the parameter C<$line_num> is the @@ -767,11 +782,11 @@ sub parse_text { ## Iterate over all sequence starts text (NOTE: split with ## capturing parens keeps the delimiters) $_ = $text; - my @tokens = split /([A-Z]<(?:<+\s+)?)/; + my @tokens = split /([A-Z]<(?:<+\s)?)/; while ( @tokens ) { $_ = shift @tokens; ## Look for the beginning of a sequence - if ( /^([A-Z])(<(?:<+\s+)?)$/ ) { + if ( /^([A-Z])(<(?:<+\s)?)$/ ) { ## Push a new sequence onto the stack of those "in-progress" ($cmd, $ldelim) = ($1, $2); $seq = Pod::InteriorSequence->new( @@ -836,7 +851,7 @@ sub parse_text { ($rdelim = $ldelim) =~ tr//; $rdelim =~ s/^(\S+)(\s*)$/$2$1/; pop @seq_stack; - my $errmsg = "*** WARNING: unterminated ${cmd}${ldelim}...${rdelim}". + my $errmsg = "*** ERROR: unterminated ${cmd}${ldelim}...${rdelim}". " at line $line in file $file\n"; (ref $errorsub) and &{$errorsub}($errmsg) or (defined $errorsub) and $self->$errorsub($errmsg) @@ -945,8 +960,7 @@ sub parse_paragraph { ## and whatever sequence of characters was used to separate them $pfx = $1; $_ = substr($text, length $pfx); - $sep = /(\s+)(?=\S)/ ? $1 : ''; - ($cmd, $text) = split(" ", $_, 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') { @@ -1025,6 +1039,8 @@ sub parse_from_filehandle { my %opts = (ref $_[0] eq 'HASH') ? %{ shift() } : (); my ($in_fh, $out_fh) = @_; $in_fh = \*STDIN unless ($in_fh); + local *myData = $self; ## alias to avoid deref-ing overhead + local *myOpts = ($myData{_PARSEOPTS} ||= {}); ## get parse-options local $_; ## Put this stream at the top of the stack and do beginning-of-input @@ -1059,10 +1075,11 @@ sub parse_from_filehandle { ## See if this line is blank and ends the current paragraph. ## If it isnt, then keep iterating until it is. - next unless (($textline =~ /^(\s*)$/) && (length $paragraph)); + next unless (($textline =~ /^([^\S\r\n]*)[\r\n]*$/) + && (length $paragraph)); ## Issue a warning about any non-empty blank lines - if (length($1) > 1 and ! $self->{_CUTTING}) { + if (length($1) > 0 and $myOpts{'-warnings'} and ! $myData{_CUTTING}) { my $errorsub = $self->errorsub(); my $file = $self->input_file(); my $errmsg = "*** WARNING: line containing nothing but whitespace". @@ -1132,7 +1149,7 @@ sub parse_from_file { my $self = shift; my %opts = (ref $_[0] eq 'HASH') ? %{ shift() } : (); my ($infile, $outfile) = @_; - my ($in_fh, $out_fh); + my ($in_fh, $out_fh) = (gensym, gensym) if ($] < 5.6); my ($close_input, $close_output) = (0, 0); local *myData = $self; local $_; @@ -1183,12 +1200,13 @@ sub parse_from_file { elsif (ref $outfile) { ## Must be a filehandle-ref (or else assume its a ref to an ## object that supports the common IO write operations). - $myData{_OUTFILE} = ${$outfile};; + $myData{_OUTFILE} = ${$outfile}; $out_fh = $outfile; } else { ## We have a filename, open it for writing $myData{_OUTFILE} = $outfile; + (-d $outfile) and croak "$outfile is a directory, not POD input!\n"; open($out_fh, "> $outfile") or croak "Can't open $outfile for writing: $!\n"; $close_output = 1; @@ -1291,7 +1309,7 @@ key/value pairs and the specified parse-option names are set to the given values. Any unspecified parse-options are unaffected. ## Set them back to the default - $parser->parseopts(-process_cut_cmd => 0); + $parser->parseopts(-warnings => 0); When passed a single hash-ref, B uses that hash to completely reset the existing parse-options, all previous parse-option values @@ -1300,7 +1318,7 @@ are lost. ## Reset all options to default $parser->parseopts( { } ); -See L<"PARSING OPTIONS"> for more for the name and meaning of each +See L<"PARSING OPTIONS"> for more information on the name and meaning of each parse-option currently recognized. =cut @@ -1570,7 +1588,7 @@ markup languages like HTML and XML) then you may need to take the tree-based approach. Rather than doing everything in one pass and calling the B method to expand sequences into text, it may be desirable to instead create a parse-tree using the B -method to return a tree-like structure which may contain an ordered list +method to return a tree-like structure which may contain an ordered list of children (each of which may be a text-string, or a similar tree-like structure).