mingw/html/lib/Pod/Select.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>podselect - extract selected sections of POD from input</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;podselect - extract selected sections of POD from input</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#requires">REQUIRES</a></li>
  25         <li><a href="#exports">EXPORTS</a></li>
  26         <li><a href="#description">DESCRIPTION</a></li>
  27         <li><a href="#section_specifications">SECTION SPECIFICATIONS</a></li>
  28         <li><a href="#range_specifications">RANGE SPECIFICATIONS</a></li>
  29         <li><a href="#object_methods">OBJECT METHODS</a></li>
  30         <li><a href="#curr_headings__"><strong>curr_headings()</strong></a></li>
  31         <li><a href="#select__"><strong>select()</strong></a></li>
  32         <li><a href="#add_selection__"><strong>add_selection()</strong></a></li>
  33         <li><a href="#clear_selections__"><strong>clear_selections()</strong></a></li>
  34         <li><a href="#match_section__"><strong>match_section()</strong></a></li>
  35         <li><a href="#is_selected__"><strong>is_selected()</strong></a></li>
  36         <li><a href="#exported_functions">EXPORTED FUNCTIONS</a></li>
  37         <li><a href="#podselect__"><strong>podselect()</strong></a></li>
  38         <li><a href="#private_methods_and_data">PRIVATE METHODS AND DATA</a></li>
  39         <li><a href="#_compile_section_spec__"><strong>_compile_section_spec()</strong></a></li>
  40         <ul>
  41
  42                 <li><a href="#_self___section_headings_">$self-&gt;{_SECTION_HEADINGS}</a></li>
  43                 <li><a href="#_self___selected_sections_">$self-&gt;{_SELECTED_SECTIONS}</a></li>
  44         </ul>
  45
  46         <li><a href="#see_also">SEE ALSO</a></li>
  47         <li><a href="#author">AUTHOR</a></li>
  48 </ul>
  49 <!-- INDEX END -->
  50
  51 <hr />
  52 <p>
  53 </p>
  54 <h1><a name="name">NAME</a></h1>
  55 <p>Pod::Select, <code>podselect()</code> - extract selected sections of POD from input</p>
  56 <p>
  57 </p>
  58 <hr />
  59 <h1><a name="synopsis">SYNOPSIS</a></h1>
  60 <pre>
  61     use Pod::Select;</pre>
  62 <pre>
  63     ## Select all the POD sections for each file in @filelist
  64     ## and print the result on standard output.
  65     podselect(@filelist);</pre>
  66 <pre>
  67     ## Same as above, but write to tmp.out
  68     podselect({-output =&gt; &quot;tmp.out&quot;}, @filelist):</pre>
  69 <pre>
  70     ## Select from the given filelist, only those POD sections that are
  71     ## within a 1st level section named any of: NAME, SYNOPSIS, OPTIONS.
  72     podselect({-sections =&gt; [&quot;NAME|SYNOPSIS&quot;, &quot;OPTIONS&quot;]}, @filelist):</pre>
  73 <pre>
  74     ## Select the &quot;DESCRIPTION&quot; section of the PODs from STDIN and write
  75     ## the result to STDERR.
  76     podselect({-output =&gt; &quot;&gt;&amp;STDERR&quot;, -sections =&gt; [&quot;DESCRIPTION&quot;]}, \*STDIN);</pre>
  77 <p>or</p>
  78 <pre>
  79     use Pod::Select;</pre>
  80 <pre>
  81     ## Create a parser object for selecting POD sections from the input
  82     $parser = new Pod::Select();</pre>
  83 <pre>
  84     ## Select all the POD sections for each file in @filelist
  85     ## and print the result to tmp.out.
  86     $parser-&gt;parse_from_file(&quot;&lt;&amp;STDIN&quot;, &quot;tmp.out&quot;);</pre>
  87 <pre>
  88     ## Select from the given filelist, only those POD sections that are
  89     ## within a 1st level section named any of: NAME, SYNOPSIS, OPTIONS.
  90     $parser-&gt;select(&quot;NAME|SYNOPSIS&quot;, &quot;OPTIONS&quot;);
  91     for (@filelist) { $parser-&gt;parse_from_file($_); }</pre>
  92 <pre>
  93     ## Select the &quot;DESCRIPTION&quot; and &quot;SEE ALSO&quot; sections of the PODs from
  94     ## STDIN and write the result to STDERR.
  95     $parser-&gt;select(&quot;DESCRIPTION&quot;);
  96     $parser-&gt;add_selection(&quot;SEE ALSO&quot;);
  97     $parser-&gt;parse_from_filehandle(\*STDIN, \*STDERR);</pre>
  98 <p>
  99 </p>
 100 <hr />
 101 <h1><a name="requires">REQUIRES</a></h1>
 102 <p>perl5.005, Pod::Parser, Exporter, Carp</p>
 103 <p>
 104 </p>
 105 <hr />
 106 <h1><a name="exports">EXPORTS</a></h1>
 107 <p><code>podselect()</code></p>
 108 <p>
 109 </p>
 110 <hr />
 111 <h1><a name="description">DESCRIPTION</a></h1>
 112 <p><strong>podselect()</strong> is a function which will extract specified sections of
 113 pod documentation from an input stream. This ability is provided by the
 114 <strong>Pod::Select</strong> module which is a subclass of <strong>Pod::Parser</strong>.
 115 <strong>Pod::Select</strong> provides a method named <strong>select()</strong> to specify the set of
 116 POD sections to select for processing/printing. <strong>podselect()</strong> merely
 117 creates a <strong>Pod::Select</strong> object and then invokes the <strong>podselect()</strong>
 118 followed by <strong>parse_from_file()</strong>.</p>
 119 <p>
 120 </p>
 121 <hr />
 122 <h1><a name="section_specifications">SECTION SPECIFICATIONS</a></h1>
 123 <p><strong>podselect()</strong> and <strong>Pod::Select::select()</strong> may be given one or more
 124 ``section specifications'' to restrict the text processed to only the
 125 desired set of sections and their corresponding subsections.  A section
 126 specification is a string containing one or more Perl-style regular
 127 expressions separated by forward slashes (``/'').  If you need to use a
 128 forward slash literally within a section title you can escape it with a
 129 backslash (``\/'').</p>
 130 <p>The formal syntax of a section specification is:</p>
 131 <ul>
 132 <li>
 133 <p><em>head1-title-regex</em>/<em>head2-title-regex</em>/...</p>
 134 </li>
 135 </ul>
 136 <p>Any omitted or empty regular expressions will default to ``.*''.
 137 Please note that each regular expression given is implicitly
 138 anchored by adding ``^'' and ``$'' to the beginning and end.  Also, if a
 139 given regular expression starts with a ``!'' character, then the
 140 expression is <em>negated</em> (so <code>!foo</code> would match anything <em>except</em>
 141 <code>foo</code>).</p>
 142 <p>Some example section specifications follow.</p>
 143 <ul>
 144 <li>
 145 <p>Match the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_name"><code>NAME</code></a> and <code>SYNOPSIS</code> sections and all of their subsections:</p>
 146 <p><code>NAME|SYNOPSIS</code></p>
 147 </li>
 148 <li>
 149 <p>Match only the <code>Question</code> and <code>Answer</code> subsections of the <code>DESCRIPTION</code>
 150 section:</p>
 151 <p><code>DESCRIPTION/Question|Answer</code></p>
 152 </li>
 153 <li>
 154 <p>Match the <code>Comments</code> subsection of <em>all</em> sections:</p>
 155 <p><code>/Comments</code></p>
 156 </li>
 157 <li>
 158 <p>Match all subsections of <code>DESCRIPTION</code> <em>except</em> for <code>Comments</code>:</p>
 159 <p><code>DESCRIPTION/!Comments</code></p>
 160 </li>
 161 <li>
 162 <p>Match the <code>DESCRIPTION</code> section but do <em>not</em> match any of its subsections:</p>
 163 <p><code>DESCRIPTION/!.+</code></p>
 164 </li>
 165 <li>
 166 <p>Match all top level sections but none of their subsections:</p>
 167 <p><code>/!.+</code></p>
 168 </li>
 169 </ul>
 170 <p>
 171 </p>
 172 <hr />
 173 <h1><a name="object_methods">OBJECT METHODS</a></h1>
 174 <p>The following methods are provided in this module. Each one takes a
 175 reference to the object itself as an implicit first parameter.</p>
 176 <p>
 177 </p>
 178 <hr />
 179 <h1><a name="curr_headings__"><strong>curr_headings()</strong></a></h1>
 180 <pre>
 181             ($head1, $head2, $head3, ...) = $parser-&gt;curr_headings();
 182             $head1 = $parser-&gt;curr_headings(1);</pre>
 183 <p>This method returns a list of the currently active section headings and
 184 subheadings in the document being parsed. The list of headings returned
 185 corresponds to the most recently parsed paragraph of the input.</p>
 186 <p>If an argument is given, it must correspond to the desired section
 187 heading number, in which case only the specified section heading is
 188 returned. If there is no current section heading at the specified
 189 level, then <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned.</p>
 190 <p>
 191 </p>
 192 <hr />
 193 <h1><a name="select__"><strong>select()</strong></a></h1>
 194 <pre>
 195             $parser-&gt;select($section_spec1,$section_spec2,...);</pre>
 196 <p>This method is used to select the particular sections and subsections of
 197 POD documentation that are to be printed and/or processed. The existing
 198 set of selected sections is <em>replaced</em> with the given set of sections.
 199 See <strong>add_selection()</strong> for adding to the current set of selected
 200 sections.</p>
 201 <p>Each of the <code>$section_spec</code> arguments should be a section specification
 202 as described in <a href="#section_specifications">SECTION SPECIFICATIONS</a>.  The section specifications
 203 are parsed by this method and the resulting regular expressions are
 204 stored in the invoking object.</p>
 205 <p>If no <code>$section_spec</code> arguments are given, then the existing set of
 206 selected sections is cleared out (which means <code>all</code> sections will be
 207 processed).</p>
 208 <p>This method should <em>not</em> normally be overridden by subclasses.</p>
 209 <p>
 210 </p>
 211 <hr />
 212 <h1><a name="add_selection__"><strong>add_selection()</strong></a></h1>
 213 <pre>
 214             $parser-&gt;add_selection($section_spec1,$section_spec2,...);</pre>
 215 <p>This method is used to add to the currently selected sections and
 216 subsections of POD documentation that are to be printed and/or
 217 processed. See &lt;select()&gt; for replacing the currently selected sections.</p>
 218 <p>Each of the <code>$section_spec</code> arguments should be a section specification
 219 as described in <a href="#section_specifications">SECTION SPECIFICATIONS</a>. The section specifications
 220 are parsed by this method and the resulting regular expressions are
 221 stored in the invoking object.</p>
 222 <p>This method should <em>not</em> normally be overridden by subclasses.</p>
 223 <p>
 224 </p>
 225 <hr />
 226 <h1><a name="clear_selections__"><strong>clear_selections()</strong></a></h1>
 227 <pre>
 228             $parser-&gt;clear_selections();</pre>
 229 <p>This method takes no arguments, it has the exact same effect as invoking
 230 &lt;select()&gt; with no arguments.</p>
 231 <p>
 232 </p>
 233 <hr />
 234 <h1><a name="match_section__"><strong>match_section()</strong></a></h1>
 235 <pre>
 236             $boolean = $parser-&gt;match_section($heading1,$heading2,...);</pre>
 237 <p>Returns a value of true if the given section and subsection heading
 238 titles match any of the currently selected section specifications in
 239 effect from prior calls to <strong>select()</strong> and <strong>add_selection()</strong> (or if
 240 there are no explictly selected/deselected sections).</p>
 241 <p>The arguments <code>$heading1</code>, <code>$heading2</code>, etc. are the heading titles of
 242 the corresponding sections, subsections, etc. to try and match.  If
 243 <code>$headingN</code> is omitted then it defaults to the current corresponding
 244 section heading title in the input.</p>
 245 <p>This method should <em>not</em> normally be overridden by subclasses.</p>
 246 <p>
 247 </p>
 248 <hr />
 249 <h1><a name="is_selected__"><strong>is_selected()</strong></a></h1>
 250 <pre>
 251             $boolean = $parser-&gt;is_selected($paragraph);</pre>
 252 <p>This method is used to determine if the block of text given in
 253 <code>$paragraph</code> falls within the currently selected set of POD sections
 254 and subsections to be printed or processed. This method is also
 255 responsible for keeping track of the current input section and
 256 subsections. It is assumed that <code>$paragraph</code> is the most recently read
 257 (but not yet processed) input paragraph.</p>
 258 <p>The value returned will be true if the <code>$paragraph</code> and the rest of the
 259 text in the same section as <code>$paragraph</code> should be selected (included)
 260 for processing; otherwise a false value is returned.</p>
 261 <p>
 262 </p>
 263 <hr />
 264 <h1><a name="exported_functions">EXPORTED FUNCTIONS</a></h1>
 265 <p>The following functions are exported by this module. Please note that
 266 these are functions (not methods) and therefore <code>do not</code> take an
 267 implicit first argument.</p>
 268 <p>
 269 </p>
 270 <hr />
 271 <h1><a name="podselect__"><strong>podselect()</strong></a></h1>
 272 <pre>
 273             podselect(\%options,@filelist);</pre>
 274 <p><strong>podselect</strong> will print the raw (untranslated) POD paragraphs of all
 275 POD sections in the given input files specified by <code>@filelist</code>
 276 according to the given options.</p>
 277 <p>If any argument to <strong>podselect</strong> is a reference to a hash
 278 (associative array) then the values with the following keys are
 279 processed as follows:</p>
 280 <dl>
 281 <dt><strong><a name="item__2doutput"><strong>-output</strong></a></strong>
 282
 283 <dd>
 284 <p>A string corresponding to the desired output file (or ``&gt;&amp;STDOUT''
 285 or ``&gt;&amp;STDERR''). The default is to use standard output.</p>
 286 </dd>
 287 </li>
 288 <dt><strong><a name="item__2dsections"><strong>-sections</strong></a></strong>
 289
 290 <dd>
 291 <p>A reference to an array of sections specifications (as described in
 292 <a href="#section_specifications">SECTION SPECIFICATIONS</a>) which indicate the desired set of POD
 293 sections and subsections to be selected from input. If no section
 294 specifications are given, then all sections of the PODs are used.</p>
 295 </dd>
 296 </li>
 297 </dl>
 298 <p>All other arguments should correspond to the names of input files
 299 containing POD sections. A file name of ``-'' or ``&lt;&amp;STDIN'' will
 300 be interpeted to mean standard input (which is the default if no
 301 filenames are given).</p>
 302 <p>
 303 </p>
 304 <hr />
 305 <h1><a name="private_methods_and_data">PRIVATE METHODS AND DATA</a></h1>
 306 <p><strong>Pod::Select</strong> makes uses a number of internal methods and data fields
 307 which clients should not need to see or use. For the sake of avoiding
 308 name collisions with client data and methods, these methods and fields
 309 are briefly discussed here. Determined hackers may obtain further
 310 information about them by reading the <strong>Pod::Select</strong> source code.</p>
 311 <p>Private data fields are stored in the hash-object whose reference is
 312 returned by the <strong>new()</strong> constructor for this class. The names of all
 313 private methods and data-fields used by <strong>Pod::Select</strong> begin with a
 314 prefix of ``_'' and match the regular expression <code>/^_\w+$/</code>.</p>
 315 <p>
 316 </p>
 317 <hr />
 318 <h1><a name="see_also">SEE ALSO</a></h1>
 319 <p><a href="file://C|\msysgit\mingw\html/lib/Pod/Parser.html">the Pod::Parser manpage</a></p>
 320 <p>
 321 </p>
 322 <hr />
 323 <h1><a name="author">AUTHOR</a></h1>
 324 <p>Please report bugs using <a href="http://rt.cpan.org">http://rt.cpan.org</a>.</p>
 325 <p>Brad Appleton &lt;<a href="mailto:bradapp@enteract.com">bradapp@enteract.com</a>&gt;</p>
 326 <p>Based on code for <strong>pod2text</strong> written by
 327 Tom Christiansen &lt;<a href="mailto:tchrist@mox.perl.com">tchrist@mox.perl.com</a>&gt;</p>
 328 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 329 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 330 <big><strong><span class="block">&nbsp;podselect - extract selected sections of POD from input</span></strong></big>
 331 </td></tr>
 332 </table>
 333
 334 </body>
 335
 336 </html>