.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Parser 3pm" .TH Parser 3pm "2012-01-02" "perl v5.14.2" "User Contributed Perl Documentation" .\" 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" PDL::Pod::Parser \- base class for creating pod filters and translators .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& use PDL::Pod::Parser; \& package PDL::MyParser; \& @ISA = qw(PDL::Pod::Parser); \& \& sub new { \& ## constructor code ... \& } \& \& ## implementation of appropriate subclass methods ... \& \& package main; \& $parser = new PDL::MyParser; \& @ARGV = (\*(Aq\-\*(Aq) unless (@ARGV > 0); \& for (@ARGV) { \& $parser\->parse_from_file($_); \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBPDL::Pod::Parser\fR is an abstract base class for implementing filters and/or translators to parse pod documentation into other formats. It handles most of the difficulty of parsing the pod sections in a file and leaves it to the subclasses to override various methods to provide the actual translation. The other thing that \fBPDL::Pod::Parser\fR provides is the ability to process only selected sections of pod documentation from the input. .SS "\s-1SECTION\s0 \s-1SPECIFICATIONS\s0" .IX Subsection "SECTION SPECIFICATIONS" Certain methods and functions provided by \fBPDL::Pod::Parser\fR may be given one or more \*(L"section specifications\*(R" to restrict the text processed to only the desired set of sections and their corresponding subsections. A section specification is a string containing one or more Perl-style regular expressions separated by forward slashes (\*(L"/\*(R"). If you need to use a forward slash literally within a section title you can escape it with a backslash (\*(L"\e/\*(R"). .PP The formal syntax of a section specification is: .IP " \fIhead1\-title\-regexp\fR/\fIhead2\-title\-regexp\fR/..." 4 .IX Item " head1-title-regexp/head2-title-regexp/..." .PP Any omitted or empty regular expressions will default to \*(L".*\*(R". Please note that each regular expression given is implicitly anchored by adding \*(L"^\*(R" and \*(L"$\*(R" to the beginning and end. Also, if a given regular expression starts with a \*(L"!\*(R" character, then the expression is negated (so \f(CW\*(C`!foo\*(C'\fR would match anything \fIexcept\fR \&\f(CW\*(C`foo\*(C'\fR). .PP Some example section specifications follow. .ie n .IP " Match the ""NAME"" and ""SYNOPSIS"" sections and all of their subsections:" 4 .el .IP " Match the \f(CWNAME\fR and \f(CWSYNOPSIS\fR sections and all of their subsections:" 4 .IX Item " Match the NAME and SYNOPSIS sections and all of their subsections:" \&\f(CW\*(C`NAME|SYNOPSIS\*(C'\fR .ie n .IP " Match only the ""Question"" and ""Answer"" subsections of the ""DESCRIPTION"" section:" 4 .el .IP " Match only the \f(CWQuestion\fR and \f(CWAnswer\fR subsections of the \f(CWDESCRIPTION\fR section:" 4 .IX Item " Match only the Question and Answer subsections of the DESCRIPTION section:" \&\f(CW\*(C`DESCRIPTION/Question|Answer\*(C'\fR .ie n .IP " Match the ""Comments"" subsection of \fIall\fR sections:" 4 .el .IP " Match the \f(CWComments\fR subsection of \fIall\fR sections:" 4 .IX Item " Match the Comments subsection of all sections:" \&\f(CW\*(C`/Comments\*(C'\fR .ie n .IP " Match all subsections of ""DESCRIPTION"" \fIexcept\fR for ""Comments"":" 4 .el .IP " Match all subsections of \f(CWDESCRIPTION\fR \fIexcept\fR for \f(CWComments\fR:" 4 .IX Item " Match all subsections of DESCRIPTION except for Comments:" \&\f(CW\*(C`DESCRIPTION/!Comments\*(C'\fR .ie n .IP " Match the ""DESCRIPTION"" section but do \fInot\fR match any of its subsections:" 4 .el .IP " Match the \f(CWDESCRIPTION\fR section but do \fInot\fR match any of its subsections:" 4 .IX Item " Match the DESCRIPTION section but do not match any of its subsections:" \&\f(CW\*(C`DESCRIPTION/!.+\*(C'\fR .IP " Match all top level sections but none of their subsections:" 4 .IX Item " Match all top level sections but none of their subsections:" \&\f(CW\*(C`/!.+\*(C'\fR .SH "FUNCTIONS" .IX Header "FUNCTIONS" \&\fBPDL::Pod::Parser\fR provides the following functions (please note that these are functions and \fInot\fR methods, they do not take an object reference as an implicit first parameter): .SS "\fIversion()\fP" .IX Subsection "version()" Return the current version of this package. .SH "INSTANCE METHODS" .IX Header "INSTANCE METHODS" \&\fBPDL::Pod::Parser\fR provides several methods, some of which should be overridden by subclasses. They are as follows: .SS "\fInew()\fP" .IX Subsection "new()" This is the the constructor for the base class. You should only use it if you want to create an instance of a \fBPDL::Pod::Parser\fR instead of one of its subclasses. The constructor for this class and all of its subclasses should return a blessed reference to an associative array (hash). .SS "\fIinitialize()\fP" .IX Subsection "initialize()" This method performs any necessary base class initialization. It takes no arguments (other than the object instance of course). If subclasses override this method then they \fImust\fR be sure to invoke the superclass' \fB\f(BIinitialize()\fB\fR method. .ie n .SS "select($section_spec1, $section_spec2, ...)" .el .SS "select($section_spec1, \f(CW$section_spec2\fP, ...)" .IX Subsection "select($section_spec1, $section_spec2, ...)" This is the method that is used to select the particular sections and subsections of pod documentation that are to be printed and/or processed. If the \fIfirst\fR \fIargument\fR is the string \*(L"+\*(R", then the remaining section specifications are \fIadded\fR to the current list of selections; otherwise the given section specifications will \fIreplace\fR the current list of selections. .PP Each of the \f(CW$section_spec\fR arguments should be a section specification as described in \*(L"\s-1SECTION\s0 \s-1SPECIFICATIONS\s0\*(R". The section specifications are parsed by this method and the resulting regular expressions are stored in the array referenced by \&\f(CW\*(C`$self\->{SELECTED}\*(C'\fR (please see the description of this member variable in \*(L"\s-1INSTANCE\s0 \s-1DATA\s0\*(R"). .PP This method should \fInot\fR normally be overridden by subclasses. .ie n .SS "want_section($head1_title, $head2_title, ...)" .el .SS "want_section($head1_title, \f(CW$head2_title\fP, ...)" .IX Subsection "want_section($head1_title, $head2_title, ...)" Returns a value of true if the given section and subsection titles match any of the section specifications passed to the \fB\f(BIselect()\fB\fR method (or if no section specifications were given). Returns a value of false otherwise. If \f(CW$headN_title\fR is ommitted then it defaults to the current \&\f(CW\*(C`headN\*(C'\fR section title in the input. .PP This method should \fInot\fR normally be overridden by subclasses. .SS "\fIbegin_input()\fP" .IX Subsection "begin_input()" This method is invoked by \fB\f(BIparse_from_filehandle()\fB\fR immediately \fIbefore\fR processing input from a filehandle. The base class implementation does nothing but subclasses may override it to perform any per-file intializations. .SS "\fIend_input()\fP" .IX Subsection "end_input()" This method is invoked by \fB\f(BIparse_from_filehandle()\fB\fR immediately \fIafter\fR processing input from a filehandle. The base class implementation does nothing but subclasses may override it to perform any per-file cleanup actions. .SS "preprocess_line($text)" .IX Subsection "preprocess_line($text)" This methods should be overridden by subclasses that wish to perform any kind of preprocessing for each \fIline\fR of input (\fIbefore\fR it has been determined whether or not it is part of a pod paragraph). The parameter \&\f(CW$text\fR is the input line and the value returned should correspond to the new text to use in its place. If the empty string or an undefined value is returned then no further process will be performed for this line. If desired, this method can call the \fB\f(BIparse_paragraph()\fB\fR method directly with any preprocessed text and return an empty string (to indicate that no further processing is needed). .PP Please note that the \fB\f(BIpreprocess_line()\fB\fR method is invoked \fIbefore\fR the \fB\f(BIpreprocess_paragraph()\fB\fR method. After all (possibly preprocessed) lines in a paragraph have been assembled together and it has been determined that the paragraph is part of the pod documentation from one of the selected sections, then \fB\f(BIpreprocess_paragraph()\fB\fR is invoked. .PP The base class implementation of this method returns the given text. .SS "preprocess_paragraph($text)" .IX Subsection "preprocess_paragraph($text)" This method should be overridden by subclasses that wish to perform any kind of preprocessing for each block (paragraph) of pod documentation that appears in the input stream. The parameter \f(CW$text\fR is the pod paragraph from the input file and the value returned should correspond to the new text to use in its place. If the empty string is returned or an undefined value is returned, then the given \f(CW$text\fR is ignored (not processed). .PP This method is invoked by \fB\f(BIparse_paragraph()\fB\fR. After it returns, \&\fB\f(BIparse_paragraph()\fB\fR examines the current cutting state (which is stored in \f(CW\*(C`$self\->{CUTTING}\*(C'\fR). If it evaluates to false then input text (including the given \f(CW$text\fR) is cut (not processed) until the next pod directive is encountered. .PP Please note that the \fB\f(BIpreprocess_line()\fB\fR method is invoked \fIbefore\fR the \fB\f(BIpreprocess_paragraph()\fB\fR method. After all (possibly preprocessed) lines in a paragraph have been assembled together and it has been determined that the paragraph is part of the pod documentation from one of the selected sections, then \fB\f(BIpreprocess_paragraph()\fB\fR is invoked. .PP The base class implementation of this method returns the given text. .ie n .SS "parse_pragmas($cmd, $text, $sep)" .el .SS "parse_pragmas($cmd, \f(CW$text\fP, \f(CW$sep\fP)" .IX Subsection "parse_pragmas($cmd, $text, $sep)" This method is called when an \f(CW\*(C`=pod\*(C'\fR directive is encountered. When such a pod directive is seen in the input, this method is called and is passed the command name \f(CW$cmd\fR (which should be \*(L"pod\*(R") and the remainder of the text paragraph \f(CW$text\fR which appeared immediately after the command name. If desired, the text which separated the \f(CW\*(C`=pod\*(C'\fR directive from its corresponding text may be found in \f(CW$sep\fR. Each word in \f(CW$text\fR is examined to see if it is a pragma specification. Pragma specifications are of the form \f(CW\*(C`pragma_name=pragma_value\*(C'\fR. .PP Unless the given object is an instance of the \fBPDL::Pod::Parser\fR class, the base class implementation of this method will invoke the \fB\f(BIpragma()\fB\fR method for each pragma specification in \f(CW$text\fR. \fIIf and only if\fR the given object \fIis\fR an instance of the \fBPDL::Pod::Parser\fR class, the base class version of this method will simply reproduce the \f(CW\*(C`=pod\*(C'\fR command exactly as it appeared in the input. .PP Derived classes should \fInot\fR usually need to reimplement this method. .ie n .SS "pragma($pragma_name, $pragma_value)" .el .SS "pragma($pragma_name, \f(CW$pragma_value\fP)" .IX Subsection "pragma($pragma_name, $pragma_value)" This method is invoked for each pragma encountered inside an \f(CW\*(C`=pod\*(C'\fR paragraph (see the description of the \fB\f(BIparse_pragmas()\fB\fR method). The pragma name is passed in \f(CW$pragma_name\fR (which should always be lowercase) and the corresponding value is \f(CW$pragma_value\fR. .PP The base class implementation of this method does nothing. Derived class implementations of this method should be able to recognize at least the following pragmas and take any necessary actions when they are encountered: .IP "\fBfill=value\fR" 4 .IX Item "fill=value" The argument \fIvalue\fR should be one of \f(CW\*(C`on\*(C'\fR, \f(CW\*(C`off\*(C'\fR, or \f(CW\*(C`previous\*(C'\fR. Specifies that \*(L"filling-mode\*(R" should set to 1, 0, or its previous value (respectively). If \fIvalue\fR is omitted then the default is \f(CW\*(C`on\*(C'\fR. Derived classes may use this to decide whether or not to perform any filling (wrapping) of subsequent text. .IP "\fBstyle=value\fR" 4 .IX Item "style=value" The argument \fIvalue\fR should be one of \f(CW\*(C`bold\*(C'\fR, \f(CW\*(C`italic\*(C'\fR, \f(CW\*(C`code\*(C'\fR, \&\f(CW\*(C`plain\*(C'\fR, or \f(CW\*(C`previous\*(C'\fR. Specifies that the current default paragraph font should be set to \f(CW\*(C`bold\*(C'\fR, \f(CW\*(C`italic\*(C'\fR, \f(CW\*(C`code\*(C'\fR, the empty string \f(CW\*(C`\*(C'\fR, or its previous value (respectively). If \fIvalue\fR is omitted then the default is \f(CW\*(C`plain\*(C'\fR. Derived classes may use this to determine the default font style to use for subsequent text. .IP "\fBindent=value\fR" 4 .IX Item "indent=value" The argument \fIvalue\fR should be an integer value (with an optional sign). Specifies that the current indentation level should be reset to the given value. If a plus (minus) sign precedes the number then the indentation level should be incremented (decremented) by the given number. If only a plus or minus sign is given (without a number) then the current indentation level is incremented or decremented by some default amount (to be determined by subclasses). .PP The value returned will be 1 if the pragma name was recognized and 0 if it wasnt (in which case the pragma was ignored). .PP Derived classes should override this method if they wish to implement any pragmas. The base class implementation of this method does nothing but it does contain some commented-out code which subclasses may want to make use of when implementing pragmas. .ie n .SS "command($cmd, $text, $sep)" .el .SS "command($cmd, \f(CW$text\fP, \f(CW$sep\fP)" .IX Subsection "command($cmd, $text, $sep)" This method should be overridden by subclasses to take the appropriate action when a pod command paragraph (denoted by a line beginning with \&\*(L"=\*(R") is encountered. When such a pod directive is seen in the input, this method is called and is passed the command name \f(CW$cmd\fR and the remainder of the text paragraph \f(CW$text\fR which appears immediately after the command name. If desired, the text which separated the command from its corresponding text may be found in \f(CW$sep\fR. Note that this method is \fInot\fR called for \f(CW\*(C`=pod\*(C'\fR paragraphs. .PP The base class implementation of this method simply prints the raw pod command to the output filehandle and then invokes the \fB\f(BItextblock()\fB\fR method, passing it the \f(CW$text\fR parameter. .SS "verbatim($text)" .IX Subsection "verbatim($text)" This method may be overridden by subclasses to take the appropriate action when a block of verbatim text is encountered. It is passed the text block \f(CW$text\fR as a parameter. .PP The base class implementation of this method simply prints the textblock (unmodified) to the output filehandle. .SS "textblock($text)" .IX Subsection "textblock($text)" This method may be overridden by subclasses to take the appropriate action when a normal block of pod text is encountered (although the base class method will usually do what you want). It is passed the text block \&\f(CW$text\fR as a parameter. .PP In order to process interior sequences, subclasses implementations of this method will probably want invoke the \fB\f(BIinterpolate()\fB\fR method, passing it the text block \f(CW$text\fR as a parameter and then perform any desired processing upon the returned result. .PP The base class implementation of this method simply prints the text block as it occurred in the input stream). .ie n .SS "interior_sequence($seq_cmd, $seq_arg)" .el .SS "interior_sequence($seq_cmd, \f(CW$seq_arg\fP)" .IX Subsection "interior_sequence($seq_cmd, $seq_arg)" This method should be overridden by subclasses to take the appropriate action when an interior sequence is encountered. An interior sequence is an embedded command within a block of text which appears as a command name (usually a single uppercase character) followed immediately by a string of text which is enclosed in angle brackets. This method is passed the sequence command \f(CW$seq_cmd\fR and the corresponding text \&\f(CW$seq_arg\fR and is invoked by the \fB\f(BIinterpolate()\fB\fR method for each interior sequence that occurs in the string that it is passed. It should return the desired text string to be used in place of the interior sequence. .PP Subclass implementationss of this method may wish to examine the the array referenced by \f(CW\*(C`$self\->{SEQUENCES}\*(C'\fR which is a stack of all the interior sequences that are currently being processed (they may be nested). The current interior sequence (the one given by \f(CW\*(C`$seq_cmd<$seq_arg>\*(C'\fR) should always be at the top of this stack. .PP The base class implementation of the \fB\f(BIinterior_sequence()\fB\fR method simply returns the raw text of the of the interior sequence (as it occurred in the input) to the output filehandle. .ie n .SS "interpolate($text, $end_re)" .el .SS "interpolate($text, \f(CW$end_re\fP)" .IX Subsection "interpolate($text, $end_re)" This method will translate all text (including any embedded interior sequences) in the given text string \f(CW$text\fR and return the interpolated result. If a second argument is given, then it is taken to be a regular expression that indicates when to quit interpolating the string. Upon return, the \f(CW$text\fR parameter will have been modified to contain only the un-processed portion of the given string (which will \&\fInot\fR contain any text matched by \f(CW$end_re\fR). .PP This method should probably \fInot\fR be overridden by subclasses. It should be noted that this method invokes itself recursively to handle any nested interior sequences. .SS "parse_paragraph($text)" .IX Subsection "parse_paragraph($text)" This method takes the text of a pod paragraph to be processed and invokes the appropriate method (one of \fB\f(BIcommand()\fB\fR, \fB\f(BIverbatim()\fB\fR, or \fB\f(BItextblock()\fB\fR). .PP This method does \fInot\fR usually need to be overridden by subclasses. .ie n .SS "parse_from_filehandle($infilehandle, $outfilehandle)" .el .SS "parse_from_filehandle($infilehandle, \f(CW$outfilehandle\fP)" .IX Subsection "parse_from_filehandle($infilehandle, $outfilehandle)" This method takes a glob to a filehandle (which is assumed to already be opened for reading) and reads the entire input stream looking for blocks (paragraphs) of pod documentation to be processed. For each block of pod documentation encountered it will call the \fB\f(BIparse_paragraph()\fB\fR method. .PP If a second argument is given then it should be a filehandle glob where output should be sent (otherwise the default output filehandle is \&\f(CW\*(C`STDOUT\*(C'\fR). If no first argument is given the default input filehandle \&\f(CW\*(C`STDIN\*(C'\fR is used. .PP The input filehandle that is currently in use is stored in the member variable whose key is \*(L"\s-1INPUT\s0\*(R" (e.g. \f(CW\*(C`$self\->{INPUT}\*(C'\fR). .PP The output filehandle that is currently in use is stored in the member variable whose key is \*(L"\s-1OUTPUT\s0\*(R" (e.g. \f(CW\*(C`$self\->{OUTPUT}\*(C'\fR). .PP Input is read line-by-line and assembled into paragraphs (which are separated by lines containing nothing but whitespace). The current line number is stored in the member variable whose key is \*(L"\s-1LINE\s0\*(R" (e.g. \&\f(CW\*(C`$self\->{LINE}\*(C'\fR) and the current paragraph number is stored in the member variable whose key is \*(L"\s-1PARAGRAPH\s0\*(R" (e.g. \f(CW\*(C`$self\->{PARAGRAPH}\*(C'\fR). .PP This method does \fInot\fR usually need to be overridden by subclasses. .ie n .SS "parse_from_file($filename, $outfile)" .el .SS "parse_from_file($filename, \f(CW$outfile\fP)" .IX Subsection "parse_from_file($filename, $outfile)" This method takes a filename and does the following: .IP "\(bu" 4 opens the input and output files for reading (creating the appropriate filehandles) .IP "\(bu" 4 invokes the \fB\f(BIparse_from_filehandle()\fB\fR method passing it the corresponding input and output filehandles. .IP "\(bu" 4 closes the input and output files. .PP If the special input filename \*(L"\-\*(R" or \*(L"<&STDIN\*(R" is given then the \s-1STDIN\s0 filehandle is used for input (and no open or close is performed). If no input filename is specified then \*(L"\-\*(R" is implied. If a reference is passed instead of a filename then it is assumed to be a glob-style reference to a filehandle. .PP If a second argument is given then it should be the name of the desired output file. If the special output filename \*(L"\-\*(R" or \*(L">&STDOUT\*(R" is given then the \s-1STDOUT\s0 filehandle is used for output (and no open or close is performed). If the special output filename \*(L">&STDERR\*(R" is given then the \&\s-1STDERR\s0 filehandle is used for output (and no open or close is performed). If no output filename is specified then \*(L"\-\*(R" is implied. If a reference is passed instead of a filename then it is assumed to be a glob-style reference to a filehandle. .PP The name of the input file that is currently being read is stored in the member variable whose key is \*(L"\s-1INFILE\s0\*(R" (e.g. \f(CW\*(C`$self\->{INFILE}\*(C'\fR). .PP The name of the output file that is currently being written is stored in the member variable whose key is \*(L"\s-1OUTFILE\s0\*(R" (e.g. \f(CW\*(C`$self\->{OUTFILE}\*(C'\fR). .PP This method does \fInot\fR usually need to be overridden by subclasses. .SH "INSTANCE DATA" .IX Header "INSTANCE DATA" \&\fBPDL::Pod::Parser\fR uses the following data members for each of its instances (where \f(CW$self\fR is a reference to such an instance): .ie n .SS "$self\->{\s-1INPUT\s0}" .el .SS "\f(CW$self\fP\->{\s-1INPUT\s0}" .IX Subsection "$self->{INPUT}" The current input filehandle. .ie n .SS "$self\->{\s-1OUTPUT\s0}" .el .SS "\f(CW$self\fP\->{\s-1OUTPUT\s0}" .IX Subsection "$self->{OUTPUT}" The current output filehandle. .ie n .SS "$self\->{\s-1INFILE\s0}" .el .SS "\f(CW$self\fP\->{\s-1INFILE\s0}" .IX Subsection "$self->{INFILE}" The name of the current input file. .ie n .SS "$self\->{\s-1OUTFILE\s0}" .el .SS "\f(CW$self\fP\->{\s-1OUTFILE\s0}" .IX Subsection "$self->{OUTFILE}" The name of the current output file. .ie n .SS "$self\->{\s-1LINE\s0}" .el .SS "\f(CW$self\fP\->{\s-1LINE\s0}" .IX Subsection "$self->{LINE}" The current line number from the input stream. .ie n .SS "$self\->{\s-1PARAGRAPH\s0}" .el .SS "\f(CW$self\fP\->{\s-1PARAGRAPH\s0}" .IX Subsection "$self->{PARAGRAPH}" The current paragraph number from the input stream (which includes input paragraphs that are \fInot\fR part of the pod documentation). .ie n .SS "$self\->{\s-1HEADINGS\s0}" .el .SS "\f(CW$self\fP\->{\s-1HEADINGS\s0}" .IX Subsection "$self->{HEADINGS}" A reference to an array of the current section heading titles for each heading level (note that the first heading level title is at index 0). .ie n .SS "$self\->{\s-1SELECTED\s0}" .el .SS "\f(CW$self\fP\->{\s-1SELECTED\s0}" .IX Subsection "$self->{SELECTED}" A reference to an array of references to arrays. Each subarray is a list of anchored regular expressions (preceded by a \*(L"!\*(R" if the regexp is to be negated). The index of the expression in the subarray should correspond to the index of the heading title in \fB\f(CB$self\fB\->{\s-1HEADINGS\s0}\fR that it is to be matched against. .ie n .SS "$self\->{\s-1CUTTING\s0}" .el .SS "\f(CW$self\fP\->{\s-1CUTTING\s0}" .IX Subsection "$self->{CUTTING}" A boolean-valued scalar which evaluates to true if text from the input file is currently being \*(L"cut\*(R". .ie n .SS "$self\->{\s-1SEQUENCES\s0}" .el .SS "\f(CW$self\fP\->{\s-1SEQUENCES\s0}" .IX Subsection "$self->{SEQUENCES}" An array reference to the stack of interior sequence commands that are currently in the middle of being processed. .SH "NOTES" .IX Header "NOTES" To create a pod translator to translate pod documentation to some other format, you usually only need to create a subclass of \fBPDL::Pod::Parser\fR which overrides the base class implementation for the following methods: .IP "\(bu" 4 \&\fB\f(BIpragma()\fB\fR .IP "\(bu" 4 \&\fB\f(BIcommand()\fB\fR .IP "\(bu" 4 \&\fB\f(BIverbatim()\fB\fR .IP "\(bu" 4 \&\fB\f(BItextblock()\fB\fR .IP "\(bu" 4 \&\fB\f(BIinterior_sequence()\fB\fR .PP You may also want to implement the \fB\f(BIbegin_input()\fB\fR and \fB\f(BIend_input()\fB\fR methods for your subclass (to perform any needed per-file intialization or cleanup). .PP If you need to perform any preprocesssing of input before it is parsed you may want to implement one or both of the \fB\f(BIpreprocess_line()\fB\fR and/or \&\fB\f(BIpreprocess_paragraph()\fB\fR methods. .PP Also, don't forget to make sure your subclass constructor invokes the base class' \fB\f(BIinitialize()\fB\fR method. .PP Sometimes it may be necessary to make more than one pass over the input files. This isn't a problem as long as none of the input files correspond to \f(CW\*(C`STDIN\*(C'\fR. You can override either the \fB\f(BIparse_from_filehandle()\fB\fR method or the \fB\f(BIparse_from_file()\fB\fR method to make the first pass yourself to collect all the information you need and then invoke the base class method to do the rest of the standard processing. .PP Feel free to add any member data fields you need to keep track of things like current font, indentation, horizontal or vertical position, or whatever else you like. .PP For the most part, the \fBPDL::Pod::Parser\fR base class should be able to do most of the input parsing for you and leave you free to worry about how to intepret the commands and translate the result. .SH "AUTHOR" .IX Header "AUTHOR" Brad Appleton .PP Based on code for \fBPod::Text\fR written by Tom Christiansen