X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FPod%2FParser.pm;h=85551faca8896393e45ecf5096c6aefc5c63efef;hb=8e5f3f285c3a089acb6e38e5ef624a23fca2164f;hp=1bd440bbc4889cf47ed2a36f34ce93f4a9690fcf;hpb=eaf840779373130f95f7bd459b3864c78c698e28;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/Pod/Parser.pm b/lib/Pod/Parser.pm index 1bd440b..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,7 +205,12 @@ use strict; use Pod::InputObjects; use Carp; use Exporter; -require VMS::Filespec if $^O eq 'VMS'; +BEGIN { + if ($] < 5.6) { + require Symbol; + import Symbol; + } +} @ISA = qw(Exporter); ## These "variables" are used as local "glob aliases" for performance @@ -633,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 @@ -768,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( @@ -833,12 +847,11 @@ sub parse_text { my $errorsub = (@seq_stack > 1) ? $self->errorsub() : undef; while (@seq_stack > 1) { ($cmd, $file, $line) = ($seq->name, $seq->file_line); - $file = VMS::Filespec::unixify($file) if $^O eq 'VMS'; $ldelim = $seq->ldelim; ($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) @@ -947,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') { @@ -1027,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 @@ -1061,20 +1075,19 @@ 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 -# XXX avoid warning until Brad has a chance to make this optional --GSAR -# if (length($1) > 1 and ! $self->{_CUTTING}) { -# my $errorsub = $self->errorsub(); -# my $file = $self->input_file(); -# $file = VMS::Filespec::unixify($file) if $^O eq 'VMS'; -# my $errmsg = "*** WARNING: line containing nothing but whitespace". -# " in paragraph at line $nlines in file $file\n"; -# (ref $errorsub) and &{$errorsub}($errmsg) -# or (defined $errorsub) and $self->$errorsub($errmsg) -# or warn($errmsg); -# } + 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". + " in paragraph at line $nlines in file $file\n"; + (ref $errorsub) and &{$errorsub}($errmsg) + or (defined $errorsub) and $self->$errorsub($errmsg) + or warn($errmsg); + } ## Now process the paragraph parse_paragraph($self, $paragraph, ($nlines - $plines) + 1); @@ -1136,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 $_; @@ -1187,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; @@ -1295,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 @@ -1304,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 @@ -1574,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).