r54284 - in /branches/upstream/libgetopt-long-descriptive-perl/current: Changes META.yml README lib/Getopt/Long/Descriptive.pm lib/Getopt/Long/Descriptive/Opts.pm lib/Getopt/Long/Descriptive/Usage.pm

jawnsy-guest at users.alioth.debian.org jawnsy-guest at users.alioth.debian.org
Sun Mar 14 03:46:45 UTC 2010


Author: jawnsy-guest
Date: Sun Mar 14 03:46:36 2010
New Revision: 54284

URL: http://svn.debian.org/wsvn/pkg-perl/?sc=1&rev=54284
Log:
[svn-upgrade] Integrating new upstream version, libgetopt-long-descriptive-perl (0.085)

Modified:
    branches/upstream/libgetopt-long-descriptive-perl/current/Changes
    branches/upstream/libgetopt-long-descriptive-perl/current/META.yml
    branches/upstream/libgetopt-long-descriptive-perl/current/README
    branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive.pm
    branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive/Opts.pm
    branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive/Usage.pm

Modified: branches/upstream/libgetopt-long-descriptive-perl/current/Changes
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libgetopt-long-descriptive-perl/current/Changes?rev=54284&op=diff
==============================================================================
--- branches/upstream/libgetopt-long-descriptive-perl/current/Changes (original)
+++ branches/upstream/libgetopt-long-descriptive-perl/current/Changes Sun Mar 14 03:46:36 2010
@@ -1,4 +1,7 @@
 Revision history for Getopt-Long-Descriptive
+
+0.085   2010-03-13
+        rewrite much of the documentation
 
 0.084   2010-02-14
         prevent auto-enabling of auto_help (Thanks, DOUGDUDE)

Modified: branches/upstream/libgetopt-long-descriptive-perl/current/META.yml
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libgetopt-long-descriptive-perl/current/META.yml?rev=54284&op=diff
==============================================================================
--- branches/upstream/libgetopt-long-descriptive-perl/current/META.yml (original)
+++ branches/upstream/libgetopt-long-descriptive-perl/current/META.yml Sun Mar 14 03:46:36 2010
@@ -1,7 +1,7 @@
 --- #YAML:1.0
 name:               Getopt-Long-Descriptive
-version:            0.084
-abstract:           Getopt::Long with usage text
+version:            0.085
+abstract:           Getopt::Long, but simpler and more powerful
 author:
     - Hans Dieter Pearcey <hdp at cpan.org>
 license:            unknown

Modified: branches/upstream/libgetopt-long-descriptive-perl/current/README
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libgetopt-long-descriptive-perl/current/README?rev=54284&op=diff
==============================================================================
--- branches/upstream/libgetopt-long-descriptive-perl/current/README (original)
+++ branches/upstream/libgetopt-long-descriptive-perl/current/README Sun Mar 14 03:46:36 2010
@@ -2,7 +2,7 @@
 
 VERSION
 
-0.084
+0.085
 
 INSTALLATION
 

Modified: branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive.pm
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive.pm?rev=54284&op=diff
==============================================================================
--- branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive.pm (original)
+++ branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive.pm Sun Mar 14 03:46:36 2010
@@ -1,11 +1,11 @@
+use strict;
 package Getopt::Long::Descriptive;
 
-use strict;
+use Carp qw(carp croak);
+use File::Basename ();
 use Getopt::Long 2.33;
 use List::Util qw(first);
-use Carp qw(carp croak);
 use Params::Validate qw(:all);
-use File::Basename ();
 use Scalar::Util ();
 
 use Getopt::Long::Descriptive::Opts;
@@ -13,93 +13,171 @@
 
 =head1 NAME
 
-Getopt::Long::Descriptive - Getopt::Long with usage text
+Getopt::Long::Descriptive - Getopt::Long, but simpler and more powerful
 
 =head1 VERSION
 
-Version 0.084
+Version 0.085
 
 =cut
 
-our $VERSION = '0.084';
+our $VERSION = '0.085';
+
+=head1 SYNOPSIS
+
+  use Getopt::Long::Descriptive;
+
+  my ($opt, $usage) = describe_options(
+    'my-program %o <some-arg>',
+    [ 'server|s=s', "the server to connect to"                  ],
+    [ 'port|p=i',   "the port to connect to", { default => 79 } ],
+    [],
+    [ 'verbose|v',  "print extra stuff"            ],
+    [ 'help',       "print usage message and exit" ],
+  );
+
+  print($usage->text), exit if $opt->help;
+
+  Client->connect( $opt->server, $opt->port );
+
+  print "Connected!\n" if $opt->verbose;
+
+...and running C<my-program --help> will produce:
+
+  my-program [-psv] [long options...] <some-arg>
+    -s --server     the server to connect to
+    -p --port       the port to connect to
+                  
+    -v --verbose    print extra stuff
+    --help          print usage message and exit
 
 =head1 DESCRIPTION
 
-Convenient wrapper for Getopt::Long and program usage output
-
-=head1 SYNOPSIS
-
-  use Getopt::Long::Descriptive;
-  my ($opts, $usage) = describe_options($format, @opts, \%arg);
-
-=head1 FORMAT
-
-  $format = "usage: myprog %o myarg...";
+Getopt::Long::Descriptive is yet another Getopt library.  It's built atop
+Getopt::Long, and gets a lot of its features, but tries to avoid making you
+think about its huge array of options.
+
+It also provides usage (help) messages, data validation, and a few other useful
+features.
+
+=head1 FUNCTIONS
+
+Getopt::Long::Descriptive only exports one routine, and exports it by default.
+It is exported with L<Sub::Exporter>.
+
+=head2 describe_options
+
+  my ($opt, $usage) = describe_options($usage_desc, @opt_spec, \%arg);
+
+This routine inspects C<@ARGV> returns the options given and a object
+for generating usage messages.
+
+The C<$opt> object will be a dynamically-generated subclass of
+L<Getopt::Long::Descriptive::Opts>.  In brief, each of the options in
+C<@opt_spec> becomes an accessor method on the object, using the first-given
+name, with dashes converted to underscores.  For more information, see the
+documentation for the Opts class.
+
+The C<$usage> object will be a L<Getopt::Long::Descriptive::Usage> object,
+which provides a C<text> method to get the text of the usage message and C<die>
+to die with it.  For more methods and options, consults the documentation for
+the Usage class.
+
+=head3 usage_desc
+
+The C<$usage_desc> parameter to C<describe_options> is a C<sprintf>-like string
+that is used in generating the first line of the usage message.  It's a
+one-line summary of how the command is to be invoked.  A typical usage
+description might be:
+
+  $usage_desc = "%c %o <source> <desc>";
+
+C<%c> will be replaced with what Getopt::Long::Descriptive thinks is the
+program name (it's computed from C<$0>, see L</prog_name>).
 
 C<%o> will be replaced with a list of the short options, as well as the text
 "[long options...]" if any have been defined.
 
-C<%c> will be replaced with what Getopt::Long::Descriptive
-thinks is the program name (see L</prog_name>).  You can
-override this guess by calling C<< prog_name($string) >>
-yourself.
-
-Because of this, any literal C<%> symbols will need to be written as C<%%>.
-
-=head1 OPTIONS
-
-Option specifications are the same as in Getopt::Long.  You should pass in an
-array of arrayrefs whose first elements are option specs and whose second
-elements are descriptions.
-
-  my @opts = (
+The rest of the usage description can be used to summarize what arguments are
+expected to follow the program's options, and is entirely free-form.
+
+Literal C<%> characters will need to be written as C<%%>, just like with
+C<sprintf>.
+
+=head3 opt_spec
+
+The C<@opt_spec> part of the args to C<describe_options> is used to configure
+option parsing and to produce the usage message.  Each entry in the list is an
+arrayref describing one option, like this:
+
+  @opt_spec = (
     [ "verbose|V" => "be noisy"       ],
     [ "logfile=s" => "file to log to" ],
   );
 
-Option specifications may have a third hashref argument.  If
-present, this configures extra restrictions on the value or
-presence of that option.
-
-You may cause a blank line to be printed by passing an empty
-arrayref.  Likewise, a plain descriptive line will be
-printed if you pass an arrayref with a single element:
-
-  @opts = (
-    $option,
-    [],
-    [ 'other options:' ],
-    $other_option,
-  );
-
-=head2 Option Constraints
-
-=head3 implies
+The first value in the arrayref is a Getopt::Long-style option specification.
+In brief, they work like this:  each one is a pipe-delimited list of names,
+optionally followed by a type declaration.  Type declarations are '=x' or ':x',
+where C<=> means a value is required and C<:> means it is optional.  I<x> may
+be 's' to indicate a string is required, 'i' for an integer, or 'f' for a
+number with a fractional part.  The type spec may end in C<@> to indicate that
+the option may appear multiple times.
+
+For more information on how these work, see the L<Getopt::Long> documentation.
+
+The first name given should be the canonical name, as it will be used as the
+accessor method on the C<$opt> object.  Dashes in the name will be converted to
+underscores, and all letters will be lowercased.  For this reason, all options
+should generally have a long-form name.
+
+The second value in the arrayref is a description of the option, for use in the
+usage message.
+
+=head4 Special Option Specifications
+
+If the option specification (arrayref) is empty, it will have no effect other
+than causing a blank line to appear in the usage message.
+
+If the option specification contains only one element, it will be printed in
+the usage message with no other effect.
+
+If the option specification contains a third element, it adds extra constraints
+or modifiers to the interpretation and validation of the value.  These are the
+keys that may be present in that hashref, and how they behave:
+
+=over 4
+
+=item implies
 
   implies => 'bar'
-
   implies => [qw(foo bar)]
-
   implies => { foo => 1, bar => 2 }
 
-=head3 required
+If option I<A> has an "implies" entry, then if I<A> is given, other options
+will be enabled.  The value may be a single option to set, an arrayref of
+options to set, or a hashref of options to set to specific values.
+
+=item required
 
   required => 1
 
-=head3 hidden
+If an option is required, failure to provide the option will result in
+C<describe_options> printing the usage message and exiting.
+
+=item hidden
 
   hidden => 1
 
 This option will not show up in the usage text.
 
-You can achieve this same behavior by using the string C<<
-hidden >> for the option's description.
-
-=head3 one_of
-
-  one_of => \@option_specs
-
-Useful for a group of options that are related.  Each option
+You can achieve the same behavior by using the string "hidden" for the option's
+description.
+
+=item one_of
+
+  one_of => \@subopt_specs
+
+This is useful for a group of options that are related.  Each option
 spec is added to the list for normal parsing and validation.
 
 Your option name will end up with a value of the name of the
@@ -111,102 +189,61 @@
     [ "delete" => "delete it" ],
   ] } ],
 
-No usage text for 'mode' will be displayed, though
-get/set/delete will all have descriptions.
-
-If more than one of get/set/delete (or their short versions)
-are given, an error will be thrown.
-
-If C<@ARGV> is C<--get>, a dump of the resultant option
-hashref would look like this:
-
-  { get  => 1,
-    mode => 'get' }
-
-NOTE: C<< get >> would not be set if C<< mode >> defaulted
-to 'get' and no arguments were passed in.
-
-WARNING: Even though the option sub-specs for C<< one_of >>
-are meant to be 'first class' specs, some options don't make
-sense with them, e.g. C<< required >>.
-
-As a further shorthand, you may specify C<< one_of >>
-options using this form:
+No usage text for 'mode' will be displayed, but text for get, set, and delete
+will be displayed.
+
+If more than one of get, set, or delete is given, an error will be thrown.
+
+So, given the C<@opt_spec> above, and an C<@ARGV> of C<('--get')>, the
+following would be true:
+
+  $opt->get == 1;
+
+  $opt->mode eq 'get';
+
+B<Note>: C<get> would not be set if C<mode> defaulted to 'get' and no arguments
+were passed in.
+
+Even though the option sub-specs for C<one_of> are meant to be 'first
+class' specs, some options don't make sense with them, e.g. C<required>.
+
+As a further shorthand, you may specify C<one_of> options using this form:
 
   [ mode => \@option_specs, \%constraints ]
 
-=head3 Params::Validate
+=item Params::Validate
 
 In addition, any constraint understood by Params::Validate may be used.
 
 (Internally, all constraints are translated into Params::Validate options or
 callbacks.)
 
-=head1 EXTRA ARGUMENTS
-
-If the last parameter is a hashref, it contains extra arguments to modify the
-way C<describe_options> works.  Valid arguments are:
+=back
+
+=head3 arg
+
+The C<%arg> to C<describe_options> is optional.  If the last parameter is a
+hashref, it contains extra arguments to modify the way C<describe_options>
+works.  Valid arguments are:
 
   getopt_conf - an arrayref of strings, passed to Getopt::Long::Configure
 
-=head1 EXPORTED FUNCTIONS
-
-=head2 C<describe_options>
-
-See SYNOPSIS; returns a hashref of option values and an object that represents
-the usage statement.  You should always import this routine, and not call it
-directly.  The ability to call C<Getopt::Long::Descriptive::describe_options>
-may go away in the future.
-
-The usage object has several methods:
-
-=over 4
-
-=item * C<< $usage->text >> returns the usage string
-
-=item * C<< $usage->warn >> prints usage to STDERR
-
-=item * C<< $usage->die >> dies with the usage string
-
-=back
-
-For more information on the usage object, look at
-L<Getopt::Long::Descriptive::Usage|Getopt::Long::Descriptive::Usage>.
-
 =head2 prog_name
 
-This routine returns the basename of C<< $0 >>, grabbed at compile-time.
-
-=head2 -types
+This routine, exported on demand, returns the basename of C<$0>, grabbed at
+compile-time.  You can override this guess by calling C<prog_name($string)>
+yourself.
+
+=head1 OTHER EXPORTS
+
+=head2 C<-types>
 
 Any of the Params::Validate type constants (C<SCALAR>, etc.) can be imported as
 well.  You can get all of them at once by importing C<-types>.
 
 =head2 C<-all>
 
-This gets you everything.
-
-=head1 CONFIGURATION
-
-=head2 C<$MungeOptions>
-
-When C<$Getopt::Long::Descriptive::MungeOptions> is true, some munging is done
-to make option names more hash-key friendly:
-
-=over 4
-
-=item * All keys are lowercased
-
-=item * C<-> is changed to C<_>
-
-=back
-
-The default is a true value.
-
-=head1 SEE ALSO
-
-L<Getopt::Long>
-L<Params::Validate>
+This import group will import C<-type>, C<describe_options>, and C<prog_name>.
 
 =cut
 
@@ -530,9 +567,16 @@
 This returns the class to be used for constructing a Usage object, and defaults
 to Getopt::Long::Descriptive::Usage.
 
-=head1 AUTHOR
+=head1 SEE ALSO
+
+L<Getopt::Long>
+L<Params::Validate>
+
+=head1 AUTHORS
 
 Hans Dieter Pearcey, C<< <hdp at cpan.org> >>
+
+Ricardo Signes, C<< <rjbs at cpan.org> >>
 
 =head1 BUGS
 

Modified: branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive/Opts.pm
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive/Opts.pm?rev=54284&op=diff
==============================================================================
--- branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive/Opts.pm (original)
+++ branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive/Opts.pm Sun Mar 14 03:46:36 2010
@@ -10,11 +10,11 @@
 
 =head1 VERSION
 
-Version 0.084
+Version 0.085
 
 =cut
 
-our $VERSION = '0.084';
+our $VERSION = '0.085';
 
 =head1 DESCRIPTION
 

Modified: branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive/Usage.pm
URL: http://svn.debian.org/wsvn/pkg-perl/branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive/Usage.pm?rev=54284&op=diff
==============================================================================
--- branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive/Usage.pm (original)
+++ branches/upstream/libgetopt-long-descriptive-perl/current/lib/Getopt/Long/Descriptive/Usage.pm Sun Mar 14 03:46:36 2010
@@ -2,7 +2,7 @@
 use strict;
 use warnings;
 
-our $VERSION = '0.084';
+our $VERSION = '0.085';
 
 use List::Util qw(max);
 




More information about the Pkg-perl-cvs-commits mailing list