D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
local
/
lp
/
sonarperl
/
man
/
man3
/
Filename :
Pod::Simple::PullParser.3
back
Copy
.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Pod::Simple::PullParser 3" .TH Pod::Simple::PullParser 3 2021-07-25 "perl v5.38.0" "Perl Programmers Reference Guide" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Pod::Simple::PullParser \-\- a pull\-parser interface to parsing Pod .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 3 \& my $parser = SomePodProcessor\->new; \& $parser\->set_source( "whatever.pod" ); \& $parser\->run; .Ve .PP Or: .PP .Vb 3 \& my $parser = SomePodProcessor\->new; \& $parser\->set_source( $some_filehandle_object ); \& $parser\->run; .Ve .PP Or: .PP .Vb 3 \& my $parser = SomePodProcessor\->new; \& $parser\->set_source( \e$document_source ); \& $parser\->run; .Ve .PP Or: .PP .Vb 3 \& my $parser = SomePodProcessor\->new; \& $parser\->set_source( \e@document_lines ); \& $parser\->run; .Ve .PP And elsewhere: .PP .Vb 4 \& 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... \& } \& } .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" 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. .PP This is a subclass of Pod::Simple and inherits all its methods. .PP A subclass of Pod::Simple::PullParser should define a \f(CW\*(C`run\*(C'\fR method that calls \f(CW\*(C`$token = $parser\->get_token\*(C'\fR to pull tokens. .PP See the source for Pod::Simple::RTF for an example of a formatter that uses Pod::Simple::PullParser. .SH METHODS .IX Header "METHODS" .ie n .IP "my $token = $parser\->get_token" 4 .el .IP "my \f(CW$token\fR = \f(CW$parser\fR\->get_token" 4 .IX Item "my $token = $parser->get_token" This returns the next token object (which will be of a subclass of Pod::Simple::PullParserToken), or undef if the parser-stream has hit the end of the document. .ie n .IP "$parser\->unget_token( $token )" 4 .el .IP "\f(CW$parser\fR\->unget_token( \f(CW$token\fR )" 4 .IX Item "$parser->unget_token( $token )" .PD 0 .ie n .IP "$parser\->unget_token( $token1, $token2, ... )" 4 .el .IP "\f(CW$parser\fR\->unget_token( \f(CW$token1\fR, \f(CW$token2\fR, ... )" 4 .IX Item "$parser->unget_token( $token1, $token2, ... )" .PD This restores the token object(s) to the front of the parser stream. .PP The source has to be set before you can parse anything. The lowest-level way is to call \f(CW\*(C`set_source\*(C'\fR: .ie n .IP "$parser\->set_source( $filename )" 4 .el .IP "\f(CW$parser\fR\->set_source( \f(CW$filename\fR )" 4 .IX Item "$parser->set_source( $filename )" .PD 0 .ie n .IP "$parser\->set_source( $filehandle_object )" 4 .el .IP "\f(CW$parser\fR\->set_source( \f(CW$filehandle_object\fR )" 4 .IX Item "$parser->set_source( $filehandle_object )" .ie n .IP "$parser\->set_source( \e$document_source )" 4 .el .IP "\f(CW$parser\fR\->set_source( \e$document_source )" 4 .IX Item "$parser->set_source( $document_source )" .ie n .IP "$parser\->set_source( \e@document_lines )" 4 .el .IP "\f(CW$parser\fR\->set_source( \e@document_lines )" 4 .IX Item "$parser->set_source( @document_lines )" .PD .PP Or you can call these methods, which Pod::Simple::PullParser has defined to work just like Pod::Simple's same-named methods: .ie n .IP $parser\->parse_file(...) 4 .el .IP \f(CW$parser\fR\->parse_file(...) 4 .IX Item "$parser->parse_file(...)" .PD 0 .ie n .IP $parser\->parse_string_document(...) 4 .el .IP \f(CW$parser\fR\->parse_string_document(...) 4 .IX Item "$parser->parse_string_document(...)" .ie n .IP $parser\->filter(...) 4 .el .IP \f(CW$parser\fR\->filter(...) 4 .IX Item "$parser->filter(...)" .ie n .IP $parser\->parse_from_file(...) 4 .el .IP \f(CW$parser\fR\->parse_from_file(...) 4 .IX Item "$parser->parse_from_file(...)" .PD .PP For those to work, the Pod-processing subclass of Pod::Simple::PullParser has to have defined a \f(CW$parser\fR\->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. .PP Authors of formatter subclasses might find these methods useful to call on a parser object that you haven't started pulling tokens from yet: .ie n .IP "my $title_string = $parser\->get_title" 4 .el .IP "my \f(CW$title_string\fR = \f(CW$parser\fR\->get_title" 4 .IX Item "my $title_string = $parser->get_title" This tries to get the title string out of \f(CW$parser\fR, 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. .Sp For example, suppose you have a document that starts out: .Sp .Vb 1 \& =head1 NAME \& \& Hoo::Boy::Wowza \-\- Stuff B<wow> yeah! .Ve .Sp \&\f(CW$parser\fR\->get_title on that document will return "Hoo::Boy::Wowza \-\- Stuff wow yeah!". If the document starts with: .Sp .Vb 1 \& =head1 Name \& \& Hoo::Boy::W00t \-\- Stuff B<w00t> yeah! .Ve .Sp Then you'll need to pass the \f(CW\*(C`nocase\*(C'\fR option in order to recognize "Name": .Sp .Vb 1 \& $parser\->get_title(nocase => 1); .Ve .Sp In cases where get_title can't find the title, it will return empty-string (""). .ie n .IP "my $title_string = $parser\->get_short_title" 4 .el .IP "my \f(CW$title_string\fR = \f(CW$parser\fR\->get_short_title" 4 .IX 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". .Sp For example, suppose you have a document that starts out: .Sp .Vb 1 \& =head1 NAME \& \& Hoo::Boy::Wowza \-\- Stuff B<wow> yeah! .Ve .Sp then \f(CW$parser\fR\->get_short_title on that document will return "Hoo::Boy::Wowza". .Sp But if the document starts out: .Sp .Vb 1 \& =head1 NAME \& \& Hooboy, stuff B<wow> yeah! .Ve .Sp then \f(CW$parser\fR\->get_short_title on that document will return "Hooboy, stuff wow yeah!". If the document starts with: .Sp .Vb 1 \& =head1 Name \& \& Hoo::Boy::W00t \-\- Stuff B<w00t> yeah! .Ve .Sp Then you'll need to pass the \f(CW\*(C`nocase\*(C'\fR option in order to recognize "Name": .Sp .Vb 1 \& $parser\->get_short_title(nocase => 1); .Ve .Sp If the title can't be found, then get_short_title returns empty-string (""). .ie n .IP "$author_name = $parser\->get_author" 4 .el .IP "\f(CW$author_name\fR = \f(CW$parser\fR\->get_author" 4 .IX Item "$author_name = $parser->get_author" This works like get_title except that it returns the contents of the "=head1 AUTHOR\en\enParagraph...\en" section, assuming that that section isn't terribly long. To recognize a "=head1 Author\en\enParagraph\en" section, pass the \f(CW\*(C`nocase\*(C'\fR option: .Sp .Vb 1 \& $parser\->get_author(nocase => 1); .Ve .Sp (This method tolerates "AUTHORS" instead of "AUTHOR" too.) .ie n .IP "$description_name = $parser\->get_description" 4 .el .IP "\f(CW$description_name\fR = \f(CW$parser\fR\->get_description" 4 .IX Item "$description_name = $parser->get_description" This works like get_title except that it returns the contents of the "=head1 DESCRIPTION\en\enParagraph...\en" section, assuming that that section isn't terribly long. To recognize a "=head1 Description\en\enParagraph\en" section, pass the \f(CW\*(C`nocase\*(C'\fR option: .Sp .Vb 1 \& $parser\->get_description(nocase => 1); .Ve .ie n .IP "$version_block = $parser\->get_version" 4 .el .IP "\f(CW$version_block\fR = \f(CW$parser\fR\->get_version" 4 .IX Item "$version_block = $parser->get_version" This works like get_title except that it returns the contents of the "=head1 VERSION\en\en[BIG BLOCK]\en" block. Note that this does NOT return the module's \f(CW$VERSION\fR!! To recognize a "=head1 Version\en\en[BIG BLOCK]\en" section, pass the \f(CW\*(C`nocase\*(C'\fR option: .Sp .Vb 1 \& $parser\->get_version(nocase => 1); .Ve .SH NOTE .IX Header "NOTE" You don't actually \fIhave\fR to define a \f(CW\*(C`run\*(C'\fR method. If you're writing a Pod-formatter class, you should define a \f(CW\*(C`run\*(C'\fR just so that users can call \f(CW\*(C`parse_file\*(C'\fR etc, but you don't \fIhave\fR to. .PP 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 \f(CW\*(C`run\*(C'\fR method. .SH "SEE ALSO" .IX Header "SEE ALSO" Pod::Simple .PP Pod::Simple::PullParserToken \-\- and its subclasses Pod::Simple::PullParserStartToken, Pod::Simple::PullParserTextToken, and Pod::Simple::PullParserEndToken. .PP HTML::TokeParser, which inspired this. .SH SUPPORT .IX Header "SUPPORT" Questions or discussion about POD and Pod::Simple should be sent to the pod\-people@perl.org mail list. Send an empty email to pod\-people\-subscribe@perl.org to subscribe. .PP This module is managed in an open GitHub repository, <https://github.com/perl\-pod/pod\-simple/>. Feel free to fork and contribute, or to clone <git://github.com/perl\-pod/pod\-simple.git> and send patches! .PP Patches against Pod::Simple are welcome. Please send bug reports to <bug\-pod\-simple@rt.cpan.org>. .SH "COPYRIGHT AND DISCLAIMERS" .IX Header "COPYRIGHT AND DISCLAIMERS" Copyright (c) 2002 Sean M. Burke. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP 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. .SH AUTHOR .IX Header "AUTHOR" Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. But don't bother him, he's retired. .PP Pod::Simple is maintained by: .IP \(bu 4 Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR .IP \(bu 4 Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR .IP \(bu 4 David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR