{ "content": [ { "type": "text", "text": "# Pod::Simple::PullParser (perldoc)\n\n**Summary:** Pod::Simple::PullParser -- a pull-parser interface to parsing Pod\n\n**Synopsis:** my $parser = SomePodProcessor->new;\n$parser->setsource( \"whatever.pod\" );\n$parser->run;\nOr:\nmy $parser = SomePodProcessor->new;\n$parser->setsource( $somefilehandleobject );\n$parser->run;\nOr:\nmy $parser = SomePodProcessor->new;\n$parser->setsource( \\$documentsource );\n$parser->run;\nOr:\nmy $parser = SomePodProcessor->new;\n$parser->setsource( \\@documentlines );\n$parser->run;\nAnd elsewhere:\nrequire 5;\npackage SomePodProcessor;\nuse strict;\nuse base qw(Pod::Simple::PullParser);\nsub run {\nmy $self = shift;\nToken:\nwhile(my $token = $self->gettoken) {\n...process each token...\n}\n}\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (37 lines)\n- **DESCRIPTION** (11 lines)\n- **METHODS** (110 lines)\n- **NOTE** (7 lines)\n- **SEE ALSO** (7 lines)\n- **SUPPORT** (10 lines)\n- **COPYRIGHT AND DISCLAIMERS** (8 lines)\n- **AUTHOR** (10 lines)\n\n## Full Content\n\n### NAME\n\nPod::Simple::PullParser -- a pull-parser interface to parsing Pod\n\n### SYNOPSIS\n\nmy $parser = SomePodProcessor->new;\n$parser->setsource( \"whatever.pod\" );\n$parser->run;\n\nOr:\n\nmy $parser = SomePodProcessor->new;\n$parser->setsource( $somefilehandleobject );\n$parser->run;\n\nOr:\n\nmy $parser = SomePodProcessor->new;\n$parser->setsource( \\$documentsource );\n$parser->run;\n\nOr:\n\nmy $parser = SomePodProcessor->new;\n$parser->setsource( \\@documentlines );\n$parser->run;\n\nAnd elsewhere:\n\nrequire 5;\npackage SomePodProcessor;\nuse strict;\nuse base qw(Pod::Simple::PullParser);\n\nsub run {\nmy $self = shift;\nToken:\nwhile(my $token = $self->gettoken) {\n...process each token...\n}\n}\n\n### DESCRIPTION\n\nThis class is for using Pod::Simple to build a Pod processor -- but one that uses an interface\nbased on a stream of token objects, instead of based on events.\n\nThis is a subclass of Pod::Simple and inherits all its methods.\n\nA subclass of Pod::Simple::PullParser should define a \"run\" method that calls \"$token =\n$parser->gettoken\" to pull tokens.\n\nSee the source for Pod::Simple::RTF for an example of a formatter that uses\nPod::Simple::PullParser.\n\n### METHODS\n\nmy $token = $parser->gettoken\nThis returns the next token object (which will be of a subclass of\nPod::Simple::PullParserToken), or undef if the parser-stream has hit the end of the\ndocument.\n\n$parser->ungettoken( $token )\n$parser->ungettoken( $token1, $token2, ... )\nThis restores the token object(s) to the front of the parser stream.\n\nThe source has to be set before you can parse anything. The lowest-level way is to call\n\"setsource\":\n\n$parser->setsource( $filename )\n$parser->setsource( $filehandleobject )\n$parser->setsource( \\$documentsource )\n$parser->setsource( \\@documentlines )\n\nOr you can call these methods, which Pod::Simple::PullParser has defined to work just like\nPod::Simple's same-named methods:\n\n$parser->parsefile(...)\n$parser->parsestringdocument(...)\n$parser->filter(...)\n$parser->parsefromfile(...)\n\nFor those to work, the Pod-processing subclass of Pod::Simple::PullParser has to have defined a\n$parser->run method -- so it is advised that all Pod::Simple::PullParser subclasses do so. See\nthe Synopsis above, or the source for Pod::Simple::RTF.\n\nAuthors of formatter subclasses might find these methods useful to call on a parser object that\nyou haven't started pulling tokens from yet:\n\nmy $titlestring = $parser->gettitle\nThis tries to get the title string out of $parser, by getting some tokens, and scanning them\nfor the title, and then ungetting them so that you can process the token-stream from the\nbeginning.\n\nFor example, suppose you have a document that starts out:\n\n=head1 NAME\n\nHoo::Boy::Wowza -- Stuff B yeah!\n\n$parser->gettitle on that document will return \"Hoo::Boy::Wowza -- Stuff wow yeah!\". If the\ndocument starts with:\n\n=head1 Name\n\nHoo::Boy::W00t -- Stuff B yeah!\n\nThen you'll need to pass the \"nocase\" option in order to recognize \"Name\":\n\n$parser->gettitle(nocase => 1);\n\nIn cases where gettitle can't find the title, it will return empty-string (\"\").\n\nmy $titlestring = $parser->getshorttitle\nThis is just like gettitle, except that it returns just the modulename, if the title seems\nto be of the form \"SomeModuleName -- description\".\n\nFor example, suppose you have a document that starts out:\n\n=head1 NAME\n\nHoo::Boy::Wowza -- Stuff B yeah!\n\nthen $parser->getshorttitle on that document will return \"Hoo::Boy::Wowza\".\n\nBut if the document starts out:\n\n=head1 NAME\n\nHooboy, stuff B yeah!\n\nthen $parser->getshorttitle on that document will return \"Hooboy, stuff wow yeah!\". If the\ndocument starts with:\n\n=head1 Name\n\nHoo::Boy::W00t -- Stuff B yeah!\n\nThen you'll need to pass the \"nocase\" option in order to recognize \"Name\":\n\n$parser->getshorttitle(nocase => 1);\n\nIf the title can't be found, then getshorttitle returns empty-string (\"\").\n\n$authorname = $parser->getauthor\nThis works like gettitle except that it returns the contents of the \"=head1\nAUTHOR\\n\\nParagraph...\\n\" section, assuming that that section isn't terribly long. To\nrecognize a \"=head1 Author\\n\\nParagraph\\n\" section, pass the \"nocase\" option:\n\n$parser->getauthor(nocase => 1);\n\n(This method tolerates \"AUTHORS\" instead of \"AUTHOR\" too.)\n\n$descriptionname = $parser->getdescription\nThis works like gettitle except that it returns the contents of the \"=head1\nDESCRIPTION\\n\\nParagraph...\\n\" section, assuming that that section isn't terribly long. To\nrecognize a \"=head1 Description\\n\\nParagraph\\n\" section, pass the \"nocase\" option:\n\n$parser->getdescription(nocase => 1);\n\n$versionblock = $parser->getversion\nThis works like gettitle except that it returns the contents of the \"=head1 VERSION\\n\\n[BIG\nBLOCK]\\n\" block. Note that this does NOT return the module's $VERSION!! To recognize a\n\"=head1 Version\\n\\n[BIG BLOCK]\\n\" section, pass the \"nocase\" option:\n\n$parser->getversion(nocase => 1);\n\n### NOTE\n\nYou don't actually *have* to define a \"run\" method. If you're writing a Pod-formatter class, you\nshould define a \"run\" just so that users can call \"parsefile\" etc, but you don't *have* to.\n\nAnd if you're not writing a formatter class, but are instead just writing a program that does\nsomething simple with a Pod::PullParser object (and not an object of a subclass), then there's\nno reason to bother subclassing to add a \"run\" method.\n\n### SEE ALSO\n\nPod::Simple\n\nPod::Simple::PullParserToken -- and its subclasses Pod::Simple::PullParserStartToken,\nPod::Simple::PullParserTextToken, and Pod::Simple::PullParserEndToken.\n\nHTML::TokeParser, which inspired this.\n\n### SUPPORT\n\nQuestions or discussion about POD and Pod::Simple should be sent to the pod-people@perl.org mail\nlist. Send an empty email to pod-people-subscribe@perl.org to subscribe.\n\nThis module is managed in an open GitHub repository, .\nFeel free to fork and contribute, or to clone and\nsend patches!\n\nPatches against Pod::Simple are welcome. Please send bug reports to\n.\n\n### COPYRIGHT AND DISCLAIMERS\n\nCopyright (c) 2002 Sean M. Burke.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nThis program is distributed in the hope that it will be useful, but without any warranty;\nwithout even the implied warranty of merchantability or fitness for a particular purpose.\n\n### AUTHOR\n\nPod::Simple was created by Sean M. Burke . But don't bother him, he's retired.\n\nPod::Simple is maintained by:\n\n* Allison Randal \"allison@perl.org\"\n\n* Hans Dieter Pearcey \"hdp@cpan.org\"\n\n* David E. Wheeler \"dwheeler@cpan.org\"\n\n" } ], "structuredContent": { "command": "Pod::Simple::PullParser", "section": "", "mode": "perldoc", "summary": "Pod::Simple::PullParser -- a pull-parser interface to parsing Pod", "synopsis": "my $parser = SomePodProcessor->new;\n$parser->setsource( \"whatever.pod\" );\n$parser->run;\nOr:\nmy $parser = SomePodProcessor->new;\n$parser->setsource( $somefilehandleobject );\n$parser->run;\nOr:\nmy $parser = SomePodProcessor->new;\n$parser->setsource( \\$documentsource );\n$parser->run;\nOr:\nmy $parser = SomePodProcessor->new;\n$parser->setsource( \\@documentlines );\n$parser->run;\nAnd elsewhere:\nrequire 5;\npackage SomePodProcessor;\nuse strict;\nuse base qw(Pod::Simple::PullParser);\nsub run {\nmy $self = shift;\nToken:\nwhile(my $token = $self->gettoken) {\n...process each token...\n}\n}", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 37, "subsections": [] }, { "name": "DESCRIPTION", "lines": 11, "subsections": [] }, { "name": "METHODS", "lines": 110, "subsections": [] }, { "name": "NOTE", "lines": 7, "subsections": [] }, { "name": "SEE ALSO", "lines": 7, "subsections": [] }, { "name": "SUPPORT", "lines": 10, "subsections": [] }, { "name": "COPYRIGHT AND DISCLAIMERS", "lines": 8, "subsections": [] }, { "name": "AUTHOR", "lines": 10, "subsections": [] } ], "sections": { "NAME": { "content": "Pod::Simple::PullParser -- a pull-parser interface to parsing Pod\n", "subsections": [] }, "SYNOPSIS": { "content": "my $parser = SomePodProcessor->new;\n$parser->setsource( \"whatever.pod\" );\n$parser->run;\n\nOr:\n\nmy $parser = SomePodProcessor->new;\n$parser->setsource( $somefilehandleobject );\n$parser->run;\n\nOr:\n\nmy $parser = SomePodProcessor->new;\n$parser->setsource( \\$documentsource );\n$parser->run;\n\nOr:\n\nmy $parser = SomePodProcessor->new;\n$parser->setsource( \\@documentlines );\n$parser->run;\n\nAnd elsewhere:\n\nrequire 5;\npackage SomePodProcessor;\nuse strict;\nuse base qw(Pod::Simple::PullParser);\n\nsub run {\nmy $self = shift;\nToken:\nwhile(my $token = $self->gettoken) {\n...process each token...\n}\n}\n", "subsections": [] }, "DESCRIPTION": { "content": "This class is for using Pod::Simple to build a Pod processor -- but one that uses an interface\nbased on a stream of token objects, instead of based on events.\n\nThis is a subclass of Pod::Simple and inherits all its methods.\n\nA subclass of Pod::Simple::PullParser should define a \"run\" method that calls \"$token =\n$parser->gettoken\" to pull tokens.\n\nSee the source for Pod::Simple::RTF for an example of a formatter that uses\nPod::Simple::PullParser.\n", "subsections": [] }, "METHODS": { "content": "my $token = $parser->gettoken\nThis returns the next token object (which will be of a subclass of\nPod::Simple::PullParserToken), or undef if the parser-stream has hit the end of the\ndocument.\n\n$parser->ungettoken( $token )\n$parser->ungettoken( $token1, $token2, ... )\nThis restores the token object(s) to the front of the parser stream.\n\nThe source has to be set before you can parse anything. The lowest-level way is to call\n\"setsource\":\n\n$parser->setsource( $filename )\n$parser->setsource( $filehandleobject )\n$parser->setsource( \\$documentsource )\n$parser->setsource( \\@documentlines )\n\nOr you can call these methods, which Pod::Simple::PullParser has defined to work just like\nPod::Simple's same-named methods:\n\n$parser->parsefile(...)\n$parser->parsestringdocument(...)\n$parser->filter(...)\n$parser->parsefromfile(...)\n\nFor those to work, the Pod-processing subclass of Pod::Simple::PullParser has to have defined a\n$parser->run method -- so it is advised that all Pod::Simple::PullParser subclasses do so. See\nthe Synopsis above, or the source for Pod::Simple::RTF.\n\nAuthors of formatter subclasses might find these methods useful to call on a parser object that\nyou haven't started pulling tokens from yet:\n\nmy $titlestring = $parser->gettitle\nThis tries to get the title string out of $parser, by getting some tokens, and scanning them\nfor the title, and then ungetting them so that you can process the token-stream from the\nbeginning.\n\nFor example, suppose you have a document that starts out:\n\n=head1 NAME\n\nHoo::Boy::Wowza -- Stuff B yeah!\n\n$parser->gettitle on that document will return \"Hoo::Boy::Wowza -- Stuff wow yeah!\". If the\ndocument starts with:\n\n=head1 Name\n\nHoo::Boy::W00t -- Stuff B yeah!\n\nThen you'll need to pass the \"nocase\" option in order to recognize \"Name\":\n\n$parser->gettitle(nocase => 1);\n\nIn cases where gettitle can't find the title, it will return empty-string (\"\").\n\nmy $titlestring = $parser->getshorttitle\nThis is just like gettitle, except that it returns just the modulename, if the title seems\nto be of the form \"SomeModuleName -- description\".\n\nFor example, suppose you have a document that starts out:\n\n=head1 NAME\n\nHoo::Boy::Wowza -- Stuff B yeah!\n\nthen $parser->getshorttitle on that document will return \"Hoo::Boy::Wowza\".\n\nBut if the document starts out:\n\n=head1 NAME\n\nHooboy, stuff B yeah!\n\nthen $parser->getshorttitle on that document will return \"Hooboy, stuff wow yeah!\". If the\ndocument starts with:\n\n=head1 Name\n\nHoo::Boy::W00t -- Stuff B yeah!\n\nThen you'll need to pass the \"nocase\" option in order to recognize \"Name\":\n\n$parser->getshorttitle(nocase => 1);\n\nIf the title can't be found, then getshorttitle returns empty-string (\"\").\n\n$authorname = $parser->getauthor\nThis works like gettitle except that it returns the contents of the \"=head1\nAUTHOR\\n\\nParagraph...\\n\" section, assuming that that section isn't terribly long. To\nrecognize a \"=head1 Author\\n\\nParagraph\\n\" section, pass the \"nocase\" option:\n\n$parser->getauthor(nocase => 1);\n\n(This method tolerates \"AUTHORS\" instead of \"AUTHOR\" too.)\n\n$descriptionname = $parser->getdescription\nThis works like gettitle except that it returns the contents of the \"=head1\nDESCRIPTION\\n\\nParagraph...\\n\" section, assuming that that section isn't terribly long. To\nrecognize a \"=head1 Description\\n\\nParagraph\\n\" section, pass the \"nocase\" option:\n\n$parser->getdescription(nocase => 1);\n\n$versionblock = $parser->getversion\nThis works like gettitle except that it returns the contents of the \"=head1 VERSION\\n\\n[BIG\nBLOCK]\\n\" block. Note that this does NOT return the module's $VERSION!! To recognize a\n\"=head1 Version\\n\\n[BIG BLOCK]\\n\" section, pass the \"nocase\" option:\n\n$parser->getversion(nocase => 1);\n", "subsections": [] }, "NOTE": { "content": "You don't actually *have* to define a \"run\" method. If you're writing a Pod-formatter class, you\nshould define a \"run\" just so that users can call \"parsefile\" etc, but you don't *have* to.\n\nAnd if you're not writing a formatter class, but are instead just writing a program that does\nsomething simple with a Pod::PullParser object (and not an object of a subclass), then there's\nno reason to bother subclassing to add a \"run\" method.\n", "subsections": [] }, "SEE ALSO": { "content": "Pod::Simple\n\nPod::Simple::PullParserToken -- and its subclasses Pod::Simple::PullParserStartToken,\nPod::Simple::PullParserTextToken, and Pod::Simple::PullParserEndToken.\n\nHTML::TokeParser, which inspired this.\n", "subsections": [] }, "SUPPORT": { "content": "Questions or discussion about POD and Pod::Simple should be sent to the pod-people@perl.org mail\nlist. Send an empty email to pod-people-subscribe@perl.org to subscribe.\n\nThis module is managed in an open GitHub repository, .\nFeel free to fork and contribute, or to clone and\nsend patches!\n\nPatches against Pod::Simple are welcome. Please send bug reports to\n.\n", "subsections": [] }, "COPYRIGHT AND DISCLAIMERS": { "content": "Copyright (c) 2002 Sean M. Burke.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nThis program is distributed in the hope that it will be useful, but without any warranty;\nwithout even the implied warranty of merchantability or fitness for a particular purpose.\n", "subsections": [] }, "AUTHOR": { "content": "Pod::Simple was created by Sean M. Burke . But don't bother him, he's retired.\n\nPod::Simple is maintained by:\n\n* Allison Randal \"allison@perl.org\"\n\n* Hans Dieter Pearcey \"hdp@cpan.org\"\n\n* David E. Wheeler \"dwheeler@cpan.org\"\n", "subsections": [] } } } }