home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _92a928e67d748d38ece18f4544964b11 < prev    next >
Text File  |  2000-03-23  |  13KB  |  305 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Pod::ParseUtils - helpers for POD parsing and conversion</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::ParseUtils - helpers for POD parsing and conversion</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="#description">DESCRIPTION</A></LI>
  25.     <UL>
  26.  
  27.         <LI><A HREF="#pod::list">Pod::List</A></LI>
  28.         <LI><A HREF="#pod::hyperlink">Pod::Hyperlink</A></LI>
  29.         <LI><A HREF="#pod::cache">Pod::Cache</A></LI>
  30.         <LI><A HREF="#pod::cache::item">Pod::Cache::Item</A></LI>
  31.     </UL>
  32.  
  33.     <LI><A HREF="#author">AUTHOR</A></LI>
  34.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  35. </UL>
  36. <!-- INDEX END -->
  37.  
  38. <HR>
  39. <P>
  40. <H1><A NAME="name">NAME</A></H1>
  41. <P>Pod::ParseUtils - helpers for POD parsing and conversion</P>
  42. <P>
  43. <HR>
  44. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  45. <UL>
  46. <LI>Linux</LI>
  47. <LI>Solaris</LI>
  48. <LI>Windows</LI>
  49. </UL>
  50. <HR>
  51. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  52. <PRE>
  53.   use Pod::ParseUtils;</PRE>
  54. <PRE>
  55.   my $list = new Pod::List;
  56.   my $link = Pod::Hyperlink->new('Pod::Parser');</PRE>
  57. <P>
  58. <HR>
  59. <H1><A NAME="description">DESCRIPTION</A></H1>
  60. <P><STRONG>Pod::ParseUtils</STRONG> contains a few object-oriented helper packages for
  61. POD parsing and processing (i.e. in POD formatters and translators).</P>
  62. <P>
  63. <H2><A NAME="pod::list">Pod::List</A></H2>
  64. <P><STRONG>Pod::List</STRONG> can be used to hold information about POD lists
  65. (written as =over ... =item ... =back) for further processing.
  66. The following methods are available:</P>
  67. <DL>
  68. <DT><STRONG><A NAME="item_new"><CODE>new()</CODE></A></STRONG><BR>
  69. <DD>
  70. Create a new list object. Properties may be specified through a hash
  71. reference like this:
  72. <PRE>
  73.   my $list = Pod::List->new({ -start => $., -indent => 4 });</PRE>
  74. <P>See the individual methods/properties for details.</P>
  75. <P></P>
  76. <DT><STRONG><A NAME="item_file"><CODE>file()</CODE></A></STRONG><BR>
  77. <DD>
  78. Without argument, retrieves the file name the list is in. This must
  79. have been set before by either specifying <STRONG>-file</STRONG> in the <STRONG>new()</STRONG>
  80. method or by calling the <STRONG>file()</STRONG> method with a scalar argument.
  81. <P></P>
  82. <DT><STRONG><A NAME="item_start"><CODE>start()</CODE></A></STRONG><BR>
  83. <DD>
  84. Without argument, retrieves the line number where the list started.
  85. This must have been set before by either specifying <STRONG>-start</STRONG> in the
  86. <STRONG>new()</STRONG> method or by calling the <STRONG>start()</STRONG> method with a scalar
  87. argument.
  88. <P></P>
  89. <DT><STRONG><A NAME="item_indent"><CODE>indent()</CODE></A></STRONG><BR>
  90. <DD>
  91. Without argument, retrieves the indent level of the list as specified
  92. in <CODE>=over n</CODE>. This must have been set before by either specifying
  93. <STRONG>-indent</STRONG> in the <STRONG>new()</STRONG> method or by calling the <STRONG>indent()</STRONG> method
  94. with a scalar argument.
  95. <P></P>
  96. <DT><STRONG><A NAME="item_type"><CODE>type()</CODE></A></STRONG><BR>
  97. <DD>
  98. Without argument, retrieves the list type, which can be an arbitrary value,
  99. e.g. <CODE>OL</CODE>, <CODE>UL</CODE>, ... when thinking the HTML way.
  100. This must have been set before by either specifying
  101. <STRONG>-type</STRONG> in the <STRONG>new()</STRONG> method or by calling the <STRONG>type()</STRONG> method
  102. with a scalar argument.
  103. <P></P>
  104. <DT><STRONG><A NAME="item_rx"><CODE>rx()</CODE></A></STRONG><BR>
  105. <DD>
  106. Without argument, retrieves a regular expression for simplifying the 
  107. individual item strings once the list type has been determined. Usage:
  108. E.g. when converting to HTML, one might strip the leading number in
  109. an ordered list as <CODE><OL></CODE> already prints numbers itself.
  110. This must have been set before by either specifying
  111. <STRONG>-rx</STRONG> in the <STRONG>new()</STRONG> method or by calling the <STRONG>rx()</STRONG> method
  112. with a scalar argument.
  113. <P></P>
  114. <DT><STRONG><A NAME="item_item"><CODE>item()</CODE></A></STRONG><BR>
  115. <DD>
  116. Without argument, retrieves the array of the items in this list.
  117. The items may be represented by any scalar.
  118. If an argument has been given, it is pushed on the list of items.
  119. <P></P>
  120. <DT><STRONG><A NAME="item_parent"><CODE>parent()</CODE></A></STRONG><BR>
  121. <DD>
  122. Without argument, retrieves information about the parent holding this
  123. list, which is represented as an arbitrary scalar.
  124. This must have been set before by either specifying
  125. <STRONG>-parent</STRONG> in the <STRONG>new()</STRONG> method or by calling the <STRONG>parent()</STRONG> method
  126. with a scalar argument.
  127. <P></P>
  128. <DT><STRONG><A NAME="item_tag"><CODE>tag()</CODE></A></STRONG><BR>
  129. <DD>
  130. Without argument, retrieves information about the list tag, which can be
  131. any scalar.
  132. This must have been set before by either specifying
  133. <STRONG>-tag</STRONG> in the <STRONG>new()</STRONG> method or by calling the <STRONG>tag()</STRONG> method
  134. with a scalar argument.
  135. <P></P></DL>
  136. <P>
  137. <H2><A NAME="pod::hyperlink">Pod::Hyperlink</A></H2>
  138. <P><STRONG>Pod::Hyperlink</STRONG> is a class for manipulation of POD hyperlinks. Usage:</P>
  139. <PRE>
  140.   my $link = Pod::Hyperlink->new('alternative text|page/"section in page"');</PRE>
  141. <P>The <STRONG>Pod::Hyperlink</STRONG> class is mainly designed to parse the contents of the
  142. <CODE>L<...></CODE> sequence, providing a simple interface for accessing the
  143. different parts of a POD hyperlink for further processing. It can also be
  144. used to construct hyperlinks.</P>
  145. <DL>
  146. <DT><STRONG><CODE>new()</CODE></STRONG><BR>
  147. <DD>
  148. The <STRONG>new()</STRONG> method can either be passed a set of key/value pairs or a single
  149. scalar value, namely the contents of a <CODE>L<...></CODE> sequence. An object
  150. of the class <CODE>Pod::Hyperlink</CODE> is returned. The value <A HREF="../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> indicates a
  151. failure, the error message is stored in <CODE>$@</CODE>.
  152. <P></P>
  153. <DT><STRONG><A NAME="item_parse"><CODE>parse($string)</CODE></A></STRONG><BR>
  154. <DD>
  155. This method can be used to (re)parse a (new) hyperlink, i.e. the contents
  156. of a <CODE>L<...></CODE> sequence. The result is stored in the current object.
  157. <P></P>
  158. <DT><STRONG><A NAME="item_markup"><CODE>markup($string)</CODE></A></STRONG><BR>
  159. <DD>
  160. Set/retrieve the textual value of the link. This string contains special
  161. markers <CODE>P<></CODE> and <CODE>Q<></CODE> that should be expanded by the
  162. translator's interior sequence expansion engine to the
  163. formatter-specific code to highlight/activate the hyperlink. The details
  164. have to be implemented in the translator.
  165. <P></P>
  166. <DT><STRONG><A NAME="item_text"><CODE>text()</CODE></A></STRONG><BR>
  167. <DD>
  168. This method returns the textual representation of the hyperlink as above,
  169. but without markers (read only). Depending on the link type this is one of
  170. the following alternatives (the + and * denote the portions of the text
  171. that are marked up):
  172. <PRE>
  173.   the +perl+ manpage
  174.   the *$|* entry in the +<A HREF="../../lib/Pod/perlvar.html">perlvar</A>+ manpage
  175.   the section on *OPTIONS* in the +perldoc+ manpage
  176.   the section on *DESCRIPTION* elsewhere in this document</PRE>
  177. <P></P>
  178. <DT><STRONG><A NAME="item_warning"><CODE>warning()</CODE></A></STRONG><BR>
  179. <DD>
  180. After parsing, this method returns any warnings encountered during the
  181. parsing process.
  182. <P></P>
  183. <DT><STRONG><A NAME="item_line">line(), <A HREF="#item_file"><CODE>file()</CODE></A></A></STRONG><BR>
  184. <DD>
  185. Just simple slots for storing information about the line and the file
  186. the link was encountered in. Has to be filled in manually.
  187. <P></P>
  188. <DT><STRONG><A NAME="item_page"><CODE>page()</CODE></A></STRONG><BR>
  189. <DD>
  190. This method sets or returns the POD page this link points to.
  191. <P></P>
  192. <DT><STRONG><A NAME="item_node"><CODE>node()</CODE></A></STRONG><BR>
  193. <DD>
  194. As above, but the destination node text of the link.
  195. <P></P>
  196. <DT><STRONG><A NAME="item_alttext"><CODE>alttext()</CODE></A></STRONG><BR>
  197. <DD>
  198. Sets or returns an alternative text specified in the link.
  199. <P></P>
  200. <DT><STRONG><CODE>type()</CODE></STRONG><BR>
  201. <DD>
  202. The node type, either <CODE>section</CODE> or <A HREF="#item_item"><CODE>item</CODE></A>. As an unofficial type,
  203. there is also <CODE>hyperlink</CODE>, derived from e.g. <CODE>L<http://perl.com></CODE>
  204. <P></P>
  205. <DT><STRONG><A NAME="item_link"><CODE>link()</CODE></A></STRONG><BR>
  206. <DD>
  207. Returns the link as contents of <CODE>L<></CODE>. Reciprocal to <STRONG>parse()</STRONG>.
  208. <P></P></DL>
  209. <P>
  210. <H2><A NAME="pod::cache">Pod::Cache</A></H2>
  211. <P><STRONG>Pod::Cache</STRONG> holds information about a set of POD documents,
  212. especially the nodes for hyperlinks.
  213. The following methods are available:</P>
  214. <DL>
  215. <DT><STRONG><CODE>new()</CODE></STRONG><BR>
  216. <DD>
  217. Create a new cache object. This object can hold an arbitrary number of
  218. POD documents of class Pod::Cache::Item.
  219. <P></P>
  220. <DT><STRONG><CODE>item()</CODE></STRONG><BR>
  221. <DD>
  222. Add a new item to the cache. Without arguments, this method returns a
  223. list of all cache elements.
  224. <P></P>
  225. <DT><STRONG><A NAME="item_find_page"><CODE>find_page($name)</CODE></A></STRONG><BR>
  226. <DD>
  227. Look for a POD document named <CODE>$name</CODE> in the cache. Returns the
  228. reference to the corresponding Pod::Cache::Item object or undef if
  229. not found.
  230. <P></P></DL>
  231. <P>
  232. <H2><A NAME="pod::cache::item">Pod::Cache::Item</A></H2>
  233. <P><STRONG>Pod::Cache::Item</STRONG> holds information about individual POD documents,
  234. that can be grouped in a Pod::Cache object.
  235. It is intended to hold information about the hyperlink nodes of POD
  236. documents.
  237. The following methods are available:</P>
  238. <DL>
  239. <DT><STRONG><CODE>new()</CODE></STRONG><BR>
  240. <DD>
  241. Create a new object.
  242. <P></P>
  243. <DT><STRONG><CODE>page()</CODE></STRONG><BR>
  244. <DD>
  245. Set/retrieve the POD document name (e.g. ``Pod::Parser'').
  246. <P></P>
  247. <DT><STRONG><A NAME="item_description"><CODE>description()</CODE></A></STRONG><BR>
  248. <DD>
  249. Set/retrieve the POD short description as found in the <CODE>=head1 NAME</CODE>
  250. section.
  251. <P></P>
  252. <DT><STRONG><A NAME="item_path"><CODE>path()</CODE></A></STRONG><BR>
  253. <DD>
  254. Set/retrieve the POD file storage path.
  255. <P></P>
  256. <DT><STRONG><CODE>file()</CODE></STRONG><BR>
  257. <DD>
  258. Set/retrieve the POD file name.
  259. <P></P>
  260. <DT><STRONG><A NAME="item_nodes"><CODE>nodes()</CODE></A></STRONG><BR>
  261. <DD>
  262. Add a node (or a list of nodes) to the document's node list. Note that
  263. the order is kept, i.e. start with the first node and end with the last.
  264. If no argument is given, the current list of nodes is returned in the
  265. same order the nodes have been added.
  266. A node can be any scalar, but usually is a pair of node string and
  267. unique id for the <A HREF="#item_find_node"><CODE>find_node</CODE></A> method to work correctly.
  268. <P></P>
  269. <DT><STRONG><A NAME="item_find_node"><CODE>find_node($name)</CODE></A></STRONG><BR>
  270. <DD>
  271. Look for a node or index entry named <CODE>$name</CODE> in the object.
  272. Returns the unique id of the node (i.e. the second element of the array
  273. stored in the node arry) or undef if not found.
  274. <P></P></DL>
  275. <DL>
  276. <DT><STRONG><A NAME="item_idx"><CODE>idx()</CODE></A></STRONG><BR>
  277. <DD>
  278. Add an index entry (or a list of them) to the document's index list. Note that
  279. the order is kept, i.e. start with the first node and end with the last.
  280. If no argument is given, the current list of index entries is returned in the
  281. same order the entries have been added.
  282. An index entry can be any scalar, but usually is a pair of string and
  283. unique id.
  284. <P></P></DL>
  285. <P>
  286. <HR>
  287. <H1><A NAME="author">AUTHOR</A></H1>
  288. <P>Marek Rouchal <<A HREF="mailto:marek@saftsack.fs.uni-bayreuth.de">marek@saftsack.fs.uni-bayreuth.de</A>>, borrowing
  289. a lot of things from <EM>pod2man</EM> and <EM>pod2roff</EM> as well as other POD
  290. processing tools by Tom Christiansen, Brad Appleton and Russ Allbery.</P>
  291. <P>
  292. <HR>
  293. <H1><A NAME="see also">SEE ALSO</A></H1>
  294. <P><EM>pod2man</EM>, <EM>pod2roff</EM>, <A HREF="../../lib/Pod/Parser.html">the Pod::Parser manpage</A>, <A HREF="../../lib/Pod/Checker.html">the Pod::Checker manpage</A>,
  295. <EM>pod2html</EM></P>
  296. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  297. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  298. <STRONG><P CLASS=block> Pod::ParseUtils - helpers for POD parsing and conversion</P></STRONG>
  299. </TD></TR>
  300. </TABLE>
  301.  
  302. </BODY>
  303.  
  304. </HTML>
  305.