Provided by: libmoox-options-perl_3.83-1_all 
NAME
MooX::Options - add option keywords to your object (Mo/Moo/Moose)
VERSION
version 3.83
MooX::Options
Use Getopt::Long::Descritive to provide command line option for your Mo/Moo/Moose Object.
This module will add "option" which act as "has" but support additional feature for
getopt.
You will have "new_with_options" to instanciate new object for command line.
METHOD
IMPORT
The import method can take option :
%options
flavour
pass extra arguments for Getopt::Long::Descriptive. it is usefull if you want to
configure Getopt::Long.
use MooX::Options flavour => [qw( pass_through )];
Any flavour is pass to Getopt::Long as a configuration, check the doc to see what
is possible.
protect_argv
by default, argv is protected. if you want to do something else on it, use this
option and it will change the real argv.
use MooX::Options protect_argv => 0;
skip_options
you can skip some option to remove the possibility to the terminal. in that case,
the 'option' keyword will just works like an 'has'.
use MooX::Options skip_options => [qw/multi/];
If you have multiple tools that use the same Role to generate params, you can skip
one and force his value. In my example, it could be a multithread option that you
want to disabling in some case.
prefer_commandline
By default, arguments to new_with_options() are used in preference of items
provided via command line options.
You may enable the "prefer_commandline" option to reverse this behaviour; this
allows you to provide some default values to new_with_options() and override them
on the command line.
{
package t;
use Moo;
use MooX::Options prefer_commandline => 1;
option 'test' => (is => 'ro');
1;
}
# parse ARGV for options but default to those provided here
my $t = t->new_with_options( test => 'default' );
USAGE
First of all, I use Getopt::Long::Descriptive. Everything will be pass to the programs,
more specially the format.
{
package t;
use Moo;
use MooX::Options;
option 'test' => (is => 'ro');
1;
}
my $t = t->new_with_options(); #parse @ARGV
my $o = t->new_with_options(test => 'override'); #parse ARGV and override any value with the params here
The keyword "option" work exactly like the keyword "has" and take extra argument of
Getopt.
You can also use it over a Role.
{
package tRole;
use Moo::Role;
use MooX::Options;
option 'test' => (is => 'ro');
1;
}
{
package t;
use Moo;
use MooX::Options; #you have to add this, or the role will not find the necessary methods
with 'tRole';
1;
}
my $t = t->new_with_options(); #parse @ARGV
my $o = t->new_with_options(test => 'override'); #parse ARGV and override any value with the params here
If you use Mo, you have a little bit more work to do. Because Mo lack of "with" and
"around".
{
package tRole;
use Moo::Role;
use Mo;
use MooX::Options;
option 'test' => (is => 'ro');
1;
}
{
package t;
use Mo;
use Role::Tiny::With;
with 'tRole';
1;
}
my $t = t->new_with_options(); #parse @ARGV
my $o = t->new_with_options(test => 'override'); #parse ARGV and override any value with the params here
It's a bit tricky but, hey, you are using Mo !
Keyword 'options_usage'
It display the usage message and return the exit code
my $t = t->new_with_options();
$t->options_usage(1, "str is not valid");
Params :
$exit_code
Exit code after displaying the usage message
@messages
Additional message to display before the usage message
Ex: str is not valid
Keyword 'new_with_options'
It will parse your command line params and your inline params, validate and call the 'new'
method.
You can override the command line params :
Ex:
local @ARGV=('--str=ko');
t->new_with_options(str => 'ok');
t->str; #ok
Keyword 'option' : EXTRA ARGS
doc Specified the documentation for the attribute
documentation
Specified the documentation for the attribute. It is usefull if you chain with other
module like MooseX::App::Cmd that use this attribute.
If doc attribute is defined, this one will be ignored.
required
Specified if the attribute is needed
format
Format of the params. It is the same as Getopt::Long::Descriptive.
Example :
i : integer
i@: array of integer
s : string
s@: array of string
f : float value
by default, it's a boolean value.
Take a look of available format with Getopt::Long::Descriptive.
negativable
add the attribute "!" to the name. It will allow negative params.
Ex :
test --quiet
=> quiet = 1
test --quiet --no-quiet
=> quiet = 0
repeatable
add the attribute "@" to the name. It will allow repeatable params.
Ex :
test --verbose
=> verbose = 1
test --verbose --verbose
=> verbose = 2
it is advisable to use a "default" option on the attribute for repeatable params so
that they behave as arrays "out of the box" when used outside of command line context.
Ex:
{
package t;
use Moo;
use MooX::Options;
option foo => (is => 'rw', format => 's@', default => sub { [] });
option bar => (is => 'rw', format => 'i@', default => sub { [] });
1;
}
# this now works as expected and you will no longer see
# "Can't use an undefined value as an ARRAY reference"
my $t = t->new_with_options;
push @{ $t->foo }, 'abc123';
1;
autosplit
auto split args to generate multiple value. It implie "repeatable". autosplit take
the separator value, ex: ",".
Ex :
{
package t;
use Moo;
use MooX::Options;
option test => (is => 'ro', format => 'i@', autosplit => ',');
#same as : option test => (is => 'ro', format => 'i', autosplit => ',');
1;
}
local @ARGV=('--test=1,2,3,4');
my $t = t->new_with_options;
t->test # [1,2,3,4]
I automatically take the quoted as a group separator value
{
package str;
use Moo;
use MooX::Options;
option test => (is => 'ro', format => 's', repeatable => 1, autosplit => ',');
1;
}
local @ARGV=('--test=a,b,"c,d",e');
my $t = str->new_with_options;
t->test # ['a','b','c,d','e']
short
give short name of an attribute.
Ex :
{
package t;
use Moo;
use MooX::Options;
option 'verbose' => (is => 'ro', repeatable => 1, short => 'v');
1;
}
local @ARGV=('-vvv');
my $t = t->new_with_options;
t->verbose # 3
order
Specified the order of the attribute.
The order value is an integer.
json
The parameter will be treat like a json string.
Ex :
{
package t;
use Moo;
use MooX::Options;
option 'hash' => (is => 'ro', json => 1);
1;
}
local @ARGV=('--hash', '{"a":1,"b":2}');
my $t = t->new_with_options;
t->hash # { a => 1, b => 2 }
namespace::clean
To use namespace::clean you need to add 2 methods as an exception. It is use by
MooX::Options when you run the new_with_options methods.
{
package t;
use Moo;
use MooX::Options;
use namespace::clean -except => [qw/_options_data _options_config/];
option 'v' => (is => 'rw');
1;
}
my $r = t->new_with_options;
dash support
You can call the option with underscore or dash in the name.
For example, --start-date or --start_date will fill the option 'start_date'.
no more Mouse support
If you are using Mouse, I'm sorry to say than the rewrite of this module has make it just
incompatible. Mouse is not design to by compatible with anything else than Mouse itself. I
could just suggest to use Moo instead, which is a great and compatible replacement.
More examples
http://perltalks.celogeek.com/slides/2012/08/moox-options-slide3d.html
<http://perltalks.celogeek.com/slides/2012/08/moox-options-slide3d.html>
THANKS
Matt S. Trout (mst) <mst@shadowcat.co.uk> : For his patience and advice.
Tomas Doran (t0m) <bobtfish@bobtfish.net> : To help me release the new version, and using
it :)
Torsten Raudssus (Getty) : to use it a lot in DuckDuckGo <http://duckduckgo.com> (go to
see MooX module also)
BUGS
Please report any bugs or feature requests on the bugtracker website
https://tasks.celogeek.com/projects/perl-modules-moox-options
When submitting a bug or request, please include a test-file or a patch to an existing
test-file that illustrates the bug or desired feature.
AUTHOR
celogeek <me@celogeek.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by celogeek <me@celogeek.com>.
This is free software; you can redistribute it and/or modify it under the same terms as
the Perl 5 programming language system itself.