This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Getopt::Std: Changed pod NAME to follow convention
[perl5.git] / lib / Getopt / Std.pm
index 99e9269..5b8878d 100644 (file)
@@ -4,43 +4,51 @@ require Exporter;
 
 =head1 NAME
 
-getopt - Process single-character switches with switch clustering
-
-getopts - Process single-character switches with switch clustering
+Getopt::Std - Process single-character switches with switch clustering
 
 =head1 SYNOPSIS
 
     use Getopt::Std;
 
-    getopt('oDI');    # -o, -D & -I take arg.  Sets $opt_* as a side effect.
-    getopt('oDI', \%opts);    # -o, -D & -I take arg.  Values in %opts
     getopts('oif:');  # -o & -i are boolean flags, -f takes an argument
                      # Sets $opt_* as a side effect.
     getopts('oif:', \%opts);  # options as above. Values in %opts
+    getopt('oDI');    # -o, -D & -I take arg.
+                      # Sets $opt_* as a side effect.
+    getopt('oDI', \%opts);    # -o, -D & -I take arg.  Values in %opts
 
 =head1 DESCRIPTION
 
-The getopt() function processes single-character switches with switch
-clustering.  Pass one argument which is a string containing all switches
-that take an argument.  For each switch found, sets $opt_x (where x is the
-switch name) to the value of the argument if an argument is expected,
-or 1 otherwise.  Switches which take an argument don't care whether
-there is a space between the switch and the argument.
+The C<getopts()> function processes single-character switches with switch
+clustering.  Pass one argument which is a string containing all switches to be
+recognized.  For each switch found, if an argument is expected and provided,
+C<getopts()> sets C<$opt_x> (where C<x> is the switch name) to the value of
+the argument.  If an argument is expected but none is provided, C<$opt_x> is
+set to an undefined value.  If a switch does not take an argument, C<$opt_x>
+is set to C<1>.
 
-The getopts() function is similar, but you should pass to it the list of all
-switches to be recognized.  If unspecified switches are found on the
+Switches which take an argument don't care whether there is a space between
+the switch and the argument.  If unspecified switches are found on the
 command-line, the user will be warned that an unknown option was given.
 
+The C<getopts()> function returns true unless an invalid option was found.
+
+The C<getopt()> function is similar, but its argument is a string containing
+all switches that take an argument.  If no argument is provided for a switch,
+say, C<y>, the corresponding C<$opt_y> will be set to an undefined value.
+Unspecified switches are silently accepted.  Use of C<getopt()> is not
+recommended.
+
 Note that, if your code is running under the recommended C<use strict
-'vars'> pragma, you will need to declare these package variables
-with "our":
+vars> pragma, you will need to declare these package variables
+with C<our>:
 
     our($opt_x, $opt_y);
 
-For those of you who don't like additional global variables being created, getopt()
-and getopts() will also accept a hash reference as an optional second argument. 
-Hash keys will be x (where x is the switch name) with key values the value of
-the argument or 1 if no argument is specified.
+For those of you who don't like additional global variables being created,
+C<getopt()> and C<getopts()> will also accept a hash reference as an optional
+second argument.  Hash keys will be C<x> (where C<x> is the switch name) with
+key values the value of the argument or C<1> if no argument is specified.
 
 To allow programs to process arguments that look like switches, but aren't,
 both functions will stop processing switches when they see the argument
@@ -55,6 +63,9 @@ the output file handle, the name of option-processing package, its version,
 and the switches string.  If the subroutines are not defined, an attempt is
 made to generate intelligent messages; for best results, define $main::VERSION.
 
+If embedded documentation (in pod format, see L<perlpod>) is detected
+in the script, C<--help> will also show how to access the documentation.
+
 Note that due to excessive paranoia, if $Getopt::Std::STANDARD_HELP_VERSION
 isn't true (the default is false), then the messages are printed on STDERR,
 and the processing continues after the messages are printed.  This being
@@ -70,7 +81,7 @@ and version_mess() with the switches string as an argument.
 
 @ISA = qw(Exporter);
 @EXPORT = qw(getopt getopts);
-$VERSION = '1.04';
+$VERSION = '1.12';
 # uncomment the next line to disable 1.03-backward compatibility paranoia
 # $STANDARD_HELP_VERSION = 1;
 
@@ -145,7 +156,7 @@ sub try_exit () {
     my $p = __PACKAGE__;
     print {output_h()} <<EOM;
   [Now continuing due to backward compatibility and excessive paranoia.
-   See ``perldoc $p'' about \$$p\::STANDARD_HELP_VERSION.]
+   See 'perldoc $p' about \$$p\::STANDARD_HELP_VERSION.]
 EOM
 }
 
@@ -186,12 +197,27 @@ sub help_mess ($;$) {
        }
        my ($scr) = ($0 =~ m,([^/\\]+)$,);
        print $h <<EOH if @_;                   # Let the script override this
+
 Usage: $scr [-OPTIONS [-MORE_OPTIONS]] [--] [PROGRAM_ARG1 ...]
 EOH
        print $h <<EOH;
+
 The following single-character options are accepted:$help
+
 Options may be merged together.  -- stops processing of options.$arg
 EOH
+       my $has_pod;
+       if ( defined $0 and $0 ne '-e' and -f $0 and -r $0
+            and open my $script, '<', $0 ) {
+           while (<$script>) {
+               $has_pod = 1, last if /^=(pod|head1)/;
+           }
+       }
+       print $h <<EOH if $has_pod;
+
+For more details run
+       perldoc -F $0
+EOH
     }
 }