mingw/html/lib/Pod/InputObjects.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>Pod::InputObjects - objects representing POD input paragraphs, commands, etc.</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;Pod::InputObjects - objects representing POD input paragraphs, commands, etc.</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="#pod__inputsource"><strong>Pod::InputSource</strong></a></li>
  28         <ul>
  29
  30                 <li><a href="#new__"><strong>new()</strong></a></li>
  31                 <li><a href="#name__"><strong>name()</strong></a></li>
  32                 <li><a href="#handle__"><strong>handle()</strong></a></li>
  33                 <li><a href="#was_cutting__"><strong>was_cutting()</strong></a></li>
  34         </ul>
  35
  36         <li><a href="#pod__paragraph"><strong>Pod::Paragraph</strong></a></li>
  37         <ul>
  38
  39                 <li><a href="#pod__paragraph_new__">Pod::Paragraph-&gt;<strong>new()</strong></a></li>
  40                 <li><a href="#_pod_para_cmd_name__">$pod_para-&gt;<strong>cmd_name()</strong></a></li>
  41                 <li><a href="#_pod_para_text__">$pod_para-&gt;<strong>text()</strong></a></li>
  42                 <li><a href="#_pod_para_raw_text__">$pod_para-&gt;<strong>raw_text()</strong></a></li>
  43                 <li><a href="#_pod_para_cmd_prefix__">$pod_para-&gt;<strong>cmd_prefix()</strong></a></li>
  44                 <li><a href="#_pod_para_cmd_separator__">$pod_para-&gt;<strong>cmd_separator()</strong></a></li>
  45                 <li><a href="#_pod_para_parse_tree__">$pod_para-&gt;<strong>parse_tree()</strong></a></li>
  46                 <li><a href="#_pod_para_file_line__">$pod_para-&gt;<strong>file_line()</strong></a></li>
  47         </ul>
  48
  49         <li><a href="#pod__interiorsequence"><strong>Pod::InteriorSequence</strong></a></li>
  50         <ul>
  51
  52                 <li><a href="#pod__interiorsequence_new__">Pod::InteriorSequence-&gt;<strong>new()</strong></a></li>
  53                 <li><a href="#_pod_seq_cmd_name__">$pod_seq-&gt;<strong>cmd_name()</strong></a></li>
  54                 <li><a href="#_pod_seq_prepend__">$pod_seq-&gt;<strong>prepend()</strong></a></li>
  55                 <li><a href="#_pod_seq_append__">$pod_seq-&gt;<strong>append()</strong></a></li>
  56                 <li><a href="#_pod_seq_nested__">$pod_seq-&gt;<strong>nested()</strong></a></li>
  57                 <li><a href="#_pod_seq_raw_text__">$pod_seq-&gt;<strong>raw_text()</strong></a></li>
  58                 <li><a href="#_pod_seq_left_delimiter__">$pod_seq-&gt;<strong>left_delimiter()</strong></a></li>
  59                 <li><a href="#_pod_seq_right_delimiter__">$pod_seq-&gt;<strong>right_delimiter()</strong></a></li>
  60                 <li><a href="#_pod_seq_parse_tree__">$pod_seq-&gt;<strong>parse_tree()</strong></a></li>
  61                 <li><a href="#_pod_seq_file_line__">$pod_seq-&gt;<strong>file_line()</strong></a></li>
  62                 <li><a href="#pod__interiorsequence__destroy__">Pod::InteriorSequence::<strong>DESTROY()</strong></a></li>
  63         </ul>
  64
  65         <li><a href="#pod__parsetree"><strong>Pod::ParseTree</strong></a></li>
  66         <ul>
  67
  68                 <li><a href="#pod__parsetree_new__">Pod::ParseTree-&gt;<strong>new()</strong></a></li>
  69                 <li><a href="#_ptree_top__">$ptree-&gt;<strong>top()</strong></a></li>
  70                 <li><a href="#_ptree_children__">$ptree-&gt;<strong>children()</strong></a></li>
  71                 <li><a href="#_ptree_prepend__">$ptree-&gt;<strong>prepend()</strong></a></li>
  72                 <li><a href="#_ptree_append__">$ptree-&gt;<strong>append()</strong></a></li>
  73                 <li><a href="#_ptree_raw_text__">$ptree-&gt;<strong>raw_text()</strong></a></li>
  74                 <li><a href="#pod__parsetree__destroy__">Pod::ParseTree::<strong>DESTROY()</strong></a></li>
  75         </ul>
  76
  77         <li><a href="#see_also">SEE ALSO</a></li>
  78         <li><a href="#author">AUTHOR</a></li>
  79 </ul>
  80 <!-- INDEX END -->
  81
  82 <hr />
  83 <p>
  84 </p>
  85 <h1><a name="name">NAME</a></h1>
  86 <p>Pod::InputObjects - objects representing POD input paragraphs, commands, etc.</p>
  87 <p>
  88 </p>
  89 <hr />
  90 <h1><a name="synopsis">SYNOPSIS</a></h1>
  91 <pre>
  92     use Pod::InputObjects;</pre>
  93 <p>
  94 </p>
  95 <hr />
  96 <h1><a name="requires">REQUIRES</a></h1>
  97 <p>perl5.004, Carp</p>
  98 <p>
  99 </p>
 100 <hr />
 101 <h1><a name="exports">EXPORTS</a></h1>
 102 <p>Nothing.</p>
 103 <p>
 104 </p>
 105 <hr />
 106 <h1><a name="description">DESCRIPTION</a></h1>
 107 <p>This module defines some basic input objects used by <strong>Pod::Parser</strong> when
 108 reading and parsing POD text from an input source. The following objects
 109 are defined:</p>
 110 <dl>
 111 <dt><strong><a name="item_package_pod_3a_3aparagraph">package <strong>Pod::Paragraph</strong></a></strong>
 112
 113 <dd>
 114 <p>An object corresponding to a paragraph of POD input text. It may be a
 115 plain paragraph, a verbatim paragraph, or a command paragraph (see
 116 <a href="file://C|\msysgit\mingw\html/pod/perlpod.html">the perlpod manpage</a>).</p>
 117 </dd>
 118 </li>
 119 <dt><strong><a name="item_package_pod_3a_3ainteriorsequence">package <strong>Pod::InteriorSequence</strong></a></strong>
 120
 121 <dd>
 122 <p>An object corresponding to an interior sequence command from the POD
 123 input text (see <a href="file://C|\msysgit\mingw\html/pod/perlpod.html">the perlpod manpage</a>).</p>
 124 </dd>
 125 </li>
 126 <dt><strong><a name="item_package_pod_3a_3aparsetree">package <strong>Pod::ParseTree</strong></a></strong>
 127
 128 <dd>
 129 <p>An object corresponding to a tree of parsed POD text. Each ``node'' in
 130 a parse-tree (or <em>ptree</em>) is either a text-string or a reference to
 131 a <strong>Pod::InteriorSequence</strong> object. The nodes appear in the parse-tree
 132 in the order in which they were parsed from left-to-right.</p>
 133 </dd>
 134 </li>
 135 </dl>
 136 <p>Each of these input objects are described in further detail in the
 137 sections which follow.</p>
 138 <p>
 139 </p>
 140 <hr />
 141 <h1><a name="pod__paragraph"><strong>Pod::Paragraph</strong></a></h1>
 142 <p>An object representing a paragraph of POD input text.
 143 It has the following methods/attributes:</p>
 144 <p>
 145 </p>
 146 <h2><a name="pod__paragraph_new__">Pod::Paragraph-&gt;<strong>new()</strong></a></h2>
 147 <pre>
 148         my $pod_para1 = Pod::Paragraph-&gt;new(-text =&gt; $text);
 149         my $pod_para2 = Pod::Paragraph-&gt;new(-name =&gt; $cmd,
 150                                             -text =&gt; $text);
 151         my $pod_para3 = new Pod::Paragraph(-text =&gt; $text);
 152         my $pod_para4 = new Pod::Paragraph(-name =&gt; $cmd,
 153                                            -text =&gt; $text);
 154         my $pod_para5 = Pod::Paragraph-&gt;new(-name =&gt; $cmd,
 155                                             -text =&gt; $text,
 156                                             -file =&gt; $filename,
 157                                             -line =&gt; $line_number);</pre>
 158 <p>This is a class method that constructs a <code>Pod::Paragraph</code> object and
 159 returns a reference to the new paragraph object. It may be given one or
 160 two keyword arguments. The <code>-text</code> keyword indicates the corresponding
 161 text of the POD paragraph. The <code>-name</code> keyword indicates the name of
 162 the corresponding POD command, such as <code>head1</code> or <code>item</code> (it should
 163 <em>not</em> contain the <code>=</code> prefix); this is needed only if the POD
 164 paragraph corresponds to a command paragraph. The <code>-file</code> and <code>-line</code>
 165 keywords indicate the filename and line number corresponding to the
 166 beginning of the paragraph</p>
 167 <p>
 168 </p>
 169 <h2><a name="_pod_para_cmd_name__">$pod_para-&gt;<strong>cmd_name()</strong></a></h2>
 170 <pre>
 171         my $para_cmd = $pod_para-&gt;cmd_name();</pre>
 172 <p>If this paragraph is a command paragraph, then this method will return
 173 the name of the command (<em>without</em> any leading <code>=</code> prefix).</p>
 174 <p>
 175 </p>
 176 <h2><a name="_pod_para_text__">$pod_para-&gt;<strong>text()</strong></a></h2>
 177 <pre>
 178         my $para_text = $pod_para-&gt;text();</pre>
 179 <p>This method will return the corresponding text of the paragraph.</p>
 180 <p>
 181 </p>
 182 <h2><a name="_pod_para_raw_text__">$pod_para-&gt;<strong>raw_text()</strong></a></h2>
 183 <pre>
 184         my $raw_pod_para = $pod_para-&gt;raw_text();</pre>
 185 <p>This method will return the <em>raw</em> text of the POD paragraph, exactly
 186 as it appeared in the input.</p>
 187 <p>
 188 </p>
 189 <h2><a name="_pod_para_cmd_prefix__">$pod_para-&gt;<strong>cmd_prefix()</strong></a></h2>
 190 <pre>
 191         my $prefix = $pod_para-&gt;cmd_prefix();</pre>
 192 <p>If this paragraph is a command paragraph, then this method will return
 193 the prefix used to denote the command (which should be the string ``=''
 194 or ``=='').</p>
 195 <p>
 196 </p>
 197 <h2><a name="_pod_para_cmd_separator__">$pod_para-&gt;<strong>cmd_separator()</strong></a></h2>
 198 <pre>
 199         my $separator = $pod_para-&gt;cmd_separator();</pre>
 200 <p>If this paragraph is a command paragraph, then this method will return
 201 the text used to separate the command name from the rest of the
 202 paragraph (if any).</p>
 203 <p>
 204 </p>
 205 <h2><a name="_pod_para_parse_tree__">$pod_para-&gt;<strong>parse_tree()</strong></a></h2>
 206 <pre>
 207         my $ptree = $pod_parser-&gt;parse_text( $pod_para-&gt;text() );
 208         $pod_para-&gt;parse_tree( $ptree );
 209         $ptree = $pod_para-&gt;parse_tree();</pre>
 210 <p>This method will get/set the corresponding parse-tree of the paragraph's text.</p>
 211 <p>
 212 </p>
 213 <h2><a name="_pod_para_file_line__">$pod_para-&gt;<strong>file_line()</strong></a></h2>
 214 <pre>
 215         my ($filename, $line_number) = $pod_para-&gt;file_line();
 216         my $position = $pod_para-&gt;file_line();</pre>
 217 <p>Returns the current filename and line number for the paragraph
 218 object.  If called in a list context, it returns a list of two
 219 elements: first the filename, then the line number. If called in
 220 a scalar context, it returns a string containing the filename, followed
 221 by a colon (':'), followed by the line number.</p>
 222 <p>
 223 </p>
 224 <hr />
 225 <h1><a name="pod__interiorsequence"><strong>Pod::InteriorSequence</strong></a></h1>
 226 <p>An object representing a POD interior sequence command.
 227 It has the following methods/attributes:</p>
 228 <p>
 229 </p>
 230 <h2><a name="pod__interiorsequence_new__">Pod::InteriorSequence-&gt;<strong>new()</strong></a></h2>
 231 <pre>
 232         my $pod_seq1 = Pod::InteriorSequence-&gt;new(-name =&gt; $cmd
 233                                                   -ldelim =&gt; $delimiter);
 234         my $pod_seq2 = new Pod::InteriorSequence(-name =&gt; $cmd,
 235                                                  -ldelim =&gt; $delimiter);
 236         my $pod_seq3 = new Pod::InteriorSequence(-name =&gt; $cmd,
 237                                                  -ldelim =&gt; $delimiter,
 238                                                  -file =&gt; $filename,
 239                                                  -line =&gt; $line_number);</pre>
 240 <pre>
 241         my $pod_seq4 = new Pod::InteriorSequence(-name =&gt; $cmd, $ptree);
 242         my $pod_seq5 = new Pod::InteriorSequence($cmd, $ptree);</pre>
 243 <p>This is a class method that constructs a <code>Pod::InteriorSequence</code> object
 244 and returns a reference to the new interior sequence object. It should
 245 be given two keyword arguments.  The <code>-ldelim</code> keyword indicates the
 246 corresponding left-delimiter of the interior sequence (e.g. '&lt;').
 247 The <code>-name</code> keyword indicates the name of the corresponding interior
 248 sequence command, such as <code>I</code> or <code>B</code> or <code>C</code>. The <code>-file</code> and
 249 <code>-line</code> keywords indicate the filename and line number corresponding
 250 to the beginning of the interior sequence. If the <code>$ptree</code> argument is
 251 given, it must be the last argument, and it must be either string, or
 252 else an array-ref suitable for passing to <strong>Pod::ParseTree::new</strong> (or
 253 it may be a reference to a Pod::ParseTree object).</p>
 254 <p>
 255 </p>
 256 <h2><a name="_pod_seq_cmd_name__">$pod_seq-&gt;<strong>cmd_name()</strong></a></h2>
 257 <pre>
 258         my $seq_cmd = $pod_seq-&gt;cmd_name();</pre>
 259 <p>The name of the interior sequence command.</p>
 260 <p>
 261 </p>
 262 <h2><a name="_pod_seq_prepend__">$pod_seq-&gt;<strong>prepend()</strong></a></h2>
 263 <pre>
 264         $pod_seq-&gt;prepend($text);
 265         $pod_seq1-&gt;prepend($pod_seq2);</pre>
 266 <p>Prepends the given string or parse-tree or sequence object to the parse-tree
 267 of this interior sequence.</p>
 268 <p>
 269 </p>
 270 <h2><a name="_pod_seq_append__">$pod_seq-&gt;<strong>append()</strong></a></h2>
 271 <pre>
 272         $pod_seq-&gt;append($text);
 273         $pod_seq1-&gt;append($pod_seq2);</pre>
 274 <p>Appends the given string or parse-tree or sequence object to the parse-tree
 275 of this interior sequence.</p>
 276 <p>
 277 </p>
 278 <h2><a name="_pod_seq_nested__">$pod_seq-&gt;<strong>nested()</strong></a></h2>
 279 <pre>
 280         $outer_seq = $pod_seq-&gt;nested || print &quot;not nested&quot;;</pre>
 281 <p>If this interior sequence is nested inside of another interior
 282 sequence, then the outer/parent sequence that contains it is
 283 returned. Otherwise <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is returned.</p>
 284 <p>
 285 </p>
 286 <h2><a name="_pod_seq_raw_text__">$pod_seq-&gt;<strong>raw_text()</strong></a></h2>
 287 <pre>
 288         my $seq_raw_text = $pod_seq-&gt;raw_text();</pre>
 289 <p>This method will return the <em>raw</em> text of the POD interior sequence,
 290 exactly as it appeared in the input.</p>
 291 <p>
 292 </p>
 293 <h2><a name="_pod_seq_left_delimiter__">$pod_seq-&gt;<strong>left_delimiter()</strong></a></h2>
 294 <pre>
 295         my $ldelim = $pod_seq-&gt;left_delimiter();</pre>
 296 <p>The leftmost delimiter beginning the argument text to the interior
 297 sequence (should be ``&lt;'').</p>
 298 <p>
 299 </p>
 300 <h2><a name="_pod_seq_right_delimiter__">$pod_seq-&gt;<strong>right_delimiter()</strong></a></h2>
 301 <p>The rightmost delimiter beginning the argument text to the interior
 302 sequence (should be ``&gt;'').</p>
 303 <p>
 304 </p>
 305 <h2><a name="_pod_seq_parse_tree__">$pod_seq-&gt;<strong>parse_tree()</strong></a></h2>
 306 <pre>
 307         my $ptree = $pod_parser-&gt;parse_text($paragraph_text);
 308         $pod_seq-&gt;parse_tree( $ptree );
 309         $ptree = $pod_seq-&gt;parse_tree();</pre>
 310 <p>This method will get/set the corresponding parse-tree of the interior
 311 sequence's text.</p>
 312 <p>
 313 </p>
 314 <h2><a name="_pod_seq_file_line__">$pod_seq-&gt;<strong>file_line()</strong></a></h2>
 315 <pre>
 316         my ($filename, $line_number) = $pod_seq-&gt;file_line();
 317         my $position = $pod_seq-&gt;file_line();</pre>
 318 <p>Returns the current filename and line number for the interior sequence
 319 object.  If called in a list context, it returns a list of two
 320 elements: first the filename, then the line number. If called in
 321 a scalar context, it returns a string containing the filename, followed
 322 by a colon (':'), followed by the line number.</p>
 323 <p>
 324 </p>
 325 <h2><a name="pod__interiorsequence__destroy__">Pod::InteriorSequence::<strong>DESTROY()</strong></a></h2>
 326 <p>This method performs any necessary cleanup for the interior-sequence.
 327 If you override this method then it is <strong>imperative</strong> that you invoke
 328 the parent method from within your own method, otherwise
 329 <em>interior-sequence storage will not be reclaimed upon destruction!</em></p>
 330 <p>
 331 </p>
 332 <hr />
 333 <h1><a name="pod__parsetree"><strong>Pod::ParseTree</strong></a></h1>
 334 <p>This object corresponds to a tree of parsed POD text. As POD text is
 335 scanned from left to right, it is parsed into an ordered list of
 336 text-strings and <strong>Pod::InteriorSequence</strong> objects (in order of
 337 appearance). A <strong>Pod::ParseTree</strong> object corresponds to this list of
 338 strings and sequences. Each interior sequence in the parse-tree may
 339 itself contain a parse-tree (since interior sequences may be nested).</p>
 340 <p>
 341 </p>
 342 <h2><a name="pod__parsetree_new__">Pod::ParseTree-&gt;<strong>new()</strong></a></h2>
 343 <pre>
 344         my $ptree1 = Pod::ParseTree-&gt;new;
 345         my $ptree2 = new Pod::ParseTree;
 346         my $ptree4 = Pod::ParseTree-&gt;new($array_ref);
 347         my $ptree3 = new Pod::ParseTree($array_ref);</pre>
 348 <p>This is a class method that constructs a <code>Pod::Parse_tree</code> object and
 349 returns a reference to the new parse-tree. If a single-argument is given,
 350 it must be a reference to an array, and is used to initialize the root
 351 (top) of the parse tree.</p>
 352 <p>
 353 </p>
 354 <h2><a name="_ptree_top__">$ptree-&gt;<strong>top()</strong></a></h2>
 355 <pre>
 356         my $top_node = $ptree-&gt;top();
 357         $ptree-&gt;top( $top_node );
 358         $ptree-&gt;top( @children );</pre>
 359 <p>This method gets/sets the top node of the parse-tree. If no arguments are
 360 given, it returns the topmost node in the tree (the root), which is also
 361 a <strong>Pod::ParseTree</strong>. If it is given a single argument that is a reference,
 362 then the reference is assumed to a parse-tree and becomes the new top node.
 363 Otherwise, if arguments are given, they are treated as the new list of
 364 children for the top node.</p>
 365 <p>
 366 </p>
 367 <h2><a name="_ptree_children__">$ptree-&gt;<strong>children()</strong></a></h2>
 368 <p>This method gets/sets the children of the top node in the parse-tree.
 369 If no arguments are given, it returns the list (array) of children
 370 (each of which should be either a string or a <strong>Pod::InteriorSequence</strong>.
 371 Otherwise, if arguments are given, they are treated as the new list of
 372 children for the top node.</p>
 373 <p>
 374 </p>
 375 <h2><a name="_ptree_prepend__">$ptree-&gt;<strong>prepend()</strong></a></h2>
 376 <p>This method prepends the given text or parse-tree to the current parse-tree.
 377 If the first item on the parse-tree is text and the argument is also text,
 378 then the text is prepended to the first item (not added as a separate string).
 379 Otherwise the argument is added as a new string or parse-tree <em>before</em>
 380 the current one.</p>
 381 <p>
 382 </p>
 383 <h2><a name="_ptree_append__">$ptree-&gt;<strong>append()</strong></a></h2>
 384 <p>This method appends the given text or parse-tree to the current parse-tree.
 385 If the last item on the parse-tree is text and the argument is also text,
 386 then the text is appended to the last item (not added as a separate string).
 387 Otherwise the argument is added as a new string or parse-tree <em>after</em>
 388 the current one.</p>
 389 <p>
 390 </p>
 391 <h2><a name="_ptree_raw_text__">$ptree-&gt;<strong>raw_text()</strong></a></h2>
 392 <pre>
 393         my $ptree_raw_text = $ptree-&gt;raw_text();</pre>
 394 <p>This method will return the <em>raw</em> text of the POD parse-tree
 395 exactly as it appeared in the input.</p>
 396 <p>
 397 </p>
 398 <h2><a name="pod__parsetree__destroy__">Pod::ParseTree::<strong>DESTROY()</strong></a></h2>
 399 <p>This method performs any necessary cleanup for the parse-tree.
 400 If you override this method then it is <strong>imperative</strong>
 401 that you invoke the parent method from within your own method,
 402 otherwise <em>parse-tree storage will not be reclaimed upon destruction!</em></p>
 403 <p>
 404 </p>
 405 <hr />
 406 <h1><a name="see_also">SEE ALSO</a></h1>
 407 <p>See <a href="file://C|\msysgit\mingw\html/lib/Pod/Parser.html">the Pod::Parser manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/Pod/Select.html">the Pod::Select manpage</a></p>
 408 <p>
 409 </p>
 410 <hr />
 411 <h1><a name="author">AUTHOR</a></h1>
 412 <p>Please report bugs using <a href="http://rt.cpan.org">http://rt.cpan.org</a>.</p>
 413 <p>Brad Appleton &lt;<a href="mailto:bradapp@enteract.com">bradapp@enteract.com</a>&gt;</p>
 414 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 415 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 416 <big><strong><span class="block">&nbsp;Pod::InputObjects - objects representing POD input paragraphs, commands, etc.</span></strong></big>
 417 </td></tr>
 418 </table>
 419
 420 </body>
 421
 422 </html>