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

FreeBSD Manual Pages

  
 
  

home | help
Getargs::Long(3)      User Contributed Perl Documentation     Getargs::Long(3)

NAME
       Getargs::Long - Named subroutine	arguments, with	optional type checking

SYNOPSIS
	use Getargs::Long;		       # case sensitive
	use Getargs::Long qw(ignorecase);      # case insensitive

	# Simple, args mandatory
	my ($val, $other) = getargs(@_,	qw(val other));

	# Simple, args optional	(in [] means optional)
	my ($val, $other) = getargs(@_,	[qw(val	other)]);

	# Simple with typechecking, args mandatory
	my ($val, $other) = getargs(@_,	qw(val=Class::X	other=ARRAY));

	# Simple with typechecking, args optional
	my ($val, $other) = getargs(@_,	[qw(val=Class::X other=ARRAY)]);

	# Faster version, building dedicated argument parsing routine
	my ($val, $other) = cgetargs(@_, qw(val	other));

	# Other	cases, use full	specs:
	my ($x,	$y, $z,	$a, $b,	$c) = xgetargs(@_,

	   # Non-mandatory, defaults to	undef unless specified otherwise
	   'x'	   => ['i'],		       # integer, no default
	   'y'	   => ['ARRAY',	['a', 'b']],   # Has a default
	   'z'	   => [],		       # No typecheck, can be anything

	   # Mandatory arguments
	   'a'	   => 'i',		       # integer (scalar)
	   'b'	   => 'TYPE',		       # TYPE or any heir of TYPE
	   'c'	   => undef,		       # unspecified type but mandatory
	);

	# Extract remaining unparsed args in @extra
	my ($val, $other, @extra) = getargs(@_,	{ -strict => 0 }, qw(val other));

	# Alter	behaviour of the getargs() routines via	switches in hashref
	my ($val, $other) = getargs(@_,
	   {
	       -strict	       => 1,	   # unknown switches are fatal
	       -ignorecase     => 1,	   # override package's	global
	       -inplace	       => 1,	   # edit @_ inplace: remove parsed args
	       -extra	       => 0,	   # suppress return of	extra arguments
	   },
	   qw(val other)
	);

DESCRIPTION
       The "Getargs::Long" module allows usage of named	parameters in function
       calls, along with optional argument type-checking.  It provides an easy
       way to get at the parameters within the routine,	and yields concise
       descriptions for	the common cases of all-mandatory and all-optional
       parameter lists.

       The validation of arguments can be done by a structure-driven routine
       getargs() which is fine for infrequently	called routines	(but should be
       slower),	or via a dedicated routine created and compiled	on the fly the
       fist time it is needed, by using	the cgetargs() family (expected	to be
       faster).

       The "Log::Agent"	module is used to report errors, which leaves to the
       application the choice of the final logging method: to a	file, to
       STDERR, or to syslog.

EXAMPLES
       Before going through the	interface specification, a little example will
       help illustrate both caller and callee sides.  Let's write a routine
       that can	be called as either:

	f(-x =>	1, -y => 2, -z => 3);  # -switch form
	f(x => 1, y => 2, z => 3);     # concise form (- are optional)
	f(y => 1, x => 2);	       # order changed,	z may be omitted

       Since we	have an	optional parameter z but mandatory x and y, we can't
       use the short form of getargs() and must	therefore use xgetargs():

	sub f {
	    my ($x, $y ,$z) = xgetargs(@_,
		-x => 'i',	       # mandatory, integer
		-y => 'i',	       # mandatory, integer
		-z => ['i', 0],	       # optional integer, defaults to 0
	    );
	    # code use $x, $y, $z
	}

       That's quite simple and direct if you think of [] as "optional".	 Note
       that we pass xgetargs() a reference to @_.

       If we had all arguments mandatory and wished to nonethless benefit from
       the named specification at call time to avoid having the	caller
       remember	the exact parameter ordering, we could write:

	sub f {
	    my ($x, $y ,$z) = getargs(@_, qw(x=i y=i z=i));
	    # code of f
	}

       Without parameter type checking,	that would be even more	concise.
       Besides,	if f() is frequently called, it	might be more efficient	to
       build a routine dynamically to parse the	arguments rather than letting
       getargs() parse the same	data structures	again and again:

	sub f {
	    my ($x, $y ,$z) = cgetargs(@_, qw(x	y z));	  # 'c'	for cached/compiled
	    # code of f
	}

       If you call f() with an improper	argument, logcroak() will be called to
       issue an	exception from the persepective	of the caller, i.e. pointing
       to the place f()	is called instead of within f()	at the getargs() call,
       which would be rather useless.

       Here are	some more examples:

       Example 1 -- All	mandatory:

	  sub f	{
	      my ($port, $server) = getargs(@_,
		  qw(port=i server=HTTP::Server));
	  }

	  f(-server => $server,	port =>	80);  #	or -port, since	- is optional
	  f(port => 80,	server => $server);
	  f(server => $server);		      #	WRONG: missing mandatory -port
	  f(server => 80, port => 80);	      #	WRONG: -server not an HTTP::Server
	  f(server => undef, port => 80);     #	WRONG: -server cannot be undef

       Example 2 -- All	optional

	  sub cmd {
	      my ($a, $o) = getargs(@_,	[qw(a o=s)]);
	  }

	  cmd();		      #	OK
	  cmd(-a => undef);	      #	OK -a accepts anything,	even undef
	  cmd(-a => 1, -o => "..");   #	OK
	  cmd(-a => 1, -o => undef);  #	WRONG: -o does not accept undef
	  cmd(-x => 1);		      #	WRONG: -x is not a known argument name

       Example 3  -- Mixed optional / mandatory

	  sub f	{
	      my ($x, $z) = xgetargs(@_,
		  -x  => 'i',		      #	-x mandatory integer
		  -z  => ['n', -20.4],	      #	-z optional, defaults to -20.4
	      );
	  }

	  f(x => 1, z => {});	  # WRONG: z is	not a numerical	value
	  f(z => 1, x => -2);	  # OK
	  f(-z => 1);		  # WRONG: mandatory x is missing
	  f(-z => undef);	  # WRONG: z cannot be undef

       Example 4 -- Parsing options

	  sub f	{
	      my ($x, $z) = xgetargs(@_,
		  { -strict => 0, -ignorecase => 1 },
		  -x  => 'i',		      #	-x mandatory integer
		  -z  => ['n', -20.4],	      #	-z optional, defaults to -20.4
	      );
	  }

	  f(x => 1, foo	=> {});	  # OK,	-foo ignored since not strict
	  f(-X => 1);		  # OK,	-X actually specifies -x with ignorecase

INTERFACE
       All the routines	take a mandatory first argument, called	arglist, which
       is the array containing the named arguments for the routine (i.e. a
       succession of name => value tuples).  This array	is implicitely passed
       as reference, and will usually be given as @_.

       All the routines	take an	optional options argument which	comes in the
       second place.  It is an hash reference containing named options that
       alter the behaviour of the routine.  More details given in the Options
       section.

       All the routines	return a list of the arguments in the order they are
       specified, each slot in the list	being either the argument value, if
       present,	or "undef" if missing (and not mandatory).

   Simple Cases
       Simple cases are	handled	by getargs(): named arguments should either be
       all mandatory or	all optional, and there	is no provision	for specifying
       a default value for optional parameters.

       The getargs() routine and its cousin cgetargs() have two	different
       interfaces, depending on	whether	the arguments are all mandatory	or all
       optional.  We'll	only specify for getargs(), but	the signature of
       cgetargs() is identical.

       getargs arglist,	options, arg_spec1, arg_spec2, ...
	   We'll be ignoring the options argument from our discussion.	See
	   the Options section for details.

	   All the routine formal arguments specified by arg_spec1, arg_spec2,
	   etc... are mandatory.  If arg_spec1 is only a name, then it
	   specifies a mandatory formal	argument of that name, which can be of
	   any type, even undef.  If the name is followed by "=type" then
	   "type" specifies the	argument type: usually a reference type,
	   unless 'i', 'n' or 's' is used for integer, natural and string
	   scalars.

	   Currently, types 'i', 'n' and 's' all mean the same thing: that the
	   argument must be a scalar.  A future	implementation will probably
	   ensure 'i' and 'n' hold integers and	natural	numbers	respectively,
	   's' being the placeholder for anything else that is defined.

	   For instance:

	       foo		 expects mandatory "foo" of "-foo" argument (undef ok)
	       foo=s		 idem, and argument cannot be undef or reference
	       foo=i		 value of argument -foo	must be	an integer
	       foo=My::Package	 foo is	a blessed object, inheriting from My::Package
	       foo=ARRAY	 foo is	an ARRAY reference

	   The rule for	determing whether "foo=X" means	"foo" is a reference
	   "X" or "foo"	is an object whose class is an heir of "X" depends on
	   the argument	value at runtime: if it	is an unblessed	ref, strict
	   reference equality is expected.  If it is a blessed ref, type
	   conformance is based	on inheritance,	as you would expect.

	   Example:

	       sub f {
		   my ($port, $server) = getargs(@_,
		       qw(port=i server=HTTP::Server));
	       }

	   Some	calls:

	       f(-server => $server, port => 80);  # or	-port, since - is optional
	       f(port => 80, server => $server);
	       f(server	=> $server);		   # WRONG: missing mandatory -port
	       f(server	=> 80, port => 80);	   # WRONG: -server not	an HTTP::Server
	       f(server	=> undef, port => 80);	   # WRONG: -server cannot be undef

	   By default, named argument processing is case-sensitive but there
	   is an option	to ignore case.

       getargs arglist,	options, array_ref
	   This	form specifies that all	the formal arguments specified in the
	   array_ref are optional.  Think of the '[' and ']' (which you'll
	   probably use	to supply the reference	as a manifest constant)	as
	   syntactic markers for optional things.  In the traditional Unix
	   command line	description, something like:

	       cmd [-a]	[-o file]

	   typically denotes that options "-a" and "-o"	are optional, and that
	   "-o"	takes one argument, a file name.  To specify the same things
	   for routine arguments using getargs():

	       sub cmd {
		   my ($a, $o) = getargs(@_, [qw(a o=s)]);
	       }

	   Here	however, the "-a" argument can be anything: we're not
	   specifying switches,	we're specifying named arguments.  Big
	   difference.

	   Some	calls:

	       cmd();			   # OK
	       cmd(-a => undef);	   # OK	-a accepts anything, even undef
	       cmd(-a => 1, -o => "..");   # OK
	       cmd(-a => 1, -o => undef);  # WRONG: -o does not	accept undef
	       cmd(-x => 1);		   # WRONG: -x is not a	known argument name

	   It is important to note that	there can only be tuples when using
	   named arguments, which means	that the routine is called with	an
	   even	number of arguments.  If you forget a "," separator between
	   arguments, getargs()	will complain about an odd number of arguments
	   (provided the resulting code	still parses as	valid Perl, naturally,
	   or you'll never get a chance	to reach the execution of getargs()
	   anyway).

       cgetargs	same args as getargs
	   The cgetargs() routine behaves exactly as the getargs() routine: it
	   takes the same arguments, returns the same list.  The only
	   difference is that the first	time it	is called, it builds a routine
	   to process the arguments, and then calls it.

	   On subsequent calls to cgetargs() for the same routine, the cached
	   argument parsing routine is re-used to analyze the arguments.  For
	   frequently called routines, this might be a win, even though	Perl
	   still needs to construct the	argument list to cgetargs() and	call
	   it.

   Complex Cases
       The xgetargs() routine and its cousin cxgetargs() (for the caching
       version)	allow for a more verbose description of	named parameters which
       allows specifying arguments that	are mandatory or optional, and also
       give default values to optional arguments.

       xgetargs	arglist, options, name => type,	...
	   We'll be ignoring the options argument from our discussion.	See
	   Options for details.

	   There can be	as many	name =>	type tuples as necessary to describe
	   all the formal arguments of the routine.  The name refers to	the
	   argument name, and type specifies both the mandatory	nature and the
	   expected type.  You may use name or -name to	specify	an argument
	   called name,	and the	caller will also be able to spell it as	he
	   wishes.  The	type is	encoded	as follows:

	       "i"	mandatory integer (scalar)
	       "s"	mandatory string (scalar)
	       "TYPE"	mandatory ref of type TYPE, or heir of type TYPE
	       undef	unspecified type, but mandatory	argument
	       ["i"]	optional integer
	       ["s"]	optional string
	       ["TYPE"]	optional ref of	type TYPE, or heir of type TYPE

	   For optional	parameter, an optional second value may	be inserted in
	   the list to specify a default value.	 For instance, the tupple:

	       'y' => ['HASH', { a => 1, b => 2	}]

	   specifies an	optional named argument	y, which is expected to	be a
	   HASH	reference, and whose default value is the hash given.

	   You may specify an expression as default value instead of giving a
	   manifest constant, but BEWARE: the cxgetargs() routine will take a
	   snapshot of your expression when building its analyzing routine.
	   It's	of no consequence when using a manifest	constant, but when
	   using an expression,	it will	be evaluated once and the result of
	   that	evaluation will	be taken as the	manifest constant to use
	   subsequently	(and this does not mean	the same reference will	be
	   returned, only the same topological structure as the	one we
	   evaluated during caching).

	   Example:

	       sub f {
		   my ($x, $z) = cxgetargs(@_,
		       -x  => 'i',		   # -x	mandatory integer
		       -z  => ['n', -20.4],	   # -z	optional, defaults to -20.4
		   );
	       }

	       f(x => 1, z => {});     # WRONG:	z is not a numerical value
	       f(z => 1, x => -2);     # OK
	       f(-z => 1);	       # WRONG:	mandatory x is missing
	       f(-z => undef);	       # WRONG:	z cannot be undef

	   Remember that we are	dealing	with named parameters for a routine
	   call, not with option parsing.  Therefore, we are always expecting
	   an even number of arguments,	and those arguments are	tuples name =>
	   value.

   Options
       All the getargs() and xgetargs()	routines take an optional hash
       reference as second argument.  Keys in this hash	define options that
       apply locally to	the call.  In the case of caching routines, e.g.
       cxgetargs(), the	options	are only considered the	first time, when the
       analyzing routine is built, and are ignored on subsequent calls.
       Therefore, it is	wise to	use manifest constants when specifying
       options,	or use the non-caching function	family instead if your options
       need to be dynamically computed (please,	don't do that).

       Options given there must	be spelled out with the	leading	"-" and	are
       case sensitive.	To enable an option, give a true value.	 For instance:

	   sub f {
	       my ($x, $z) = cxgetargs(@_,
		   { -strict =>	0, -ignorecase => 1 },
		   -x  => 'i',		       # -x mandatory integer
		   -z  => ['n',	-20.4],	       # -z optional, defaults to -20.4
	       );
	   }

       supplies	two options, turning "-ignorecase" on and "-strict" off.

       The available options are, in alphabetical order:

       -extra
	   Whether to report extra unknown arguments at	the end	of the
	   argument list.  Example:

	       my ($x, $y, @extra) = getargs(@_,
		   { -extra => 1, -strict => 0 }, qw(x y));

	   Your	setting	is forced to false when	"-strict" is true.  The
	   default value is the	negation of the	boolean	"-strict" setting,
	   which means the above can be	rewritten as:

	       my ($x, $y, @extra) = getargs(@_, { -strict => 0	}, qw(x	y));

	   which will implicitely set -extra to	be true.  This is usually what
	   you want when not strict, i.e. get at the other parameters.
	   Assuming we were writing the	above for a function f(), calling:

	       f(-x => 1, -y =>	2, -other => 5);

	   would set:

	       @extra =	(-other	=> 5);

	   An alternative when you are not strict is to	make use of the
	   "-inplace" option to	edit @_	inplace.

       -ignorecase
	   Turn	case-insensitive named parameters.  False by default.
	   Actually, if	not explicitely	specified, the default setting depends
	   on the way "Getargs::Long" was imported within the package scope.
	   If you said:

	       use Getargs::Long;

	   then	the default is indeed to be case-sensitive.  However, if you
	   said:

	       use Getargs::Long qw(ignorecase);

	   then	the default for	the package scope is to	be case-insensitive.
	   You may still specify the "-ignorecase" option to force case
	   sensitivity on a per-routine	basis, although	I would	never do such
	   a thing and stick to	a uniform case sensitivity on a	package	basis.

       -inplace
	   Whether to edit the routine's argument list inplace,	removing
	   processed arguments as they are found and leaving unprocessed ones.
	   False by default.

	   Your	setting	is forced to false when	"-strict" is true, naturally,
	   since an unknown argument is	an error.

       -strict
	   Whether unknown named parameters are	fatal.	True by	default.  When
	   "-strict" is	true, the "-inplace" and "-extra" options you may
	   specify are ignored and forced to false.

BUGS
       Currently, types	'i', 'n' and 's' all mean the same thing, but that
       will change.  Don't take	the current implementation's deficiency	as an
       excuse for lamely specifying your scalar	types.

       You must	be careful in this implementation to list options and
       variables in the	very same order.  Some day, I will probably add
       another routine to take arguments the way "Getopt::Long"	does to	cope
       with this ordering problem (but it forces to spell out variables	twice
       -- once for declaration,	and once for specifying	a pointer to it).

RELATED	MODULE
       See Params::Validate for	another	take at	parameter validation.  It is a
       completely independant module, developped by Dave Rolsky, which may
       also interest you.  Its interface and purpose are different though.

LICENSE
       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself. See	the file LICENSE in the
       distribution for	details.

AUTHOR
       The original code (written before September 15, 2004) was written by
       Raphael Manfredi	<Raphael_Manfredi@pobox.com>.

       Maintenance of this module is now being done by David Coppit
       <david@coppit.org>.

SEE ALSO
       Log::Agent, Params::Validate

perl v5.24.1			  2015-04-20		      Getargs::Long(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | INTERFACE | BUGS | RELATED MODULE | LICENSE | AUTHOR | SEE ALSO

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

home | help