home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _eea98029c8650c398888397be8703941 < prev    next >
Text File  |  2000-03-23  |  16KB  |  395 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>pod2usage - print a usage message from embedded pod documentation</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> pod2usage - print a usage message from embedded pod documentation</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="#arguments">ARGUMENTS</A></LI>
  25.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  26.     <LI><A HREF="#examples">EXAMPLES</A></LI>
  27.     <UL>
  28.  
  29.         <LI><A HREF="#recommended use">Recommended Use</A></LI>
  30.     </UL>
  31.  
  32.     <LI><A HREF="#caveats">CAVEATS</A></LI>
  33.     <LI><A HREF="#author">AUTHOR</A></LI>
  34.     <LI><A HREF="#acknowledgements">ACKNOWLEDGEMENTS</A></LI>
  35. </UL>
  36. <!-- INDEX END -->
  37.  
  38. <HR>
  39. <P>
  40. <H1><A NAME="name">NAME</A></H1>
  41. <P>Pod::Usage, <CODE>pod2usage()</CODE> - print a usage message from embedded pod documentation</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::Usage</PRE>
  54. <PRE>
  55.   my $message_text  = "This text precedes the usage message.";
  56.   my $exit_status   = 2;          ## The exit status to use
  57.   my $verbose_level = 0;          ## The verbose level to use
  58.   my $filehandle    = \*STDERR;   ## The filehandle to write to</PRE>
  59. <PRE>
  60.   pod2usage($message_text);</PRE>
  61. <PRE>
  62.   pod2usage($exit_status);</PRE>
  63. <PRE>
  64.   pod2usage( { -message => $message_text ,
  65.                -exitval => $exit_status  ,  
  66.                -verbose => $verbose_level,  
  67.                -output  => $filehandle } );</PRE>
  68. <PRE>
  69.   pod2usage(   -msg     => $message_text ,
  70.                -exitval => $exit_status  ,  
  71.                -verbose => $verbose_level,  
  72.                -output  => $filehandle   );</PRE>
  73. <P>
  74. <HR>
  75. <H1><A NAME="arguments">ARGUMENTS</A></H1>
  76. <P><STRONG>pod2usage</STRONG> should be given either a single argument, or a list of
  77. arguments corresponding to an associative array (a ``hash''). When a single
  78. argument is given, it should correspond to exactly one of the following:</P>
  79. <UL>
  80. <LI>
  81. A string containing the text of a message to print <EM>before</EM> printing
  82. the usage message
  83. <P></P>
  84. <LI>
  85. A numeric value corresponding to the desired exit status
  86. <P></P>
  87. <LI>
  88. A reference to a hash
  89. <P></P></UL>
  90. <P>If more than one argument is given then the entire argument list is
  91. assumed to be a hash.  If a hash is supplied (either as a reference or
  92. as a list) it should contain one or more elements with the following
  93. keys:</P>
  94. <DL>
  95. <DT><STRONG><A NAME="item_%2Dmessage"><CODE>-message</CODE></A></STRONG><BR>
  96. <DD>
  97. <DT><STRONG><A NAME="item_%2Dmsg"><CODE>-msg</CODE></A></STRONG><BR>
  98. <DD>
  99. The text of a message to print immediately prior to printing the
  100. program's usage message.
  101. <P></P>
  102. <DT><STRONG><A NAME="item_%2Dexitval"><CODE>-exitval</CODE></A></STRONG><BR>
  103. <DD>
  104. The desired exit status to pass to the <STRONG>exit()</STRONG> function.
  105. <P></P>
  106. <DT><STRONG><A NAME="item_%2Dverbose"><CODE>-verbose</CODE></A></STRONG><BR>
  107. <DD>
  108. The desired level of ``verboseness'' to use when printing the usage
  109. message. If the corresponding value is 0, then only the ``SYNOPSIS''
  110. section of the pod documentation is printed. If the corresponding value
  111. is 1, then the ``SYNOPSIS'' section, along with any section entitled
  112. ``OPTIONS'', ``ARGUMENTS'', or ``OPTIONS AND ARGUMENTS'' is printed.  If the
  113. corresponding value is 2 or more then the entire manpage is printed.
  114. <P></P>
  115. <DT><STRONG><A NAME="item_%2Doutput"><CODE>-output</CODE></A></STRONG><BR>
  116. <DD>
  117. A reference to a filehandle, or the pathname of a file to which the
  118. usage message should be written. The default is <CODE>\*STDERR</CODE> unless the
  119. exit value is less than 2 (in which case the default is <CODE>\*STDOUT</CODE>).
  120. <P></P>
  121. <DT><STRONG><A NAME="item_%2Dinput"><CODE>-input</CODE></A></STRONG><BR>
  122. <DD>
  123. A reference to a filehandle, or the pathname of a file from which the
  124. invoking script's pod documentation should be read.  It defaults to the
  125. file indicated by <CODE>$0</CODE> (<CODE>$PROGRAM_NAME</CODE> for users of <EM>English.pm</EM>).
  126. <P></P>
  127. <DT><STRONG><A NAME="item_%2Dpathlist"><CODE>-pathlist</CODE></A></STRONG><BR>
  128. <DD>
  129. A list of directory paths. If the input file does not exist, then it
  130. will be searched for in the given directory list (in the order the
  131. directories appear in the list). It defaults to the list of directories
  132. implied by <CODE>$ENV{PATH}</CODE>. The list may be specified either by a reference
  133. to an array, or by a string of directory paths which use the same path
  134. separator as <CODE>$ENV{PATH}</CODE> on your system (e.g., <CODE>:</CODE> for Unix, <CODE>;</CODE> for
  135. MSWin32 and DOS).
  136. <P></P></DL>
  137. <P>
  138. <HR>
  139. <H1><A NAME="description">DESCRIPTION</A></H1>
  140. <P><STRONG>pod2usage</STRONG> will print a usage message for the invoking script (using
  141. its embedded pod documentation) and then exit the script with the
  142. desired exit status. The usage message printed may have any one of three
  143. levels of ``verboseness'': If the verbose level is 0, then only a synopsis
  144. is printed. If the verbose level is 1, then the synopsis is printed
  145. along with a description (if present) of the command line options and
  146. arguments. If the verbose level is 2, then the entire manual page is
  147. printed.</P>
  148. <P>Unless they are explicitly specified, the default values for the exit
  149. status, verbose level, and output stream to use are determined as
  150. follows:</P>
  151. <UL>
  152. <LI>
  153. If neither the exit status nor the verbose level is specified, then the
  154. default is to use an exit status of 2 with a verbose level of 0.
  155. <P></P>
  156. <LI>
  157. If an exit status <EM>is</EM> specified but the verbose level is <EM>not</EM>, then the
  158. verbose level will default to 1 if the exit status is less than 2 and
  159. will default to 0 otherwise.
  160. <P></P>
  161. <LI>
  162. If an exit status is <EM>not</EM> specified but verbose level <EM>is</EM> given, then
  163. the exit status will default to 2 if the verbose level is 0 and will
  164. default to 1 otherwise.
  165. <P></P>
  166. <LI>
  167. If the exit status used is less than 2, then output is printed on
  168. <CODE>STDOUT</CODE>.  Otherwise output is printed on <CODE>STDERR</CODE>.
  169. <P></P></UL>
  170. <P>Although the above may seem a bit confusing at first, it generally does
  171. ``the right thing'' in most situations.  This determination of the default
  172. values to use is based upon the following typical Unix conventions:</P>
  173. <UL>
  174. <LI>
  175. An exit status of 0 implies ``success''. For example, <STRONG>diff(1)</STRONG> exits
  176. with a status of 0 if the two files have the same contents.
  177. <P></P>
  178. <LI>
  179. An exit status of 1 implies possibly abnormal, but non-defective, program
  180. termination.  For example, <STRONG>grep(1)</STRONG> exits with a status of 1 if
  181. it did <EM>not</EM> find a matching line for the given regular expression.
  182. <P></P>
  183. <LI>
  184. An exit status of 2 or more implies a fatal error. For example, <STRONG>ls(1)</STRONG>
  185. exits with a status of 2 if you specify an illegal (unknown) option on
  186. the command line.
  187. <P></P>
  188. <LI>
  189. Usage messages issued as a result of bad command-line syntax should go
  190. to <CODE>STDERR</CODE>.  However, usage messages issued due to an explicit request
  191. to print usage (like specifying <STRONG>-help</STRONG> on the command line) should go
  192. to <CODE>STDOUT</CODE>, just in case the user wants to pipe the output to a pager
  193. (such as <STRONG>more(1)</STRONG>).
  194. <P></P>
  195. <LI>
  196. If program usage has been explicitly requested by the user, it is often
  197. desireable to exit with a status of 1 (as opposed to 0) after issuing
  198. the user-requested usage message.  It is also desireable to give a
  199. more verbose description of program usage in this case.
  200. <P></P></UL>
  201. <P><STRONG>pod2usage</STRONG> doesn't force the above conventions upon you, but it will
  202. use them by default if you don't expressly tell it to do otherwise.  The
  203. ability of <STRONG>pod2usage()</STRONG> to accept a single number or a string makes it
  204. convenient to use as an innocent looking error message handling function:</P>
  205. <PRE>
  206.     use Pod::Usage;
  207.     use Getopt::Long;</PRE>
  208. <PRE>
  209.     ## Parse options
  210.     GetOptions("help", "man", "flag1")  ||  pod2usage(2);
  211.     pod2usage(1)  if ($opt_help);
  212.     pod2usage(-verbose => 2)  if ($opt_man);</PRE>
  213. <PRE>
  214.     ## Check for too many filenames
  215.     pod2usage("$0: Too many files given.\n")  if (@ARGV > 1);</PRE>
  216. <P>Some user's however may feel that the above ``economy of expression'' is
  217. not particularly readable nor consistent and may instead choose to do
  218. something more like the following:</P>
  219. <PRE>
  220.     use Pod::Usage;
  221.     use Getopt::Long;</PRE>
  222. <PRE>
  223.     ## Parse options
  224.     GetOptions("help", "man", "flag1")  ||  pod2usage(-verbose => 0);
  225.     pod2usage(-verbose => 1)  if ($opt_help);
  226.     pod2usage(-verbose => 2)  if ($opt_man);</PRE>
  227. <PRE>
  228.     ## Check for too many filenames
  229.     pod2usage(-verbose => 2, -message => "$0: Too many files given.\n")
  230.         if (@ARGV > 1);</PRE>
  231. <P>As with all things in Perl, <EM>there's more than one way to do it</EM>, and
  232. <STRONG>pod2usage()</STRONG> adheres to this philosophy.  If you are interested in
  233. seeing a number of different ways to invoke <STRONG>pod2usage</STRONG> (although by no
  234. means exhaustive), please refer to <A HREF="#examples">EXAMPLES</A>.</P>
  235. <P>
  236. <HR>
  237. <H1><A NAME="examples">EXAMPLES</A></H1>
  238. <P>Each of the following invocations of <CODE>pod2usage()</CODE> will print just the
  239. ``SYNOPSIS'' section to <CODE>STDERR</CODE> and will exit with a status of 2:</P>
  240. <PRE>
  241.     pod2usage();</PRE>
  242. <PRE>
  243.     pod2usage(2);</PRE>
  244. <PRE>
  245.     pod2usage(-verbose => 0);</PRE>
  246. <PRE>
  247.     pod2usage(-exitval => 2);</PRE>
  248. <PRE>
  249.     pod2usage({-exitval => 2, -output => \*STDERR});</PRE>
  250. <PRE>
  251.     pod2usage({-verbose => 0, -output  => \*STDERR});</PRE>
  252. <PRE>
  253.     pod2usage(-exitval => 2, -verbose => 0);</PRE>
  254. <PRE>
  255.     pod2usage(-exitval => 2, -verbose => 0, -output => \*STDERR);</PRE>
  256. <P>Each of the following invocations of <CODE>pod2usage()</CODE> will print a message
  257. of ``Syntax error.'' (followed by a newline) to <CODE>STDERR</CODE>, immediately
  258. followed by just the ``SYNOPSIS'' section (also printed to <CODE>STDERR</CODE>) and
  259. will exit with a status of 2:</P>
  260. <PRE>
  261.     pod2usage("Syntax error.");</PRE>
  262. <PRE>
  263.     pod2usage(-message => "Syntax error.", -verbose => 0);</PRE>
  264. <PRE>
  265.     pod2usage(-msg  => "Syntax error.", -exitval => 2);</PRE>
  266. <PRE>
  267.     pod2usage({-msg => "Syntax error.", -exitval => 2, -output => \*STDERR});</PRE>
  268. <PRE>
  269.     pod2usage({-msg => "Syntax error.", -verbose => 0, -output => \*STDERR});</PRE>
  270. <PRE>
  271.     pod2usage(-msg  => "Syntax error.", -exitval => 2, -verbose => 0);</PRE>
  272. <PRE>
  273.     pod2usage(-message => "Syntax error.",
  274.               -exitval => 2,
  275.               -verbose => 0,
  276.               -output  => \*STDERR);</PRE>
  277. <P>Each of the following invocations of <CODE>pod2usage()</CODE> will print the
  278. ``SYNOPSIS'' section and any ``OPTIONS'' and/or ``ARGUMENTS'' sections to
  279. <CODE>STDOUT</CODE> and will exit with a status of 1:</P>
  280. <PRE>
  281.     pod2usage(1);</PRE>
  282. <PRE>
  283.     pod2usage(-verbose => 1);</PRE>
  284. <PRE>
  285.     pod2usage(-exitval => 1);</PRE>
  286. <PRE>
  287.     pod2usage({-exitval => 1, -output => \*STDOUT});</PRE>
  288. <PRE>
  289.     pod2usage({-verbose => 1, -output => \*STDOUT});</PRE>
  290. <PRE>
  291.     pod2usage(-exitval => 1, -verbose => 1);</PRE>
  292. <PRE>
  293.     pod2usage(-exitval => 1, -verbose => 1, -output => \*STDOUT});</PRE>
  294. <P>Each of the following invocations of <CODE>pod2usage()</CODE> will print the
  295. entire manual page to <CODE>STDOUT</CODE> and will exit with a status of 1:</P>
  296. <PRE>
  297.     pod2usage(-verbose  => 2);</PRE>
  298. <PRE>
  299.     pod2usage({-verbose => 2, -output => \*STDOUT});</PRE>
  300. <PRE>
  301.     pod2usage(-exitval  => 1, -verbose => 2);</PRE>
  302. <PRE>
  303.     pod2usage({-exitval => 1, -verbose => 2, -output => \*STDOUT});</PRE>
  304. <P>
  305. <H2><A NAME="recommended use">Recommended Use</A></H2>
  306. <P>Most scripts should print some type of usage message to <CODE>STDERR</CODE> when a
  307. command line syntax error is detected. They should also provide an
  308. option (usually <CODE>-H</CODE> or <CODE>-help</CODE>) to print a (possibly more verbose)
  309. usage message to <CODE>STDOUT</CODE>. Some scripts may even wish to go so far as to
  310. provide a means of printing their complete documentation to <CODE>STDOUT</CODE>
  311. (perhaps by allowing a <CODE>-man</CODE> option). The following complete example
  312. uses <STRONG>Pod::Usage</STRONG> in combination with <STRONG>Getopt::Long</STRONG> to do all of these
  313. things:</P>
  314. <PRE>
  315.     use Getopt::Long;
  316.     use Pod::Usage;</PRE>
  317. <PRE>
  318.     my $man = 0;
  319.     my $help = 0;
  320.     ## Parse options and print usage if there is a syntax error,
  321.     ## or if usage was explicitly requested.
  322.     GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
  323.     pod2usage(1) if $help;
  324.     pod2usage(-verbose => 2) if $man;</PRE>
  325. <PRE>
  326.     ## If no arguments were given, then allow STDIN to be used only
  327.     ## if it's not connected to a terminal (otherwise print usage)
  328.     pod2usage("$0: No files given.")  if ((@ARGV == 0) && (-t STDIN));
  329.     __END__</PRE>
  330. <PRE>
  331.     =head1 NAME</PRE>
  332. <PRE>
  333.     sample - Using GetOpt::Long and Pod::Usage</PRE>
  334. <PRE>
  335.     =head1 SYNOPSIS</PRE>
  336. <PRE>
  337.     sample [options] [file ...]</PRE>
  338. <PRE>
  339.      Options:
  340.        -help            brief help message
  341.        -man             full documentation</PRE>
  342. <PRE>
  343.     =head1 OPTIONS</PRE>
  344. <PRE>
  345.     =over 8</PRE>
  346. <PRE>
  347.     =item B<-help></PRE>
  348. <PRE>
  349.     Print a brief help message and exits.</PRE>
  350. <PRE>
  351.     =item B<-man></PRE>
  352. <PRE>
  353.     Prints the manual page and exits.</PRE>
  354. <PRE>
  355.     =back</PRE>
  356. <PRE>
  357.     =head1 DESCRIPTION</PRE>
  358. <PRE>
  359.     B<This program> will read the given input file(s) and do something
  360.     useful with the contents thereof.</PRE>
  361. <PRE>
  362.     =cut</PRE>
  363. <P>
  364. <HR>
  365. <H1><A NAME="caveats">CAVEATS</A></H1>
  366. <P>By default, <STRONG>pod2usage()</STRONG> will use <CODE>$0</CODE> as the path to the pod input
  367. file.  Unfortunately, not all systems on which Perl runs will set <CODE>$0</CODE>
  368. properly (although if <CODE>$0</CODE> isn't found, <STRONG>pod2usage()</STRONG> will search
  369. <CODE>$ENV{PATH}</CODE> or else the list specified by the <A HREF="#item_%2Dpathlist"><CODE>-pathlist</CODE></A> option).
  370. If this is the case for your system, you may need to explicitly specify
  371. the path to the pod docs for the invoking script using something
  372. similar to the following:</P>
  373. <PRE>
  374.     pod2usage(-exitval => 2, -input => "/path/to/your/pod/docs");</PRE>
  375. <P>
  376. <HR>
  377. <H1><A NAME="author">AUTHOR</A></H1>
  378. <P>Brad Appleton <<A HREF="mailto:bradapp@enteract.com">bradapp@enteract.com</A>></P>
  379. <P>Based on code for <STRONG>Pod::Text::pod2text()</STRONG> written by
  380. Tom Christiansen <<A HREF="mailto:tchrist@mox.perl.com">tchrist@mox.perl.com</A>></P>
  381. <P>
  382. <HR>
  383. <H1><A NAME="acknowledgements">ACKNOWLEDGEMENTS</A></H1>
  384. <P>Steven McDougall <<A HREF="mailto:swmcd@world.std.com">swmcd@world.std.com</A>> for his help and patience
  385. with re-writing this manpage.</P>
  386. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  387. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  388. <STRONG><P CLASS=block> pod2usage - print a usage message from embedded pod documentation</P></STRONG>
  389. </TD></TR>
  390. </TABLE>
  391.  
  392. </BODY>
  393.  
  394. </HTML>
  395.