/ 
MooX-Options-3.0
River stage three • 48 direct dependents • 149 total dependents
/ MooX::Options

NAME

MooX::Options - add option keywords to your object (Mo/Moo/Moose)

VERSION

version 3.0

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;

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;
    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

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.

THANKS

Matt S. Trout (mst) <mst@shadowcat.co.uk> : For his patience and advice.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/celogeek/MooX-Options/issues

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.