Getopt::EX::Hashed - Hash store object automation for Getopt::Long
Version 1.0503
# script/foo use App::foo; App::foo->new->run(); # lib/App/foo.pm package App::foo; use Getopt::EX::Hashed; { Getopt::EX::Hashed->configure( DEFAULT => [ is => 'rw' ] ); has start => ' =i s begin ' , default => 1; has end => ' =i e ' ; has file => ' =s@ f ' , any => qr/^(?!\.)/; has score => ' =i ' , min => 0, max => 100; has answer => ' =i ' , must => sub { $_[1] == 42 }; has mouse => ' =s ' , any => [ 'Frankie', 'Benjy' ]; has question => ' =s ' , any => qr/^(life|universe|everything)$/i; } no Getopt::EX::Hashed; sub run { my $app = shift; use Getopt::Long; $app->getopt or pod2usage(); if ($app->answer == 42) { $app->question //= 'life'; ...
Getopt::EX::Hashed is a module to automate a hash object to store command line option values for Getopt::Long and compatible modules including Getopt::EX::Long. Module name shares Getopt::EX, but it works independently from other modules in Getopt::EX, so far.
Major objective of this module is integrating initialization and specification into single place. It also provides simple validation interface.
Accessor methods are automatically generated when is parameter is given. If the same function is already defined, the program causes fatal error. Accessors are removed when the object is destroyed. Problems may occur when multiple objects are present at the same time.
is
Declare option parameters in a form of:
has option_name => ( param => value, ... );
If array reference is given, multiple names can be declared at once.
has [ 'left', 'right' ] => ( spec => "=i" );
If the name start with plus (+), given parameter updates values.
+
has '+left' => ( default => 1 );
As for spec parameter, label can be omitted if it is the first parameter.
spec
has left => "=i", default => 1;
If the number of parameter is not even, default label is assumed to be exist at the head: action if the first parameter is code reference, spec otherwise.
action
Following parameters are available.
Give option specification. spec => label can be omitted if and only if it is the first parameter.
spec =>
In string, option spec and alias names are separated by white space, and can show up in any order. Declaration
has start => "=i s begin";
will be compiled into string:
start|s|begin=i
which conform to Getopt::Long definition. Of course, you can write as this:
Getopt::Long
has start => "s|begin=i";
If the name and aliases contain underscore (_), another alias name is defined with dash (-) in place of underscores. So
_
-
has a_to_z => "=s";
will be compiled into:
a_to_z|a-to-z=s
If nothing special is necessary, give empty (or white space only) string as a value. Otherwise, it is not considered as an option.
Additional alias names can be specified by alias parameter too. There is no difference with ones in spec parameter.
has start => "=i", alias => "s begin";
ro
rw
To produce accessor method, is parameter is necessary. Set the value ro for read-only, rw for read-write.
Read-write accessor has lvalue attribute, so it can be assigned to. You can use like this:
$app->foo //= 1;
which is simpler than:
$app->foo(1) unless defined $app->foo;
If you want to make accessor for all following members, use configure to set DEFAULT parameter.
configure
DEFAULT
Getopt::EX::Hashed->configure( DEFAULT => [ is => 'rw' ] );
If you don't like assignable accessor, configure ACCESSOR_LVALUE parameter to 0. Because accessor is generated at the time of new, this value is effective for all members.
ACCESSOR_LVALUE
new
Set default value. If no default is given, the member is initialized as undef.
undef
If the value is a reference for ARRAY or HASH, new reference with same member is assigned. This means that member data is shared across multiple new calls. Please be careful if you call new multiple times and alter the member data.
If a code reference is given, it is called at the time of new to get default value. This is effective when you want to evaluate the value at the time of execution, rather than declaration. Use action parameter to define a default action.
Parameter action takes code reference which is called to process the option. action => label can be omitted if and only if it is the first parameter.
action =>
When called, hash object is passed as $_.
$_
has [ qw(left right both) ] => '=i'; has "+both" => sub { $_->{left} = $_->{right} = $_[1]; };
You can use this for "<>" to catch everything. In that case, spec parameter does not matter and not required.
"<>"
has ARGV => default => []; has "<>" => sub { push @{$_->{ARGV}}, $_[0]; };
Following parameters are all for data validation. First must is a generic validator and can implement anything. Others are shortcut for common rules.
must
Parameter must takes a code reference to validate option values. It takes same arguments as action and returns boolean. With next example, option --answer takes only 42 as a valid value.
has answer => '=i', must => sub { $_[1] == 42 };
If multiple code reference is given, all code have to return true.
has answer => '=i', must => [ sub { $_[1] >= 42 }, sub { $_[1] <= 42 } ];
Set the minimum and maximum limit for the argument.
Set the valid string parameter list. Each item is a string or a regex reference. The argument is valid when it is same as, or match to any item of the given list. If the value is not an arrayref, it is taken as a single item list (regexpref usually).
Following declarations are almost equivalent, except second one is case insensitive.
has question => '=s', any => [ 'life', 'universe', 'everything' ]; has question => '=s', any => qr/^(life|universe|everything)$/i;
If you are using optional argument, don't forget to include default value in the list. Otherwise it causes validation error.
has question => ':s', any => [ 'life', 'universe', 'everything', '' ];
Class method to get initialized hash object.
Return option specification list which can be given to GetOptions function.
GetOptions
GetOptions($obj->optspec)
GetOptions has a capability of storing values in a hash, by giving the hash reference as a first argument, but it is not necessary.
Call appropriate function defined in caller's context to process options.
$obj->getopt $obj->getopt(\@argv);
are shortcut for:
GetOptions($obj->optspec) GetOptionsFromArray(\@argv, $obj->optspec)
Because hash keys are protected by Hash::Util::lock_keys, accessing non-existent member causes an error. Use this function to declare new member key before use.
Hash::Util::lock_keys
$obj->use_keys( qw(foo bar) );
If you want to access arbitrary keys, unlock the object.
use Hash::Util 'unlock_keys'; unlock_keys %{$obj};
You can change this behavior by configure with LOCK_KEYS parameter.
LOCK_KEYS
Use class method Getopt::EX::Hashed->configure() before creating an object; this information is stored in the area unique for calling package. After calling new(), package unique configuration is copied in the object, and it is used for further operation. Use $obj->configure() to update object unique configuration.
Getopt::EX::Hashed->configure()
new()
$obj->configure()
There are following configuration parameters.
Lock hash keys. This avoids accidental access to non-existent hash entry.
Produce alias with underscores replaced by dash.
Produce alias with underscores removed.
Set function name called from getopt method.
getopt
When specified, it is prepended to the member name to make accessor method. If ACCESSOR_PREFIX is defined as opt_, accessor for member file will be opt_file.
ACCESSOR_PREFIX
opt_
file
opt_file
If true, read-write accessors have lvalue attribute. Set zero if you don't like that behavior.
Set default parameters. At the call for has, DEFAULT parameters are inserted before argument parameters. So if both include same parameter, later one in argument list has precedence. Incremental call with + is not affected.
has
Typical use of DEFAULT is is to prepare accessor method for all following hash entries. Declare DEFAULT => [] to reset.
DEFAULT => []
Getopt::EX::Hashed->configure(DEFAULT => [ is => 'ro' ]);
Reset the class to the original state.
Getopt::EX, Getopt::EX::Long
Kazumasa Utashiro
The following copyright notice applies to all the files provided in this distribution, including binary files, unless explicitly noted otherwise.
Copyright 2021-2022 Kazumasa Utashiro
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Getopt::EX::Hashed, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Getopt::EX::Hashed
CPAN shell
perl -MCPAN -e shell install Getopt::EX::Hashed
For more information on module installation, please visit the detailed CPAN module installation guide.