Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Getopt::Compact(3)    User Contributed Perl Documentation   Getopt::Compact(3)

NAME
       Getopt::Compact - getopt	processing in a	compact	statement with both
       long and	short options, and usage functionality.

SYNOPSIS
       inside foobar.pl:

	   use Getopt::Compact;

	   # (1) simple	usage:
	   my $opts = new Getopt::Compact
	       (struct =>
		[[[qw(b	baz)], qq(baz option)],	 # -b or --baz
		 ["foobar", qq(foobar option)],	 # --foobar only
		])->opts();

	   # (2) or, a more advanced usage:
	   my $go = new	Getopt::Compact
	       (name =>	'foobar	program', modes	=> [qw(verbose test debug)],
		struct =>
		[[[qw(w	wibble)], qq(specify a wibble parameter), ':s'],
		 [[qw(f	foobar)], qq(apply foobar algorithm)],
		 [[qw(j	joobies)], qq(jooby integer list), '=i', \@joobs],
		]
	       );
	   my $opts = $go->opts;

	   print "applying foobar algorithm\n" if $opt->{foobar};
	   print "joobs: @joobs\n" if @joobs;
	   print $go->usage if MyModule::some_error_condition($opts);

       using (2), running the command './foobar.pl -x' results in the
       following output:

	   Unknown option: x
	   foobar program v1.0
	   usage: foobar.pl [options]
	   options
	   -h, --help	   This	help message
	   -v, --verbose   Verbose mode
	   -n, --test	   Test	mode
	   -d, --debug	   Debug mode
	   -w, --wibble	   Specify a wibble parameter
	   -f, --foobar	   Apply foobar	algorithm
	   -j, --joobies   Jooby integer list
	       --man	   Display documentation

DESCRIPTION
       This is yet another Getopt related module.  Getopt::Compact is geared
       towards compactly and yet quite powerfully describing an	option syntax.
       Options can be parsed, returned as a hashref of values, and/or
       displayed as a usage string or within the script	POD.

PUBLIC METHODS
       new()
	       my $go =	new Getopt::Compact(%options)

	   Instantiates	a Getopt::Compact object.  This	will parse the command
	   line	arguments and store them for later retrieval (via the opts()
	   method).  On	error a	usage string is	printed	and exit() is called,
	   unless you have set the 'usage' option to false.

	   The following constructor options are recognised:

	   "name"
	       The name	of the program.	 This is printed at the	start of the
	       usage string.

	   "cmd"
	       The command used	to execute this	program.  Defaults to $0.
	       This will be printed as part of the usage string.

	   "version"
	       Program version.	 Can be	an RCS Version string, or any other
	       string.	Displayed in usage information.	 The default is
	       ($main::VERSION || '1.0')

	   "usage"
	       'usage' is set to true by default.  Set it to false (0) to
	       disable the default behaviour of	automatically printing a usage
	       string and exiting when there are parse errors or the --help
	       option is given.

	   "args"
	       A string	describing mandatory arguments to display in the usage
	       string.	eg:

		   print new Getopt::Compact
		       (args =>	'foo', cmd => 'bar.pl')->usage;

	       displays:

		   usage: bar.pl [options] foo

	   "modes"
	       This is a shortcut for defining boolean mode options, such as
	       verbose and test	modes.	Set it to an arrayref of mode names,
	       eg [qw(verbose test)].  The following statements	are
	       equivalent:

		   # longhand version
		   my $go = new	Getopt::Compact
		       (struct => [[[qw(v verbose)], qw(verbose	mode)],
				   [[qw(n test)],    qw(test mode)],
				   [[qw(d debug)],   qw(debug mode)],
				   [[qw(f foobar)],  qw(activate foobar)],
				  ]);

	       and

		   # shorthand version
		   my $go = new	Getopt::Compact
		       (modes => [qw(verbose test debug)],
			struct => [[[qw(f foobar)], qq(activate	foobar)]]);

	       Mode options will be prepended to any options defined via the
	       'struct'	option.

	   "struct"
	       This is where most of the option	configuration is done.	The
	       format for a struct option is an	arrayref of arrayrefs (see
	       "SYNOPSIS") in the following form (where	[ ] denotes an array
	       reference):

		   struct => [optarray,	optarray, ...]

	       and each	optarray is an array reference in the following	form:
	       (only 'name specification' is required)

		   [name spec, description, argument spec, destination]

	       name specification may be a scalar string, eg "length", or a
	       reference to an array of	alternate option names,	eg [qw(l
	       length)].  The option name specification	is also	used to
	       determine the key to the	option value in	the hashref returned
	       by "opts()".  See "opts()" for more information.

	       The argument specification is passed directly to	Getopt::Long,
	       so any syntax recognised	by Getopt::Long	should also work here.
	       Some argument specifications are:

		   =s  Required	string argument
		   :s  Optional	string argument
		   =i  Required	integer	argument
		   +   Value incrementing
		   !   Negatable option

	       Refer to	Getopt::Long documentation for more details on
	       argument	specifications.

	       The 'destination' is an optional	reference to a variable	that
	       will hold the option value.  If destination is not specified it
	       will be stored internally by Getopt::Compact and	can be
	       retrieved via the opts()	method.	 This is useful	if you want
	       options to accept multiple values.  The only way	to achieve
	       this is to use a	destination that is a reference	to a list (see
	       the joobies option in "SYNOPSIS"	by way of example).

	   "configure"
	       Optional	configure arguments to pass to Getopt::Long::Configure
	       in the form of a	hashref	of key,	boolean	value pairs.  By
	       default,	the following configuration is used:

	       { no_auto_abbrev	=> 1, bundling => 1 }

	       To disable bundling and have case insensitive single-character
	       options you would do the	following:

	       new Getopt::Compact
		   (configure => { ignorecase_always =>	1, bundling => 0 });

	       see Getopt::Long	documentation for more information on
	       configuration options.

       $go->usage()
	       print $go->usage();

	   Returns a usage string.  Normally the usage string will be printed
	   automatically and the program will exit if the user supplies	an
	   unrecognised	argument or if the -h or --help	option is given.
	   Automatic usage and exiting can be disabled by setting 'usage' to
	   false (0) in	the constructor	(see new()).  This method uses
	   Text::Table internally to format the	usage output.

	   The following options may be	automatically added by
	   Getopt::Compact:

	   "This help message" (-h or --help)
	       A help option is	automatically prepended	to the list of
	       available options if the	"usage"	constructor option is true
	       (this is	enabled	by default).  When invoked with	-h or --help,
	       Getopt::Compact automatically displays the usage	string and
	       exits.

	   "Display documentation" (--man)
	       This option is appended to the list of available	options	unless
	       an alternative --man option has been defined.  When invoked
	       with --man, Getopt::Compact prints a modified version of	its
	       POD to stdout and exits.

       $go->pod2usage()
	   Displays the	POD for	the script.  The POD will be altered to
	   include "USAGE", "NAME" and "VERSION" sections unless they already
	   exist.  This	is invoked automatically when the --man	option is
	   given.

       $go->status()
	       print "getopt ".($go->status ? 'success'	: 'error'),"\n";

	   The return value from Getopt::Long::Getoptions(). This is a true
	   value if the	command	line was processed successfully. Otherwise it
	   returns a false result.

       $go->opts()
	       $opt = $go->opts;

	   Returns a hashref of	options	keyed by option	name.  If the
	   constructor usage option is true (on	by default), then a usage
	   string will be printed and the program will exit if it encounters
	   an unrecognised option or the -h or --help option is	given.

	   The key in %$opt for	each option is determined by the option	names
	   in the specification	used in	the "struct" definition.  For example:

	   ["foo", qw(foo option)]
	       The key will be "foo".

	   [[qw(f foo)], qw(foo	option)]
	   [[qw(f foo foobar)],	qw(foo option)]
	       In both cases the key will be "foo".  If	multiple option	names
	       are given, the first long option	name (longer than one
	       character) will be used as the key.

	   [[qw(a b)], qq(a or b option)]
	       The key here will be "a".  If all alternatives are one
	       character, the first option name	in the list is used as the key

AUTHOR
       Andrew Stewart Williams

SEE ALSO
       Getopt::Long

perl v5.32.0			  2006-09-04		    Getopt::Compact(3)

NAME | SYNOPSIS | DESCRIPTION | PUBLIC METHODS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Getopt::Compact&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help