Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

import Pod::Simple 0.96 from CPAN

git-cpan-module: Pod::Simple
git-cpan-version: 0.96
git-cpan-authorid: SBURKE
  • Loading branch information...
commit 67346fe0724120436df6bb9022e2705db53b9b73 1 parent 48d7dcf
Sean M. Burke authored schwern committed
View
16 ChangeLog
@@ -1,5 +1,19 @@
-# ChangeLog for Pod::Simple dist # Time-stamp: "2002-11-10 01:47:14 MST"
+# ChangeLog for Pod::Simple dist # Time-stamp: "2002-11-20 00:28:53 MST"
+2002-11-19 Sean M. Burke <sburke@cpan.org>
+ * Release 0.96
+ * Still kinda sorta beta.
+
+ * Much much more docs in this version. Only a few feature
+ changes:
+
+ * Added any_errata_seen to Pod::Simple. Should've been in there
+ ages ago. Oops!
+ * Fixed some errors in the experimental VerbatimFormatted code.
+ * Added is_tagname / is_tag to Pod::Simple::PullParserStartToken
+ and Pod::Simple::PullParserEndToken
+ * Added RTFDEFLANG stuff to Pod::Simple::RTF.
+
2002-11-10 Sean M. Burke <sburke@cpan.org>
* Release 0.95
* Beta release. Much documentation still to write, many features
View
9 lib/Pod/Simple.pm
@@ -16,7 +16,7 @@ use vars qw(
);
@ISA = ('Pod::Simple::BlackBox');
-$VERSION = '0.95';
+$VERSION = '0.96';
@Known_formatting_codes = qw(I B C L E F S X Z);
%Known_formatting_codes = map(($_=>1), @Known_formatting_codes);
@@ -89,6 +89,12 @@ __PACKAGE__->_accessorize(
);
#@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+sub any_errata_seen { # good for using as an exit() value...
+ return shift->{'errors_seen'} || 0;
+}
+
+#@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
# Pull in some functions that, for some reason, I expect to see here too:
BEGIN {
*pretty = \&Pod::Simple::BlackBox::pretty;
@@ -321,6 +327,7 @@ sub parse_file {
sub parse_from_file {
# An emulation of Pod::Parser's interface, for the sake of Perldoc.
+ # Basically just a wrapper around parse_file.
my($self, $source, $to) = @_;
$self = $self->new unless ref($self); # so we tolerate being a class method
View
24 lib/Pod/Simple/BlackBox.pm
@@ -1050,9 +1050,24 @@ sub _verbatim_format {
for(my $i = $#$p; $i > 2; $i--) {
# work backwards over the lines, except the first (#2)
- next unless $p->[$i] =~ m{^#:([ \^\/\%]*)\n?$}s
- and $p->[$i-1] !~ m{^#:[ \^\/\%]*\n?$}s;
+ #next unless $p->[$i] =~ m{^#:([ \^\/\%]*)\n?$}s
+ # and $p->[$i-1] !~ m{^#:[ \^\/\%]*\n?$}s;
# look at a formatty line preceding a nonformatty one
+ DEBUG > 5 and print "Scrutinizing line $i: $$p[$i]\n";
+ if($p->[$i] =~ m{^#:([ \^\/\%]*)\n?$}s) {
+ DEBUG > 5 and print " It's a formatty line. ",
+ "Peeking at previous line ", $i-1, ": $$p[$i-1]: \n";
+
+ if( $p->[$i-1] =~ m{^#:[ \^\/\%]*\n?$}s ) {
+ DEBUG > 5 and print " Previous line is formatty! Skipping this one.\n";
+ next;
+ } else {
+ DEBUG > 5 and print " Previous line is non-formatty! Yay!\n";
+ }
+ } else {
+ DEBUG > 5 and print " It's not a formatty line. Ignoring\n";
+ next;
+ }
# A formatty line has to have #: in the first two columns, and uses
# "^" to mean bold, "/" to mean underline, and "%" to mean bold italic.
@@ -1102,7 +1117,10 @@ sub _verbatim_format {
}
}
splice @$p, $i-1, 2, @new_line; # replace myself and the next line
- $i -= @new_line; # Skip however many things we've just added!
+ DEBUG > 6 and print "New tokens: ", map( ref($_)?"<@$_> ":"<$_>", @new_line ), "\n";
+ $i -= @new_line - 2
+ # Skip however many things we've just added,
+ # minus the two tokens we just nixed.
}
$p->[0] = 'VerbatimFormatted';
View
17 lib/Pod/Simple/Checker.pm
@@ -9,7 +9,7 @@ use Carp ();
use Pod::Simple::Methody ();
use Pod::Simple ();
use vars qw( @ISA $VERSION );
-$VERSION = '1.01';
+$VERSION = '1.02';
@ISA = ('Pod::Simple::Methody');
BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG)
? \&Pod::Simple::DEBUG
@@ -131,27 +131,26 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::Checker -- check the Pod syntax of a document
=head1 SYNOPSIS
- TODO
-
perl -MPod::Simple::Checker -e \
"exit Pod::Simple::Checker->filter(shift)->any_errata_seen" \
thingy.pod
-
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+This class is for checking the syntactic validity of Pod.
+It works by basically acting like a simple-minded version of
+L<Pod::Simple::Text> that formats only the "Pod Errors" section
+(if Pod::Simple even generates one for the given document).
-TODO
+This is a subclass of L<Pod::Simple> and inherits all its methods.
=head1 SEE ALSO
-L<Pod::Simple>
+L<Pod::Simple>, L<Pod::Simple::Text>, L<Pod::Checker>
=head1 COPYRIGHT AND DISCLAIMERS
View
62 lib/Pod/Simple/Debug.pm
@@ -63,23 +63,75 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::Debug -- put Pod::Simple into trace/debug mode
=head1 SYNOPSIS
- TODO
+ use Pod::Simple::Debug (5); # or some integer
+
+Or:
+
+ my $debuglevel;
+ use Pod::Simple::Debug (\$debuglevel, 0);
+ ...some stuff that uses Pod::Simple to do stuff, but which
+ you don't want debug output from...
+
+ $debug_level = 4;
+ ...some stuff that uses Pod::Simple to do stuff, but which
+ you DO want debug output from...
+
+ $debug_level = 0;
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+This is an internal module for controlling the debug level (a.k.a. trace
+level) of Pod::Simple. This is of interest only to Pod::Simple
+developers.
+
+
+=head1 CAVEATS
+
+Note that you should load this module I<before> loading Pod::Simple (or
+any Pod::Simple-based class). If you try loading Pod::Simple::Debug
+after &Pod::Simple::DEBUG is already defined, Pod::Simple::Debug will
+throw a fatal error to the effect that
+"it's s too late to call Pod::Simple::Debug".
+
+Note that the C<use Pod::Simple::Debug (\$x, I<somenum>)> mode will make
+Pod::Simple (et al) run rather slower, since &Pod::Simple::DEBUG won't
+be a constant sub anymore, and so Pod::Simple (et al) won't compile with
+constant-folding.
+
-TODO
+=head1 GUTS
+
+Doing this:
+
+ use Pod::Simple::Debug (5); # or some integer
+
+is basically equivalent to:
+
+ BEGIN { sub Pod::Simple::DEBUG () {5} } # or some integer
+ use Pod::Simple ();
+
+And this:
+
+ use Pod::Simple::Debug (\$debug_level,0); # or some integer
+
+is basically equivalent to this:
+
+ my $debug_level;
+ BEGIN { $debug_level = 0 }
+ BEGIN { sub Pod::Simple::DEBUG () { $debug_level }
+ use Pod::Simple ();
=head1 SEE ALSO
L<Pod::Simple>
+The article "Constants in Perl", in I<The Perl Journal> issue
+21. See L<http://www.sysadminmag.com/tpj/issues/vol5_5/>
+
=head1 COPYRIGHT AND DISCLAIMERS
Copyright (c) 2002 Sean M. Burke. All rights reserved.
View
15 lib/Pod/Simple/DumpAsText.pm
@@ -1,7 +1,7 @@
require 5;
package Pod::Simple::DumpAsText;
-$VERSION = '1.01';
+$VERSION = '1.02';
use Pod::Simple ();
BEGIN {@ISA = ('Pod::Simple')}
@@ -15,6 +15,7 @@ sub new {
my $self = shift;
my $new = $self->SUPER::new(@_);
$new->{'output_fh'} ||= *STDOUT{IO};
+ $new->accept_codes('VerbatimFormatted');
return $new;
}
@@ -87,7 +88,7 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::DumpAsText -- dump Pod-parsing events as text
=head1 SYNOPSIS
@@ -97,13 +98,17 @@ TODO - TODO
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+This class is for dumping, as text, the events gotten from parsing a Pod
+document. This class is of interest to people writing Pod formatters
+based on Pod::Simple. It is useful for seeing exactly what events you
+get out of some Pod that you feed in.
-TODO
+This is a subclass of L<Pod::Simple> and inherits all its methods.
=head1 SEE ALSO
+L<Pod::Simple::DumpAsXML>
+
L<Pod::Simple>
=head1 COPYRIGHT AND DISCLAIMERS
View
35 lib/Pod/Simple/DumpAsXML.pm
@@ -1,7 +1,7 @@
require 5;
package Pod::Simple::DumpAsXML;
-$VERSION = '1.02';
+$VERSION = '1.01';
use Pod::Simple ();
BEGIN {@ISA = ('Pod::Simple')}
@@ -9,10 +9,6 @@ use strict;
use Carp ();
-# TODO: note that this is padding with WS
-# TODO: make a setting for leaving off the line number attributes?
-
-
BEGIN { *DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG }
sub new {
@@ -95,26 +91,41 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::DumpAsXML -- turn Pod into XML
=head1 SYNOPSIS
- TODO
-
perl -MPod::Simple::DumpAsXML -e \
"exit Pod::Simple::DumpAsXML->filter(shift)->any_errata_seen" \
thingy.pod
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+Pod::Simple::DumpAsXML is a subclass of L<Pod::Simple> that parses Pod
+and turns it into indented and wrapped XML. This class is of
+interest to people writing Pod formatters based on Pod::Simple.
+
+Pod::Simple::DumpAsXML inherits methods from
+L<Pod::Simple>.
-TODO
=head1 SEE ALSO
-L<Pod::Simple>
+L<Pod::Simple::XMLOutStream> is rather like this class.
+Pod::Simple::XMLOutStream's output is space-padded in a way
+that's better for sending to an XML processor (that is, it has
+no ignoreable whitespace). But
+Pod::Simple::DumpAsXML's output is much more human-readable, being
+(more-or-less) one token per line, with line-wrapping.
+
+L<Pod::Simple::DumpAsText> is rather like this class,
+except that it doesn't dump with XML syntax. Try them and see
+which one you like best!
+
+L<Pod::Simple>, L<Pod::Simple::DumpAsXML>
+
+The older libraries L<Pod::PXML>, L<Pod::XML>, L<Pod::SAX>
+
=head1 COPYRIGHT AND DISCLAIMERS
View
49 lib/Pod/Simple/LinkSection.pm
@@ -70,18 +70,57 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::LinkSection -- represent "section" attributes of L codes
=head1 SYNOPSIS
- TODO
+ # a long story
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+This class is not of interest to general users.
+
+Pod::Simple uses this class for representing the value of the
+"section" attribute of "L" start-element events. Most applications
+can just use the normal stringification of objects of this class;
+they stringify to just the text content of the section,
+such as "foo" for
+C<< LZ<><Stuff/foo> >>, and "bar" for
+C<< LZ<><Stuff/bIZ<><ar>> >>.
+
+However, anyone particularly interested in getting the full value of
+the treelet, can just traverse the content of the treeleet
+@$treelet_object. To wit:
+
+
+ % perl -MData::Dumper -e
+ "use base qw(Pod::Simple::Methody);
+ sub start_L { print Dumper($_[1]{'section'} ) }
+ __PACKAGE__->new->parse_string_document('=head1 L<Foo/bI<ar>baz>>')
+ "
+Output:
+ $VAR1 = bless( [
+ '',
+ {},
+ 'b',
+ bless( [
+ 'I',
+ {},
+ 'ar'
+ ], 'Pod::Simple::LinkSection' ),
+ 'baz'
+ ], 'Pod::Simple::LinkSection' );
+
+But stringify it and you get just the text content:
+
+ % perl -MData::Dumper -e
+ "use base qw(Pod::Simple::Methody);
+ sub start_L { print Dumper( '' . $_[1]{'section'} ) }
+ __PACKAGE__->new->parse_string_document('=head1 L<Foo/bI<ar>baz>>')
+ "
+Output:
+ $VAR1 = 'barbaz';
-TODO
=head1 SEE ALSO
View
66 lib/Pod/Simple/Methody.pm
@@ -3,9 +3,13 @@ require 5;
package Pod::Simple::Methody;
use strict;
use Pod::Simple ();
-use vars qw(@ISA);
+use vars qw(@ISA $VERSION);
+$VERSION = 1.02;
@ISA = ('Pod::Simple');
+# Yes, we could use named variables, but I want this to be impose
+# as little an additional performance hit as possible.
+
sub _handle_element_start {
$_[1] =~ tr/-:./__/;
( $_[0]->can( 'start_' . $_[1] )
@@ -39,22 +43,70 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::Methody -- turn Pod::Simple events into method calls
=head1 SYNOPSIS
- TODO
+ require 5;
+ use strict;
+ package SomePodFormatter;
+ use base qw(Pod::Simple::Methody);
+
+ sub handle_text {
+ my($self, $text) = @_;
+ ...
+ }
+
+ sub start_head1 {
+ my($self, $attrs) = @_;
+ ...
+ }
+ sub end_head1 {
+ my($self) = @_;
+ ...
+ }
+
+...and start_/end_ methods for whatever other events you want to catch.
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+This class is of
+interest to people writing Pod formatters based on Pod::Simple.
+
+This class (which is very small -- read the source) overrides
+Pod::Simple's _handle_element_start, _handle_text, and
+_handle_element_end methods so that parser events are turned into method
+calls. (Otherwise, this is a subclass of L<Pod::Simple> and inherits all
+its methods.)
+
+You can use this class as the base class for a Pod formatter/processor.
+
+=head1 METHOD CALLING
+
+When Pod::Simple sees a "=head1 Hi there", for example, it basically does
+this:
+
+ $parser->_handle_element_start( "head1", \%attributes );
+ $parser->_handle_text( "Hi there" );
+ $parser->_handle_element_end( "head1" );
+
+But if you subclass Pod::Simple::Methody, it will instead do this
+when it sees a "=head1 Hi there":
+
+ $parser->start_head1( \%attributes ) if $parser->can('start_head1');
+ $parser->handle_text( "Hi there" ) if $parser->can('handle_text');
+ $parser->end_head1() if $parser->can('end_head1');
+
+If Pod::Simple sends an event where the element name has a dash,
+period, or colon, the corresponding method name will have a underscore
+in its place. For example, "foo.bar:baz" becomes start_foo_bar_baz
+and end_foo_bar_baz.
-TODO
+See the source for Pod::Simple::Text for an example of using this class.
=head1 SEE ALSO
-L<Pod::Simple>
+L<Pod::Simple>, L<Pod::Simple::Subclassing>
=head1 COPYRIGHT AND DISCLAIMERS
View
191 lib/Pod/Simple/PullParser.pm
@@ -1,7 +1,7 @@
require 5;
package Pod::Simple::PullParser;
-$VERSION = '1.01';
+$VERSION = '1.02';
use Pod::Simple ();
BEGIN {@ISA = ('Pod::Simple')}
@@ -54,6 +54,18 @@ sub parse_file {
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# In case anyone tries to use them:
+sub run {
+ use Carp ();
+ if( __PACKAGE__ eq ref($_[0]) || $_[0]) { # I'm not being subclassed!
+ Carp::croak "You can call run() only on subclasses of "
+ . __PACKAGE__;
+ } else {
+ Carp::croak join '',
+ "You can't call run() because ",
+ ref($_[0]) || $_[0], " didn't define a run() method";
+ }
+}
+
sub parse_lines {
use Carp ();
Carp::croak "Use set_source with ", __PACKAGE__,
@@ -247,13 +259,13 @@ sub get_title_short { shift->get_short_title(@_) } # alias
sub get_short_title {
my $title = shift->get_title(@_);
- $title = $1 if $title =~ m/^(\S+)\s+--?\s+./s;
+ $title = $1 if $title =~ m/^(\S{1,60})\s+--?\s+./s;
# turn "Foo::Bar -- bars for your foo" into "Foo::Bar"
return $title;
}
-sub get_title {
+sub get_title { # some witchery in here
my $self = $_[0];
my $title;
my @to_unget;
@@ -361,23 +373,188 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::PullParser -- a pull-parser interface to parsing Pod
=head1 SYNOPSIS
- TODO
+ my $parser = SomePodProcessor->new;
+ $parser->set_source( "whatever.pod" );
+ $parser->run;
+
+Or:
+
+ my $parser = SomePodProcessor->new;
+ $parser->set_source( $some_filehandle_object );
+ $parser->run;
+
+Or:
+
+ my $parser = SomePodProcessor->new;
+ $parser->set_source( \$document_source );
+ $parser->run;
+
+Or:
+
+ my $parser = SomePodProcessor->new;
+ $parser->set_source( \@document_lines );
+ $parser->run;
+
+And elsewhere:
+
+ require 5;
+ package SomePodProcessor;
+ use strict;
+ use base qw(Pod::Simple::PullParser);
+
+ sub run {
+ my $self = shift;
+ Token:
+ while(my $token = $self->get_token) {
+ ...process each token...
+ }
+ }
=head1 DESCRIPTION
-This class is for TODO.
+This class is for using Pod::Simple to build a Pod processor -- but
+one that uses an interface based on a stream of token objects,
+instead of based on events.
+
This is a subclass of L<Pod::Simple> and inherits all its methods.
-TODO
+A subclass of Pod::Simple::PullParser should define a C<run> method
+that calls C<< $token = $parser->get_token >> to pull tokens.
+
+See the source for Pod::Simple::RTF for an example of a formatter
+that uses Pod::Simple::PullParser.
+
+=head1 METHODS
+
+=over
+
+=item my $token = $parser->get_token
+
+This returns the next token object (which will be of a subclass of
+L<Pod::Simple::PullParserToken>), or undef if the parser-stream has hit
+the end of the document.
+
+=item $parser->unget_token( $token )
+
+=item $parser->unget_token( $token1, $token2, ... )
+
+This restores the token object(s) to the front of the parser stream.
+
+=back
+
+The source has to be set before you can parse anything. The lowest-level
+way is to call C<set_source>:
+
+=over
+
+=item $parser->set_source( $filename )
+
+=item $parser->set_source( $filehandle_object )
+
+=item $parser->set_source( \$document_source )
+
+=item $parser->set_source( \@document_lines )
+
+=back
+
+Or you can call these methods, which Pod::Simple::PullParser has defined
+to work just like Pod::Simple's same-named methods:
+
+=over
+
+=item $parser->parse_file(...)
+
+=item $parser->parse_string_document(...)
+
+=item $parser->filter(...)
+
+=item $parser->parse_from_file(...)
+
+=back
+
+For those to work, the Pod-processing subclass of
+Pod::Simple::PullParser has to have defined a $parser->run method --
+so it is advised that all Pod::Simple::PullParser subclasses do so.
+See the Synopsis above, or the source for Pod::Simple::RTF.
+
+Authors of formatter subclasses might find these methods useful to
+call on a parser object that you haven't started pulling tokens
+from yet:
+
+=over
+
+=item my $title_string = $parser->get_title
+
+This tries to get the title string out of $parser, by getting some tokens,
+and scanning them for the title, and then ungetting them so that you can
+process the token-stream from the beginning.
+
+For example, suppose you have a document that starts out:
+
+ =head1 NAME
+
+ Hoo::Boy::Wowza -- Stuff B<wow> yeah!
+
+$parser->get_title on that document will return "Hoo::Boy::Wowza --
+Stuff wow yeah!".
+
+In cases where get_title can't find the title, it will return empty-string
+("").
+
+=item my $title_string = $parser->get_short_title
+
+This is just like get_title, except that it returns just the modulename, if
+the title seems to be of the form "SomeModuleName -- description".
+
+For example, suppose you have a document that starts out:
+
+ =head1 NAME
+
+ Hoo::Boy::Wowza -- Stuff B<wow> yeah!
+
+then $parser->get_short_title on that document will return
+"Hoo::Boy::Wowza".
+
+But if the document starts out:
+
+ =head1 NAME
+
+ Hooboy, stuff B<wow> yeah!
+
+then $parser->get_short_title on that document will return "Hooboy,
+stuff wow yeah!".
+
+If the title can't be found, then get_short_title returns empty-string
+("").
+
+=back
+
+=head1 NOTE
+
+You don't actually I<have> to define a C<run> method. If you're
+writing a Pod-formatter class, you should define a C<run> just so
+that users can call C<parse_file> etc, but you don't I<have> to.
+
+And if you're not writing a formatter class, but are instead just
+writing a program that does something simple with a Pod::PullParser
+object (and not an object of a subclass), then there's no reason to
+bother subclassing to add a C<run> method.
=head1 SEE ALSO
L<Pod::Simple>
+L<Pod::Simple::PullParserToken> -- and its subclasses
+L<Pod::Simple::PullParserStartToken>,
+L<Pod::Simple::PullParserTextToken>, and
+L<Pod::Simple::PullParserEndToken>.
+
+L<HTML::TokeParser>, which inspired this.
+
=head1 COPYRIGHT AND DISCLAIMERS
Copyright (c) 2002 Sean M. Burke. All rights reserved.
View
46 lib/Pod/Simple/PullParserEndToken.pm
@@ -15,6 +15,9 @@ sub new { # Class->new(tagname);
sub tagname { (@_ == 2) ? ($_[0][1] = $_[1]) : $_[0][1] }
sub tag { shift->tagname(@_) }
+# shortcut:
+sub is_tagname { $_[0][1] eq $_[1] }
+sub is_tag { shift->is_tagname(@_) }
1;
@@ -23,22 +26,53 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::PullParserEndToken -- end-tokens from Pod::Simple::PullParser
=head1 SYNOPSIS
- TODO
+(See L<Pod::Simple::PullParser>)
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+When you do $parser->get_token on a L<Pod::Simple::PullParser>, you might
+get an object of this class.
-TODO
+This is a subclass of L<Pod::Simple::PullParserToken> and inherits all its methods,
+and adds these methods:
+
+=over
+
+=item $token->tagname
+
+This returns the tagname for this end-token object.
+For example, parsing a "=head1 ..." line will give you
+a start-token with the tagname of "head1", token(s) for its
+content, and then an end-token with the tagname of "head1".
+
+=item $token->tagname(I<somestring>)
+
+This changes the tagname for this end-token object.
+You probably won't need to do this.
+
+=item $token->tag(...)
+
+A shortcut for $token->tagname(...)
+
+=item $token->is_tag(I<somestring>) or $token->is_tagname(I<somestring>)
+
+These are shortcuts for C<< $token->tag() eq I<somestring> >>
+
+=back
+
+You're unlikely to ever need to construct an object of this class for
+yourself, but if you want to, call
+C<<
+Pod::Simple::PullParserEndToken->new( I<tagname> )
+>>
=head1 SEE ALSO
-L<Pod::Simple>
+L<Pod::Simple::PullParserToken>, L<Pod::Simple>, L<Pod::Simple::Subclassing>
=head1 COPYRIGHT AND DISCLAIMERS
View
69 lib/Pod/Simple/PullParserStartToken.pm
@@ -15,6 +15,10 @@ sub new { # Class->new(tagname, optional_attrhash);
sub tagname { (@_ == 2) ? ($_[0][1] = $_[1]) : $_[0][1] }
sub tag { shift->tagname(@_) }
+sub is_tagname { $_[0][1] eq $_[1] }
+sub is_tag { shift->is_tagname(@_) }
+
+
sub attr_hash { $_[0][2] ||= {} }
sub attr {
@@ -37,22 +41,75 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::PullParserStartToken -- start-tokens from Pod::Simple::PullParser
=head1 SYNOPSIS
- TODO
+(See L<Pod::Simple::PullParser>)
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+When you do $parser->get_token on a L<Pod::Simple::PullParser> object, you might
+get an object of this class.
+
+This is a subclass of L<Pod::Simple::PullParserToken> and inherits all its methods,
+and adds these methods:
+
+=over
+
+=item $token->tagname
+
+This returns the tagname for this start-token object.
+For example, parsing a "=head1 ..." line will give you
+a start-token with the tagname of "head1", token(s) for its
+content, and then an end-token with the tagname of "head1".
+
+=item $token->tagname(I<somestring>)
+
+This changes the tagname for this start-token object.
+You probably won't need
+to do this.
+
+=item $token->tag(...)
+
+A shortcut for $token->tagname(...)
+
+=item $token->is_tag(I<somestring>) or $token->is_tagname(I<somestring>)
+
+These are shortcuts for C<< $token->tag() eq I<somestring> >>
+
+=item $token->attr(I<attrname>)
+
+This returns the value of the I<attrname> attribute for this start-token
+object, or undef.
+
+For example, parsing a LZ<><Foo/"Bar"> link will produce a start-token
+with a "to" attribute with the value "Foo", a "type" attribute with the
+value "pod", and a "section" attribute with the value "Bar".
+
+=item $token->attr(I<attrname>, I<newvalue>)
+
+This sets the I<attrname> attribute for this start-token object to
+I<newvalue>. You probably won't need to do this.
+
+=item $token->attr_hash
+
+This returns the hashref that is the attribute set for this start-token.
+This is useful if (for example) you want to ask what all the attributes
+are -- you can just do C<< keys %{$token->attr_hash} >>
+
+=back
+
-TODO
+You're unlikely to ever need to construct an object of this class for
+yourself, but if you want to, call
+C<<
+Pod::Simple::PullParserStartToken->new( I<tagname>, I<attrhash> )
+>>
=head1 SEE ALSO
-L<Pod::Simple>
+L<Pod::Simple::PullParserToken>, L<Pod::Simple>, L<Pod::Simple::Subclassing>
=head1 COPYRIGHT AND DISCLAIMERS
View
55 lib/Pod/Simple/PullParserTextToken.pm
@@ -22,22 +22,65 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::PullParserTextToken -- text-tokens from Pod::Simple::PullParser
=head1 SYNOPSIS
- TODO
+(See L<Pod::Simple::PullParser>)
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+When you do $parser->get_token on a L<Pod::Simple::PullParser>, you might
+get an object of this class.
-TODO
+This is a subclass of L<Pod::Simple::PullParserToken> and inherits all its methods,
+and adds these methods:
+
+=over
+
+=item $token->text
+
+This returns the text that this token holds. For example, parsing
+CZ<><foo> will return a C start-token, a text-token, and a C end-token. And
+if you want to get the "foo" out of the text-token, call C<< $token->text >>
+
+=item $token->text(I<somestring>)
+
+This changes the string that this token holds. You probably won't need
+to do this.
+
+=item $token->text_r()
+
+This returns a scalar reference to the string that this token holds.
+This can be useful if you don't want to memory-copy the potentially
+large text value (well, as large as a paragraph or a verbatim block)
+as calling $token->text would do.
+
+Or, if you want to alter the value, you can even do things like this:
+
+ for ( ${ $token->text_r } ) { # Aliases it with $_ !!
+
+ s/ The / the /g; # just for example
+
+ if( 'A' eq chr(65) ) { # (if in an ASCII world)
+ tr/\xA0/ /;
+ tr/\xAD//d;
+ }
+
+ ...or however you want to alter the value...
+ }
+
+=back
+
+You're unlikely to ever need to construct an object of this class for
+yourself, but if you want to, call
+C<<
+Pod::Simple::PullParserTextToken->new( I<text> )
+>>
=head1 SEE ALSO
-L<Pod::Simple>
+L<Pod::Simple::PullParserToken>, L<Pod::Simple>, L<Pod::Simple::Subclassing>
=head1 COPYRIGHT AND DISCLAIMERS
View
72 lib/Pod/Simple/PullParserToken.pm
@@ -44,22 +44,82 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::PullParserToken -- tokens from Pod::Simple::PullParser
=head1 SYNOPSIS
- TODO
+Given a $parser that's an object of class Pod::Simple::PullParser
+(or a subclass)...
+
+ while(my $token = $parser->get_token) {
+ $DEBUG and print "Token: ", $token->dump, "\n";
+ if($token->is_start) {
+ ...access $token->tagname, $token->attr, etc...
+
+ } elsif($token->is_text) {
+ ...access $token->text, $token->text_r, etc...
+
+ } elsif($token->is_end) {
+ ...access $token->tagname...
+
+ }
+ }
+
+(Also see L<Pod::Simple::PullParser>)
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+When you do $parser->get_token on a L<Pod::Simple::PullParser>, you should
+get an object of a subclass of Pod::Simple::PullParserToken.
+
+Subclasses will add methods, and will also inherit these methods:
+
+=over
+
+=item $token->type
+
+This returns the type of the token. This will be either the string
+"start", the string "text", or the string "end".
+
+Once you know what the type of an object is, you then know what
+subclass it belongs to, and therefore what methods it supports.
+
+Yes, you could probably do the same thing with code like
+$token->isa('Pod::Simple::PullParserEndToken'), but that's not so
+pretty as using just $token->type, or even the following shortcuts:
+
+=item $token->is_start
+
+This is a shortcut for C<< $token->type() eq "start" >>
-TODO
+=item $token->is_text
+
+This is a shortcut for C<< $token->type() eq "text" >>
+
+=item $token->is_end
+
+This is a shortcut for C<< $token->type() eq "end" >>
+
+=item $token->dump
+
+This returns a handy stringified value of this object. This
+is useful for debugging, as in:
+
+ while(my $token = $parser->get_token) {
+ $DEBUG and print "Token: ", $token->dump, "\n";
+ ...
+ }
+
+=back
=head1 SEE ALSO
-L<Pod::Simple>
+My subclasses:
+L<Pod::Simple::PullParserStartToken>,
+L<Pod::Simple::PullParserTextToken>, and
+L<Pod::Simple::PullParserEndToken>.
+
+L<Pod::Simple::PullParser> and L<Pod::Simple>
=head1 COPYRIGHT AND DISCLAIMERS
View
141 lib/Pod/Simple/RTF.pm
@@ -10,7 +10,7 @@ package Pod::Simple::RTF;
use strict;
use vars qw($VERSION @ISA %Escape $WRAP %Tagmap);
-$VERSION = '1.02';
+$VERSION = '1.03';
use Pod::Simple::PullParser ();
BEGIN {@ISA = ('Pod::Simple::PullParser')}
@@ -104,6 +104,14 @@ sub new {
$new->accept_codes(@_to_accept);
$new->accept_codes('VerbatimFormatted');
DEBUG > 2 and print "To accept: ", join(' ',@_to_accept), "\n";
+ $new->doc_lang(
+ ( $ENV{'RTFDEFLANG'} || '') =~ m/^(\d{1,10})$/s ? $1
+ : ($ENV{'RTFDEFLANG'} || '') =~ m/^0?x([a-fA-F0-9]{1,10})$/s ? hex($1)
+ # yes, tolerate hex!
+ : ($ENV{'RTFDEFLANG'} || '') =~ m/^([a-fA-F0-9]{4})$/s ? hex($1)
+ # yes, tolerate even more hex!
+ : '1033'
+ );
$new->head1_halfpoint_size(32);
$new->head2_halfpoint_size(28);
@@ -118,9 +126,8 @@ sub new {
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# TODO: document these
-
__PACKAGE__->_accessorize(
+ 'doc_lang',
'head1_halfpoint_size',
'head2_halfpoint_size',
'head3_halfpoint_size',
@@ -454,14 +461,14 @@ sub doc_start {
if $is_obviously_module_name;
return sprintf <<'END',
-\deflang1033\widowctrl
+\deflang%s\plain\lang%s\widowctrl
{\header\pard\qr\plain\f2\fs%s
%s
p.\chpgn\par}
\fs%s
END
-
+ ($self->doc_lang) x 2,
$self->header_halfpoint_size,
$title,
$self->normal_halfpoint_size,
@@ -471,7 +478,6 @@ END
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#-------------------------------------------------------------------------
-# TODO: escaping Unicode characters?
use integer;
sub rtf_esc {
my $x; # scratch
@@ -497,7 +503,11 @@ sub rtf_esc {
}
sub rtf_esc_codely {
- # Doesn't change "-" to hard-hyphen, nor apply computerese style
+ # Doesn't change "-" to hard-hyphen, nor apply computerese style-smarts.
+ # We don't want to change the "-" to hard-hyphen, because we want to
+ # be able to paste this into a file and run it without there being
+ # dire screaming about the mysterious hard-hyphen character (which
+ # looks just like a normal dash character).
my $x; # scratch
if(!defined wantarray) { # void context: alter in-place!
@@ -551,24 +561,113 @@ sub rtf_esc_codely {
__END__
-How do do a comment in rtf
+=head1 NAME
-{\*\qqqqqqqq
- I like cookies!!!!!
-}
+Pod::Simple::RTF -- format Pod as RTF
+
+=head1 SYNOPSIS
+
+ perl -MPod::Simple::RTF -e \
+ "exit Pod::Simple::RTF->filter(shift)->any_errata_seen" \
+ thingy.pod > thingy.rtf
+
+=head1 DESCRIPTION
+
+This class is a formatter that takes Pod and renders it as RTF, good for
+viewing/printing in MSWord, WordPad/write.exe, TextEdit, etc.
+
+This is a subclass of L<Pod::Simple> and inherits all its methods.
+
+=head1 FORMAT CONTROL ATTRIBUTES
+
+You can set these attributes on the parser object before you
+call C<parse_file> (or a similar method) on it:
+
+=over
+
+=item $parser->head1_halfpoint_size( I<halfpoint_integer> );
+
+=item $parser->head2_halfpoint_size( I<halfpoint_integer> );
+
+=item $parser->head3_halfpoint_size( I<halfpoint_integer> );
+
+=item $parser->head4_halfpoint_size( I<halfpoint_integer> );
+
+These methods set the size (in half-points, like 52 for 26-point)
+that these heading levels will appear as.
+
+=item $parser->codeblock_halfpoint_size( I<halfpoint_integer> );
+
+This method sets the size (in half-points, like 21 for 10.5-point)
+that codeblocks ("verbatim sections") will appear as.
+
+=item $parser->header_halfpoint_size( I<halfpoint_integer> );
+
+This method sets the size (in half-points, like 15 for 7.5-point)
+that the header on each page will appear in. The header
+is usually just "I<modulename> p. I<pagenumber>".
+
+=item $parser->normal_halfpoint_size( I<halfpoint_integer> );
+
+This method sets the size (in half-points, like 26 for 13-point)
+that normal paragraphic text will appear in.
+
+=item $parser->no_proofing_exemptions( I<true_or_false> );
+
+Set this value to true if you don't want the formatter to try
+putting a hidden code on all Perl symbols (as best as it can
+notice them) that labels them as being not in English, and
+so not worth spellchecking.
+
+=item $parser->doc_lang( I<microsoft_decimal_language_code> )
+
+This sets the language code to tag this document as being in. By
+default, it is currently the value of the environment variable
+C<RTFDEFLANG>, or if that's not set, then the value
+1033 (for US English).
+
+Setting this appropriately is useful if you want to use the RTF
+to spellcheck, and/or if you want it to hyphenate right.
+
+Here are some notable values:
+
+ 1033 US English
+ 2057 UK English
+ 3081 Australia English
+ 4105 Canada English
+ 1034 Spain Spanish
+ 2058 Mexico Spanish
+ 1031 Germany German
+ 1036 France French
+ 3084 Canada French
+ 1035 Finnish
+ 1044 Norwegian (Bokmal)
+ 2068 Norwegian (Nynorsk)
+
+=back
+
+If you are particularly interested in customizing this module's output
+even more, see the source and/or write to me.
+
+=head1 SEE ALSO
+
+L<Pod::Simple>, L<RTF::Writer>, L<RTF::Cookbook>, L<RTF::Document>,
+L<RTF::Generator>
+
+=head1 COPYRIGHT AND DISCLAIMERS
+
+Copyright (c) 2002 Sean M. Burke. All rights reserved.
-From the spec:
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
-Destinations added after the RTF Specification published in the March
-1987 Microsoft Systems Journal may be preceded by the control symbol \*.
-This control symbol identifies destinations whose related text should be
-ignored if the RTF reader does not recognize the destination.
-[...]
-If the \* control symbol precedes a control word, then it defines a
-destination group and was itself preceded by an opening brace ({). The
-RTF reader should discard all text up to and including the closing brace
-(}) that closes this group.
+This program is distributed in the hope that it will be useful, but
+without any warranty; without even the implied warranty of
+merchantability or fitness for a particular purpose.
+=head1 AUTHOR
+Sean M. Burke C<sburke@cpan.org>
+=cut
View
70 lib/Pod/Simple/SimpleTree.pm
@@ -25,7 +25,7 @@ sub _handle_element_start { # self, tagname, attrhash
push @{ $_[0]{'_currpos'}[0] }, $x; # insert in parent's child-list
unshift @{ $_[0]{'_currpos'} }, $x; # prefix to stack
} else {
- DEBUG and print " And oo, it getsto be root!\n";
+ DEBUG and print " And oo, it gets to be root!\n";
$_[0]{'_currpos'} = [ $_[0]{'root'} = $x ];
# first event! set to stack, and set as root.
}
@@ -60,28 +60,82 @@ sub _traverse_treelet_bit {
1;
__END__
-
-__END__
-
=head1 NAME
-TODO - TODO
+Pod::Simple::SimpleTree -- parse Pod into a simple parse tree
=head1 SYNOPSIS
- TODO
+ % cat ptest.pod
+
+ =head1 PIE
+
+ I like B<pie>!
+
+ % perl -MPod::Simple::SimpleTree -MData::Dumper -e \
+ "print Dumper(Pod::Simple::SimpleTree->new->parse_file(shift)->root)" \
+ ptest.pod
+
+ $VAR1 = [
+ 'Document',
+ { 'start_line' => 1 },
+ [
+ 'head1',
+ { 'start_line' => 1 },
+ 'PIE'
+ ],
+ [
+ 'Para',
+ { 'start_line' => 3 },
+ 'I like ',
+ [
+ 'B',
+ {},
+ 'pie'
+ ],
+ '!'
+ ]
+ ];
=head1 DESCRIPTION
-This class is for TODO.
+This class is of interest to people writing a Pod processor/formatter.
+
+This class takes Pod and parses it, returning a parse tree made just
+of arrayrefs, and hashrefs, and strings.
+
This is a subclass of L<Pod::Simple> and inherits all its methods.
-TODO
+This class is inspired by XML::Parser's "Tree" parsing-style, although
+it doesn't use exactly the same LoL format.
+
+=head1 METHODS
+
+At the end of the parse, call C<< $parser->root >> to get the
+tree's top node.
+
+=head1 Tree Contents
+
+Every element node in the parse tree is represented by an arrayref of
+the form: C<[ I<elementname>, \%attributes, I<...subnodes...> ]>.
+See the example tree dump in the Synopsis, above.
+
+Every text node in the tree is represented by a simple (non-ref)
+string scalar. So you can test C<ref($node)> to see whather you have
+an element node or just a text node.
+
+The top node in the tree is C<[ 'Document', \%attributes,
+I<...subnodes...> ]>
+
=head1 SEE ALSO
L<Pod::Simple>
+L<perllol>
+
+L<The "Tree" subsubsection in XML::Parser|XML::Parser/"Tree">
+
=head1 COPYRIGHT AND DISCLAIMERS
Copyright (c) 2002 Sean M. Burke. All rights reserved.
View
18 lib/Pod/Simple/Text.pm
@@ -6,7 +6,7 @@ use Carp ();
use Pod::Simple::Methody ();
use Pod::Simple ();
use vars qw( @ISA $VERSION $FREAKYMODE);
-$VERSION = '1.01';
+$VERSION = '1.02';
@ISA = ('Pod::Simple::Methody');
BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG)
? \&Pod::Simple::DEBUG
@@ -111,27 +111,27 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::Text -- format Pod as plaintext
=head1 SYNOPSIS
- TODO
-
perl -MPod::Simple::Text -e \
"exit Pod::Simple::Text->filter(shift)->any_errata_seen" \
thingy.pod
-
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+This class is a formatter that takes Pod and renders it as
+wrapped plaintext.
-TODO
+Its wrapping is done by L<Text::Wrap>, so you can change
+C<$Text::Wrap::columns> as you like.
+
+This is a subclass of L<Pod::Simple> and inherits all its methods.
=head1 SEE ALSO
-L<Pod::Simple>
+L<Pod::Simple>, L<Pod::Simple::TextContent>, L<Pod::Text>
=head1 COPYRIGHT AND DISCLAIMERS
View
11 lib/Pod/Simple/TextContent.pm
@@ -46,7 +46,7 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::TextContent -- get the text content of Pod
=head1 SYNOPSIS
@@ -58,14 +58,15 @@ TODO - TODO
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+This class is that parses Pod and dumps just the text content. It is
+mainly meant for use by the Pod::Simple test suite, but you may find
+some other use for it.
-TODO
+This is a subclass of L<Pod::Simple> and inherits all its methods.
=head1 SEE ALSO
-L<Pod::Simple>
+L<Pod::Simple>, L<Pod::Simple::Text>, L<Pod::Spell>
=head1 COPYRIGHT AND DISCLAIMERS
View
24 lib/Pod/Simple/XMLOutStream.pm
@@ -5,7 +5,7 @@ use strict;
use Carp ();
use Pod::Simple ();
use vars qw( $ATTR_PAD @ISA $VERSION $SORT_ATTRS);
-$VERSION = '1.01';
+$VERSION = '1.02';
BEGIN {
@ISA = ('Pod::Simple');
*DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG;
@@ -20,6 +20,7 @@ sub new {
my $self = shift;
my $new = $self->SUPER::new(@_);
$new->{'output_fh'} ||= *STDOUT{IO};
+ #$new->accept_codes('VerbatimFormatted');
return $new;
}
@@ -90,27 +91,32 @@ __END__
=head1 NAME
-TODO - TODO
+Pod::Simple::XMLOutStream -- turn Pod into XML
=head1 SYNOPSIS
- TODO
-
perl -MPod::Simple::XMLOutStream -e \
"exit Pod::Simple::XMLOutStream->filter(shift)->any_errata_seen" \
thingy.pod
-
=head1 DESCRIPTION
-This class is for TODO.
-This is a subclass of L<Pod::Simple> and inherits all its methods.
+Pod::Simple::XMLOutStream is a subclass of L<Pod::Simple> that parses
+Pod and turns it into XML.
+
+Pod::Simple::XMLOutStream inherits methods from
+L<Pod::Simple>.
-TODO
=head1 SEE ALSO
-L<Pod::Simple>
+L<Pod::Simple::DumpAsXML> is rather like this class; see its
+documentation for a discussion of the differences.
+
+L<Pod::Simple>, L<Pod::Simple::DumpAsXML>
+
+The older libraries L<Pod::PXML>, L<Pod::XML>, L<Pod::SAX>
+
=head1 COPYRIGHT AND DISCLAIMERS
Please sign in to comment.
Something went wrong with that request. Please try again.