home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _fac03926a0e0460d382d310a03a736e0 < prev    next >
Text File  |  2000-03-23  |  18KB  |  386 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Pod::InputObjects - objects representing POD input paragraphs, commands, etc.</TITLE>
  5. <LINK REL="stylesheet" HREF="../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Pod::InputObjects - objects representing POD input paragraphs, commands, etc.</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  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="#new()"><STRONG>new()</STRONG></A></LI>
  40.         <LI><A HREF="#cmd_name()"><STRONG>cmd_name()</STRONG></A></LI>
  41.         <LI><A HREF="#text()"><STRONG>text()</STRONG></A></LI>
  42.         <LI><A HREF="#raw_text()"><STRONG>raw_text()</STRONG></A></LI>
  43.         <LI><A HREF="#cmd_prefix()"><STRONG>cmd_prefix()</STRONG></A></LI>
  44.         <LI><A HREF="#cmd_separator()"><STRONG>cmd_separator()</STRONG></A></LI>
  45.         <LI><A HREF="#parse_tree()"><STRONG>parse_tree()</STRONG></A></LI>
  46.         <LI><A HREF="#file_line()"><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="#new()"><STRONG>new()</STRONG></A></LI>
  53.         <LI><A HREF="#cmd_name()"><STRONG>cmd_name()</STRONG></A></LI>
  54.         <LI><A HREF="#prepend()"><STRONG>prepend()</STRONG></A></LI>
  55.         <LI><A HREF="#append()"><STRONG>append()</STRONG></A></LI>
  56.         <LI><A HREF="#nested()"><STRONG>nested()</STRONG></A></LI>
  57.         <LI><A HREF="#raw_text()"><STRONG>raw_text()</STRONG></A></LI>
  58.         <LI><A HREF="#left_delimiter()"><STRONG>left_delimiter()</STRONG></A></LI>
  59.         <LI><A HREF="#right_delimiter()"><STRONG>right_delimiter()</STRONG></A></LI>
  60.         <LI><A HREF="#parse_tree()"><STRONG>parse_tree()</STRONG></A></LI>
  61.         <LI><A HREF="#file_line()"><STRONG>file_line()</STRONG></A></LI>
  62.         <LI><A HREF="#destroy()"><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="#new()"><STRONG>new()</STRONG></A></LI>
  69.         <LI><A HREF="#top()"><STRONG>top()</STRONG></A></LI>
  70.         <LI><A HREF="#children()"><STRONG>children()</STRONG></A></LI>
  71.         <LI><A HREF="#prepend()"><STRONG>prepend()</STRONG></A></LI>
  72.         <LI><A HREF="#append()"><STRONG>append()</STRONG></A></LI>
  73.         <LI><A HREF="#raw_text()"><STRONG>raw_text()</STRONG></A></LI>
  74.         <LI><A HREF="#destroy()"><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. <H1><A NAME="name">NAME</A></H1>
  85. <P>Pod::InputObjects - objects representing POD input paragraphs, commands, etc.</P>
  86. <P>
  87. <HR>
  88. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  89. <UL>
  90. <LI>Linux</LI>
  91. <LI>Solaris</LI>
  92. <LI>Windows</LI>
  93. </UL>
  94. <HR>
  95. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  96. <PRE>
  97.     use Pod::InputObjects;</PRE>
  98. <P>
  99. <HR>
  100. <H1><A NAME="requires">REQUIRES</A></H1>
  101. <P>perl5.004, Carp</P>
  102. <P>
  103. <HR>
  104. <H1><A NAME="exports">EXPORTS</A></H1>
  105. <P>Nothing.</P>
  106. <P>
  107. <HR>
  108. <H1><A NAME="description">DESCRIPTION</A></H1>
  109. <P>This module defines some basic input objects used by <STRONG>Pod::Parser</STRONG> when
  110. reading and parsing POD text from an input source. The following objects
  111. are defined:</P>
  112. <DL>
  113. <DT><STRONG><A NAME="item_Pod%3A%3AParagraph"><STRONG>Pod::Paragraph</STRONG></A></STRONG><BR>
  114. <DD>
  115. An object corresponding to a paragraph of POD input text. It may be a
  116. plain paragraph, a verbatim paragraph, or a command paragraph (see
  117. <A HREF="../../lib/Pod/perlpod.html">the perlpod manpage</A>).
  118. <P></P>
  119. <DT><STRONG><A NAME="item_Pod%3A%3AInteriorSequence"><STRONG>Pod::InteriorSequence</STRONG></A></STRONG><BR>
  120. <DD>
  121. An object corresponding to an interior sequence command from the POD
  122. input text (see <A HREF="../../lib/Pod/perlpod.html">the perlpod manpage</A>).
  123. <P></P>
  124. <DT><STRONG><A NAME="item_Pod%3A%3AParseTree"><STRONG>Pod::ParseTree</STRONG></A></STRONG><BR>
  125. <DD>
  126. An object corresponding to a tree of parsed POD text. Each ``node'' in
  127. a parse-tree (or <EM>ptree</EM>) is either a text-string or a reference to
  128. a <STRONG>Pod::InteriorSequence</STRONG> object. The nodes appear in the parse-tree
  129. in they order in which they were parsed from  left-to-right.
  130. <P></P></DL>
  131. <P>Each of these input objects are described in further detail in the
  132. sections which follow.</P>
  133. <P>
  134. <HR>
  135. <H1><A NAME="pod::paragraph"><STRONG>Pod::Paragraph</STRONG></A></H1>
  136. <P>An object representing a paragraph of POD input text.
  137. It has the following methods/attributes:</P>
  138. <P>
  139. <H2><A NAME="new()"><STRONG>new()</STRONG></A></H2>
  140. <PRE>
  141.         my $pod_para1 = Pod::Paragraph->new(-text => $text);
  142.         my $pod_para2 = Pod::Paragraph->new(-name => $cmd,
  143.                                             -text => $text);
  144.         my $pod_para3 = new Pod::Paragraph(-text => $text);
  145.         my $pod_para4 = new Pod::Paragraph(-name => $cmd,
  146.                                            -text => $text);
  147.         my $pod_para5 = Pod::Paragraph->new(-name => $cmd,
  148.                                             -text => $text,
  149.                                             -file => $filename,
  150.                                             -line => $line_number);</PRE>
  151. <P>This is a class method that constructs a <A HREF="#item_Pod%3A%3AParagraph"><CODE>Pod::Paragraph</CODE></A> object and
  152. returns a reference to the new paragraph object. It may be given one or
  153. two keyword arguments. The <CODE>-text</CODE> keyword indicates the corresponding
  154. text of the POD paragraph. The <CODE>-name</CODE> keyword indicates the name of
  155. the corresponding POD command, such as <CODE>head1</CODE> or <CODE>item</CODE> (it should
  156. <EM>not</EM> contain the <CODE>=</CODE> prefix); this is needed only if the POD
  157. paragraph corresponds to a command paragraph. The <CODE>-file</CODE> and <CODE>-line</CODE>
  158. keywords indicate the filename and line number corresponding to the
  159. beginning of the paragraph</P>
  160. <P>
  161. <H2><A NAME="cmd_name()"><STRONG>cmd_name()</STRONG></A></H2>
  162. <PRE>
  163.         my $para_cmd = $pod_para->cmd_name();</PRE>
  164. <P>If this paragraph is a command paragraph, then this method will return 
  165. the name of the command (<EM>without</EM> any leading <CODE>=</CODE> prefix).</P>
  166. <P>
  167. <H2><A NAME="text()"><STRONG>text()</STRONG></A></H2>
  168. <PRE>
  169.         my $para_text = $pod_para->text();</PRE>
  170. <P>This method will return the corresponding text of the paragraph.</P>
  171. <P>
  172. <H2><A NAME="raw_text()"><STRONG>raw_text()</STRONG></A></H2>
  173. <PRE>
  174.         my $raw_pod_para = $pod_para->raw_text();</PRE>
  175. <P>This method will return the <EM>raw</EM> text of the POD paragraph, exactly
  176. as it appeared in the input.</P>
  177. <P>
  178. <H2><A NAME="cmd_prefix()"><STRONG>cmd_prefix()</STRONG></A></H2>
  179. <PRE>
  180.         my $prefix = $pod_para->cmd_prefix();</PRE>
  181. <P>If this paragraph is a command paragraph, then this method will return 
  182. the prefix used to denote the command (which should be the string ``=''
  183. or ``=='').</P>
  184. <P>
  185. <H2><A NAME="cmd_separator()"><STRONG>cmd_separator()</STRONG></A></H2>
  186. <PRE>
  187.         my $separator = $pod_para->cmd_separator();</PRE>
  188. <P>If this paragraph is a command paragraph, then this method will return
  189. the text used to separate the command name from the rest of the
  190. paragraph (if any).</P>
  191. <P>
  192. <H2><A NAME="parse_tree()"><STRONG>parse_tree()</STRONG></A></H2>
  193. <PRE>
  194.         my $ptree = $pod_parser->parse_text( $pod_para->text() );
  195.         $pod_para->parse_tree( $ptree );
  196.         $ptree = $pod_para->parse_tree();</PRE>
  197. <P>This method will get/set the corresponding parse-tree of the paragraph's text.</P>
  198. <P>
  199. <H2><A NAME="file_line()"><STRONG>file_line()</STRONG></A></H2>
  200. <PRE>
  201.         my ($filename, $line_number) = $pod_para->file_line();
  202.         my $position = $pod_para->file_line();</PRE>
  203. <P>Returns the current filename and line number for the paragraph
  204. object.  If called in an array context, it returns a list of two
  205. elements: first the filename, then the line number. If called in
  206. a scalar context, it returns a string containing the filename, followed
  207. by a colon (':'), followed by the line number.</P>
  208. <P>
  209. <HR>
  210. <H1><A NAME="pod::interiorsequence"><STRONG>Pod::InteriorSequence</STRONG></A></H1>
  211. <P>An object representing a POD interior sequence command.
  212. It has the following methods/attributes:</P>
  213. <P>
  214. <H2><A NAME="new()"><STRONG>new()</STRONG></A></H2>
  215. <PRE>
  216.         my $pod_seq1 = Pod::InteriorSequence->new(-name => $cmd
  217.                                                   -ldelim => $delimiter);
  218.         my $pod_seq2 = new Pod::InteriorSequence(-name => $cmd,
  219.                                                  -ldelim => $delimiter);
  220.         my $pod_seq3 = new Pod::InteriorSequence(-name => $cmd,
  221.                                                  -ldelim => $delimiter,
  222.                                                  -file => $filename,
  223.                                                  -line => $line_number);</PRE>
  224. <PRE>
  225.         my $pod_seq4 = new Pod::InteriorSequence(-name => $cmd, $ptree);
  226.         my $pod_seq5 = new Pod::InteriorSequence($cmd, $ptree);</PRE>
  227. <P>This is a class method that constructs a <A HREF="#item_Pod%3A%3AInteriorSequence"><CODE>Pod::InteriorSequence</CODE></A> object
  228. and returns a reference to the new interior sequence object. It should
  229. be given two keyword arguments.  The <CODE>-ldelim</CODE> keyword indicates the
  230. corresponding left-delimiter of the interior sequence (e.g. '<').
  231. The <CODE>-name</CODE> keyword indicates the name of the corresponding interior
  232. sequence command, such as <CODE>I</CODE> or <CODE>B</CODE> or <CODE>C</CODE>. The <CODE>-file</CODE> and
  233. <CODE>-line</CODE> keywords indicate the filename and line number corresponding
  234. to the beginning of the interior sequence. If the <CODE>$ptree</CODE> argument is
  235. given, it must be the last argument, and it must be either string, or
  236. else an array-ref suitable for passing to <STRONG>Pod::ParseTree::new</STRONG> (or
  237. it may be a reference to an Pod::ParseTree object).</P>
  238. <P>
  239. <H2><A NAME="cmd_name()"><STRONG>cmd_name()</STRONG></A></H2>
  240. <PRE>
  241.         my $seq_cmd = $pod_seq->cmd_name();</PRE>
  242. <P>The name of the interior sequence command.</P>
  243. <P>
  244. <H2><A NAME="prepend()"><STRONG>prepend()</STRONG></A></H2>
  245. <PRE>
  246.         $pod_seq->prepend($text);
  247.         $pod_seq1->prepend($pod_seq2);</PRE>
  248. <P>Prepends the given string or parse-tree or sequence object to the parse-tree
  249. of this interior sequence.</P>
  250. <P>
  251. <H2><A NAME="append()"><STRONG>append()</STRONG></A></H2>
  252. <PRE>
  253.         $pod_seq->append($text);
  254.         $pod_seq1->append($pod_seq2);</PRE>
  255. <P>Appends the given string or parse-tree or sequence object to the parse-tree
  256. of this interior sequence.</P>
  257. <P>
  258. <H2><A NAME="nested()"><STRONG>nested()</STRONG></A></H2>
  259. <PRE>
  260.         $outer_seq = $pod_seq->nested || print "not nested";</PRE>
  261. <P>If this interior sequence is nested inside of another interior
  262. sequence, then the outer/parent sequence that contains it is
  263. returned. Otherwise <A HREF="../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> is returned.</P>
  264. <P>
  265. <H2><A NAME="raw_text()"><STRONG>raw_text()</STRONG></A></H2>
  266. <PRE>
  267.         my $seq_raw_text = $pod_seq->raw_text();</PRE>
  268. <P>This method will return the <EM>raw</EM> text of the POD interior sequence,
  269. exactly as it appeared in the input.</P>
  270. <P>
  271. <H2><A NAME="left_delimiter()"><STRONG>left_delimiter()</STRONG></A></H2>
  272. <PRE>
  273.         my $ldelim = $pod_seq->left_delimiter();</PRE>
  274. <P>The leftmost delimiter beginning the argument text to the interior
  275. sequence (should be ``<'').</P>
  276. <P>
  277. <H2><A NAME="right_delimiter()"><STRONG>right_delimiter()</STRONG></A></H2>
  278. <P>The rightmost delimiter beginning the argument text to the interior
  279. sequence (should be ``>'').</P>
  280. <P>
  281. <H2><A NAME="parse_tree()"><STRONG>parse_tree()</STRONG></A></H2>
  282. <PRE>
  283.         my $ptree = $pod_parser->parse_text($paragraph_text);
  284.         $pod_seq->parse_tree( $ptree );
  285.         $ptree = $pod_seq->parse_tree();</PRE>
  286. <P>This method will get/set the corresponding parse-tree of the interior
  287. sequence's text.</P>
  288. <P>
  289. <H2><A NAME="file_line()"><STRONG>file_line()</STRONG></A></H2>
  290. <PRE>
  291.         my ($filename, $line_number) = $pod_seq->file_line();
  292.         my $position = $pod_seq->file_line();</PRE>
  293. <P>Returns the current filename and line number for the interior sequence
  294. object.  If called in an array context, it returns a list of two
  295. elements: first the filename, then the line number. If called in
  296. a scalar context, it returns a string containing the filename, followed
  297. by a colon (':'), followed by the line number.</P>
  298. <P>
  299. <H2><A NAME="destroy()"><STRONG>DESTROY()</STRONG></A></H2>
  300. <P>This method performs any necessary cleanup for the interior-sequence.
  301. If you override this method then it is <STRONG>imperative</STRONG> that you invoke
  302. the parent method from within your own method, otherwise
  303. <EM>interior-sequence storage will not be reclaimed upon destruction!</EM></P>
  304. <P>
  305. <HR>
  306. <H1><A NAME="pod::parsetree"><STRONG>Pod::ParseTree</STRONG></A></H1>
  307. <P>This object corresponds to a tree of parsed POD text. As POD text is
  308. scanned from left to right, it is parsed into an ordered list of
  309. text-strings and <STRONG>Pod::InteriorSequence</STRONG> objects (in order of
  310. appearance). A <STRONG>Pod::ParseTree</STRONG> object corresponds to this list of
  311. strings and sequences. Each interior sequence in the parse-tree may
  312. itself contain a parse-tree (since interior sequences may be nested).</P>
  313. <P>
  314. <H2><A NAME="new()"><STRONG>new()</STRONG></A></H2>
  315. <PRE>
  316.         my $ptree1 = Pod::ParseTree->new;
  317.         my $ptree2 = new Pod::ParseTree;
  318.         my $ptree4 = Pod::ParseTree->new($array_ref);
  319.         my $ptree3 = new Pod::ParseTree($array_ref);</PRE>
  320. <P>This is a class method that constructs a <CODE>Pod::Parse_tree</CODE> object and
  321. returns a reference to the new parse-tree. If a single-argument is given,
  322. it must be a reference to an array, and is used to initialize the root
  323. (top) of the parse tree.</P>
  324. <P>
  325. <H2><A NAME="top()"><STRONG>top()</STRONG></A></H2>
  326. <PRE>
  327.         my $top_node = $ptree->top();
  328.         $ptree->top( $top_node );
  329.         $ptree->top( @children );</PRE>
  330. <P>This method gets/sets the top node of the parse-tree. If no arguments are
  331. given, it returns the topmost node in the tree (the root), which is also
  332. a <STRONG>Pod::ParseTree</STRONG>. If it is given a single argument that is a reference,
  333. then the reference is assumed to a parse-tree and becomes the new top node.
  334. Otherwise, if arguments are given, they are treated as the new list of
  335. children for the top node.</P>
  336. <P>
  337. <H2><A NAME="children()"><STRONG>children()</STRONG></A></H2>
  338. <P>This method gets/sets the children of the top node in the parse-tree.
  339. If no arguments are given, it returns the list (array) of children
  340. (each of which should be either a string or a <STRONG>Pod::InteriorSequence</STRONG>.
  341. Otherwise, if arguments are given, they are treated as the new list of
  342. children for the top node.</P>
  343. <P>
  344. <H2><A NAME="prepend()"><STRONG>prepend()</STRONG></A></H2>
  345. <P>This method prepends the given text or parse-tree to the current parse-tree.
  346. If the first item on the parse-tree is text and the argument is also text,
  347. then the text is prepended to the first item (not added as a separate string).
  348. Otherwise the argument is added as a new string or parse-tree <EM>before</EM>
  349. the current one.</P>
  350. <P>
  351. <H2><A NAME="append()"><STRONG>append()</STRONG></A></H2>
  352. <P>This method appends the given text or parse-tree to the current parse-tree.
  353. If the last item on the parse-tree is text and the argument is also text,
  354. then the text is appended to the last item (not added as a separate string).
  355. Otherwise the argument is added as a new string or parse-tree <EM>after</EM>
  356. the current one.</P>
  357. <P>
  358. <H2><A NAME="raw_text()"><STRONG>raw_text()</STRONG></A></H2>
  359. <PRE>
  360.         my $ptree_raw_text = $ptree->raw_text();</PRE>
  361. <P>This method will return the <EM>raw</EM> text of the POD parse-tree
  362. exactly as it appeared in the input.</P>
  363. <P>
  364. <H2><A NAME="destroy()"><STRONG>DESTROY()</STRONG></A></H2>
  365. <P>This method performs any necessary cleanup for the parse-tree.
  366. If you override this method then it is <STRONG>imperative</STRONG>
  367. that you invoke the parent method from within your own method,
  368. otherwise <EM>parse-tree storage will not be reclaimed upon destruction!</EM></P>
  369. <P>
  370. <HR>
  371. <H1><A NAME="see also">SEE ALSO</A></H1>
  372. <P>See <A HREF="../../lib/Pod/Parser.html">the Pod::Parser manpage</A>, <A HREF="../../lib/Pod/Select.html">the Pod::Select manpage</A></P>
  373. <P>
  374. <HR>
  375. <H1><A NAME="author">AUTHOR</A></H1>
  376. <P>Brad Appleton <<A HREF="mailto:bradapp@enteract.com">bradapp@enteract.com</A>></P>
  377. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  378. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  379. <STRONG><P CLASS=block> Pod::InputObjects - objects representing POD input paragraphs, commands, etc.</P></STRONG>
  380. </TD></TR>
  381. </TABLE>
  382.  
  383. </BODY>
  384.  
  385. </HTML>
  386.