local-lib5/man/man3/Pod::Simple::PullParser.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Pod::Simple::PullParser 3"
 132 .TH Pod::Simple::PullParser 3 "2009-09-01" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Pod::Simple::PullParser \-\- a pull\-parser interface to parsing Pod
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 3
 138 \& my $parser = SomePodProcessor\->new;
 139 \& $parser\->set_source( "whatever.pod" );
 140 \& $parser\->run;
 141 .Ve
 142 .PP
 143 Or:
 144 .PP
 145 .Vb 3
 146 \& my $parser = SomePodProcessor\->new;
 147 \& $parser\->set_source( $some_filehandle_object );
 148 \& $parser\->run;
 149 .Ve
 150 .PP
 151 Or:
 152 .PP
 153 .Vb 3
 154 \& my $parser = SomePodProcessor\->new;
 155 \& $parser\->set_source( \e$document_source );
 156 \& $parser\->run;
 157 .Ve
 158 .PP
 159 Or:
 160 .PP
 161 .Vb 3
 162 \& my $parser = SomePodProcessor\->new;
 163 \& $parser\->set_source( \e@document_lines );
 164 \& $parser\->run;
 165 .Ve
 166 .PP
 167 And elsewhere:
 168 .PP
 169 .Vb 4
 170 \& require 5;
 171 \& package SomePodProcessor;
 172 \& use strict;
 173 \& use base qw(Pod::Simple::PullParser);
 174 .Ve
 175 .PP
 176 .Vb 7
 177 \& sub run {
 178 \&   my $self = shift;
 179 \&  Token:
 180 \&   while(my $token = $self\->get_token) {
 181 \&     ...process each token...
 182 \&   }
 183 \& }
 184 .Ve
 185 .SH "DESCRIPTION"
 186 .IX Header "DESCRIPTION"
 187 This class is for using Pod::Simple to build a Pod processor \*(-- but
 188 one that uses an interface based on a stream of token objects,
 189 instead of based on events.
 190 .PP
 191 This is a subclass of Pod::Simple and inherits all its methods.
 192 .PP
 193 A subclass of Pod::Simple::PullParser should define a \f(CW\*(C`run\*(C'\fR method
 194 that calls \f(CW\*(C`$token = $parser\->get_token\*(C'\fR to pull tokens.
 195 .PP
 196 See the source for Pod::Simple::RTF for an example of a formatter
 197 that uses Pod::Simple::PullParser.
 198 .SH "METHODS"
 199 .IX Header "METHODS"
 200 .ie n .IP "my $token\fR = \f(CW$parser\->get_token" 4
 201 .el .IP "my \f(CW$token\fR = \f(CW$parser\fR\->get_token" 4
 202 .IX Item "my $token = $parser->get_token"
 203 This returns the next token object (which will be of a subclass of
 204 Pod::Simple::PullParserToken), or undef if the parser-stream has hit
 205 the end of the document.
 206 .ie n .IP "$parser\->unget_token( $token )" 4
 207 .el .IP "$parser\->unget_token( \f(CW$token\fR )" 4
 208 .IX Item "$parser->unget_token( $token )"
 209 .PD 0
 210 .ie n .IP "$parser\->unget_token( $token1\fR, \f(CW$token2, ... )" 4
 211 .el .IP "$parser\->unget_token( \f(CW$token1\fR, \f(CW$token2\fR, ... )" 4
 212 .IX Item "$parser->unget_token( $token1, $token2, ... )"
 213 .PD
 214 This restores the token object(s) to the front of the parser stream.
 215 .PP
 216 The source has to be set before you can parse anything.  The lowest-level
 217 way is to call \f(CW\*(C`set_source\*(C'\fR:
 218 .ie n .IP "$parser\->set_source( $filename )" 4
 219 .el .IP "$parser\->set_source( \f(CW$filename\fR )" 4
 220 .IX Item "$parser->set_source( $filename )"
 221 .PD 0
 222 .ie n .IP "$parser\->set_source( $filehandle_object )" 4
 223 .el .IP "$parser\->set_source( \f(CW$filehandle_object\fR )" 4
 224 .IX Item "$parser->set_source( $filehandle_object )"
 225 .IP "$parser\->set_source( \e$document_source )" 4
 226 .IX Item "$parser->set_source( $document_source )"
 227 .IP "$parser\->set_source( \e@document_lines )" 4
 228 .IX Item "$parser->set_source( @document_lines )"
 229 .PD
 230 .PP
 231 Or you can call these methods, which Pod::Simple::PullParser has defined
 232 to work just like Pod::Simple's same-named methods:
 233 .IP "$parser\->parse_file(...)" 4
 234 .IX Item "$parser->parse_file(...)"
 235 .PD 0
 236 .IP "$parser\->parse_string_document(...)" 4
 237 .IX Item "$parser->parse_string_document(...)"
 238 .IP "$parser\->filter(...)" 4
 239 .IX Item "$parser->filter(...)"
 240 .IP "$parser\->parse_from_file(...)" 4
 241 .IX Item "$parser->parse_from_file(...)"
 242 .PD
 243 .PP
 244 For those to work, the Pod-processing subclass of
 245 Pod::Simple::PullParser has to have defined a \f(CW$parser\fR\->run method \*(--
 246 so it is advised that all Pod::Simple::PullParser subclasses do so.
 247 See the Synopsis above, or the source for Pod::Simple::RTF.
 248 .PP
 249 Authors of formatter subclasses might find these methods useful to
 250 call on a parser object that you haven't started pulling tokens
 251 from yet:
 252 .ie n .IP "my $title_string\fR = \f(CW$parser\->get_title" 4
 253 .el .IP "my \f(CW$title_string\fR = \f(CW$parser\fR\->get_title" 4
 254 .IX Item "my $title_string = $parser->get_title"
 255 This tries to get the title string out of \f(CW$parser\fR, by getting some tokens,
 256 and scanning them for the title, and then ungetting them so that you can
 257 process the token-stream from the beginning.
 258 .Sp
 259 For example, suppose you have a document that starts out:
 260 .Sp
 261 .Vb 1
 262 \&  =head1 NAME
 263 .Ve
 264 .Sp
 265 .Vb 1
 266 \&  Hoo::Boy::Wowza \-\- Stuff B<wow> yeah!
 267 .Ve
 268 .Sp
 269 $parser\->get_title on that document will return \*(L"Hoo::Boy::Wowza \*(--
 270 Stuff wow yeah!\*(R". If the document starts with:
 271 .Sp
 272 .Vb 1
 273 \&  =head1 Name
 274 .Ve
 275 .Sp
 276 .Vb 1
 277 \&  Hoo::Boy::W00t \-\- Stuff B<w00t> yeah!
 278 .Ve
 279 .Sp
 280 Then you'll need to pass the \f(CW\*(C`nocase\*(C'\fR option in order to recognize \*(L"Name\*(R":
 281 .Sp
 282 .Vb 1
 283 \&  $parser\->get_title(nocase => 1);
 284 .Ve
 285 .Sp
 286 In cases where get_title can't find the title, it will return empty-string
 287 ("").
 288 .ie n .IP "my $title_string\fR = \f(CW$parser\->get_short_title" 4
 289 .el .IP "my \f(CW$title_string\fR = \f(CW$parser\fR\->get_short_title" 4
 290 .IX Item "my $title_string = $parser->get_short_title"
 291 This is just like get_title, except that it returns just the modulename, if
 292 the title seems to be of the form \*(L"SomeModuleName \*(-- description\*(R".
 293 .Sp
 294 For example, suppose you have a document that starts out:
 295 .Sp
 296 .Vb 1
 297 \&  =head1 NAME
 298 .Ve
 299 .Sp
 300 .Vb 1
 301 \&  Hoo::Boy::Wowza \-\- Stuff B<wow> yeah!
 302 .Ve
 303 .Sp
 304 then \f(CW$parser\fR\->get_short_title on that document will return
 305 \&\*(L"Hoo::Boy::Wowza\*(R".
 306 .Sp
 307 But if the document starts out:
 308 .Sp
 309 .Vb 1
 310 \&  =head1 NAME
 311 .Ve
 312 .Sp
 313 .Vb 1
 314 \&  Hooboy, stuff B<wow> yeah!
 315 .Ve
 316 .Sp
 317 then \f(CW$parser\fR\->get_short_title on that document will return \*(L"Hooboy,
 318 stuff wow yeah!\*(R". If the document starts with:
 319 .Sp
 320 .Vb 1
 321 \&  =head1 Name
 322 .Ve
 323 .Sp
 324 .Vb 1
 325 \&  Hoo::Boy::W00t \-\- Stuff B<w00t> yeah!
 326 .Ve
 327 .Sp
 328 Then you'll need to pass the \f(CW\*(C`nocase\*(C'\fR option in order to recognize \*(L"Name\*(R":
 329 .Sp
 330 .Vb 1
 331 \&  $parser\->get_short_title(nocase => 1);
 332 .Ve
 333 .Sp
 334 If the title can't be found, then get_short_title returns empty-string
 335 ("").
 336 .ie n .IP "$author_name   = $parser\->get_author" 4
 337 .el .IP "$author_name   = \f(CW$parser\fR\->get_author" 4
 338 .IX Item "$author_name   = $parser->get_author"
 339 This works like get_title except that it returns the contents of the
 340 \&\*(L"=head1 AUTHOR\en\enParagraph...\en\*(R" section, assuming that that section
 341 isn't terribly long. To recognize a \*(L"=head1 Author\en\enParagraph\en\*(R"
 342 section, pass the \f(CW\*(C`nocase\*(C'\fR otpion:
 343 .Sp
 344 .Vb 1
 345 \&  $parser\->get_author(nocase => 1);
 346 .Ve
 347 .Sp
 348 (This method tolerates \*(L"\s-1AUTHORS\s0\*(R" instead of \*(L"\s-1AUTHOR\s0\*(R" too.)
 349 .ie n .IP "$description_name = $parser\->get_description" 4
 350 .el .IP "$description_name = \f(CW$parser\fR\->get_description" 4
 351 .IX Item "$description_name = $parser->get_description"
 352 This works like get_title except that it returns the contents of the
 353 \&\*(L"=head1 DESCRIPTION\en\enParagraph...\en\*(R" section, assuming that that section
 354 isn't terribly long. To recognize a \*(L"=head1 Description\en\enParagraph\en\*(R"
 355 section, pass the \f(CW\*(C`nocase\*(C'\fR otpion:
 356 .Sp
 357 .Vb 1
 358 \&  $parser\->get_description(nocase => 1);
 359 .Ve
 360 .ie n .IP "$version_block = $parser\->get_version" 4
 361 .el .IP "$version_block = \f(CW$parser\fR\->get_version" 4
 362 .IX Item "$version_block = $parser->get_version"
 363 This works like get_title except that it returns the contents of
 364 the \*(L"=head1 VERSION\en\en[\s-1BIG\s0 \s-1BLOCK\s0]\en\*(R" block.  Note that this does \s-1NOT\s0
 365 return the module's \f(CW$VERSION\fR!! To recognize a
 366 \&\*(L"=head1 Version\en\en[\s-1BIG\s0 \s-1BLOCK\s0]\en\*(R" section, pass the \f(CW\*(C`nocase\*(C'\fR otpion:
 367 .Sp
 368 .Vb 1
 369 \&  $parser\->get_version(nocase => 1);
 370 .Ve
 371 .SH "NOTE"
 372 .IX Header "NOTE"
 373 You don't actually \fIhave\fR to define a \f(CW\*(C`run\*(C'\fR method.  If you're
 374 writing a Pod-formatter class, you should define a \f(CW\*(C`run\*(C'\fR just so
 375 that users can call \f(CW\*(C`parse_file\*(C'\fR etc, but you don't \fIhave\fR to.
 376 .PP
 377 And if you're not writing a formatter class, but are instead just
 378 writing a program that does something simple with a Pod::PullParser
 379 object (and not an object of a subclass), then there's no reason to
 380 bother subclassing to add a \f(CW\*(C`run\*(C'\fR method.
 381 .SH "SEE ALSO"
 382 .IX Header "SEE ALSO"
 383 Pod::Simple
 384 .PP
 385 Pod::Simple::PullParserToken \*(-- and its subclasses
 386 Pod::Simple::PullParserStartToken,
 387 Pod::Simple::PullParserTextToken, and
 388 Pod::Simple::PullParserEndToken.
 389 .PP
 390 HTML::TokeParser, which inspired this.
 391 .SH "COPYRIGHT AND DISCLAIMERS"
 392 .IX Header "COPYRIGHT AND DISCLAIMERS"
 393 Copyright (c) 2002 Sean M. Burke.  All rights reserved.
 394 .PP
 395 This library is free software; you can redistribute it and/or modify it
 396 under the same terms as Perl itself.
 397 .PP
 398 This program is distributed in the hope that it will be useful, but
 399 without any warranty; without even the implied warranty of
 400 merchantability or fitness for a particular purpose.
 401 .SH "AUTHOR"
 402 .IX Header "AUTHOR"
 403 Sean M. Burke \f(CW\*(C`sburke@cpan.org\*(C'\fR