# NAME

MooX::Options - Explicit Options eXtension for Object Class

# VERSION

version 4.015

# DESCRIPTION

Create a command line tool with your [Mo](https://metacpan.org/pod/Mo), [Moo](https://metacpan.org/pod/Moo), [Moose](https://metacpan.org/pod/Moose) objects.

Everything is explicit. You have an `option` keyword to replace the usual `has` to explicitly use your attribute into the command line.

The `option` keyword takes additional parameters and uses [Getopt::Long::Descriptive](https://metacpan.org/pod/Getopt::Long::Descriptive)
to generate a command line tool.

# SYNOPSIS

In myOptions.pm :

    package myOptions;
    use Moo;
    use MooX::Options;
    
    option 'show_this_file' => (
        is => 'ro',
        format => 's',
        required => 1,
        doc => 'the file to display'
    );
    1;

In myTool.pl :

    use feature 'say';
    use myOptions;
    use Path::Class;
    
    my $opt = myOptions->new_with_options;
    
    say "Content of the file : ",
         file($opt->show_this_file)->slurp;

To use it :

    perl myTool.pl --show_this_file=myFile.txt
    Content of the file: myFile content

The help message :

    perl myTool.pl --help
    USAGE: myTool.pl [-h] [long options...]
    
        --show_this_file: String
            the file to display
        
        -h --help:
            show this help message
        
        --man:
            show the manual

The usage message :

    perl myTool.pl --usage
    USAGE: myTool.pl [ --show_this_file=String ] [ --usage ] [ --help ] [ --man ]

The manual :

    perl myTool.pl --man

# IMPORTED METHODS

The list of the methods automatically imported into your class.

## new\_with\_options

It will parse your command line params and your inline params, validate and call the `new` method.

    myTool --str=ko

    t->new_with_options()->str # ko
    t->new_with_options(str => 'ok')->str #ok

## option

The `option` keyword replaces the `has` method and adds support for special options for the command line only.

See ["OPTION PARAMETERS"](#option-parameters) for the documentation.

## options\_usage | --help

It displays the usage message and returns the exit code.

    my $t = t->new_with_options();
    my $exit_code = 1;
    my $pre_message = "str is not valid";
    $t->options_usage($exit_code, $pre_message);

This method is also automatically fired if the command option "--help" is passed.

    myTool --help

## options\_man | --man

It displays the manual.

    my $t = t->new_with_options();
    $t->options_man();

This is automatically fired if the command option "--man" is passed.

    myTool --man

## options\_short\_usage | --usage

It displays a short version of the help message.

    my $t = t->new_with_options();
    $t->options_short_usage($exit_code);

This is automatically fired if the command option "--usage" is passed.

    myTool --usage

# IMPORT PARAMETERS

The list of parameters supported by [MooX::Options](https://metacpan.org/pod/MooX::Options).

## flavour

Passes extra arguments for [Getopt::Long::Descriptive](https://metacpan.org/pod/Getopt::Long::Descriptive). It is useful if you
want to configure [Getopt::Long](https://metacpan.org/pod/Getopt::Long).

    use MooX::Options flavour => [qw( pass_through )];

Any flavour is passed to [Getopt::Long](https://metacpan.org/pod/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

If you have Role with options and you want to deactivate some of them, you can use this parameter.
In that case, the `option` keyword will just work like an `has`.

    use MooX::Options skip_options => [qw/multi/];

## prefer\_commandline

By default, arguments passed to `new_with_options` have a higher priority than the command line options.

This parameter will give the command line an higher priority.

    use MooX::Options prefer_commandline => 1;

## with\_config\_from\_file

This parameter will load [MooX::ConfigFromFile](https://metacpan.org/pod/MooX::ConfigFromFile) in your module. 
The config option will be used between the command line and parameters.

myTool :

    use MooX::Options with_config_from_file => 1;

In /etc/myTool.json

    {"test" : 1}

# OPTION PARAMETERS

The keyword `option` extend the keyword `has` with specific parameters for the command line.

## doc | documentation

Documentation for the command line option.

## long\_doc

Documentation for the man page. By default the `doc` parameter will be used.

See also [Man parameters](https://metacpan.org/pod/MooX::Options::Manual::Man) to get more examples how to build a nice man page.

## required

This attribute indicates that the parameter is mandatory.
This attribute is not really used by [MooX::Options](https://metacpan.org/pod/MooX::Options) but ensures that consistent error message will be displayed.

## format

Format of the params, same as [Getopt::Long::Descriptive](https://metacpan.org/pod/Getopt::Long::Descriptive).

- 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 formats with [Getopt::Long::Descriptive](https://metacpan.org/pod/Getopt::Long::Descriptive).

You need to understand that everything is explicit here. 
If you use [Moose](https://metacpan.org/pod/Moose) and your attribute has `isa => 'Array[Int]'`, that will **not** imply the format `i@`.

## format json : special format support

The parameter will be treated like a json string.

    option 'hash' => (is => 'ro', json => 1);

    myTool --hash='{"a":1,"b":2}' # hash = { a => 1, b => 2 }

## negativable

It adds the negative version for the option.

    option 'verbose' => (is => 'ro', negativable => 1);

    myTool --verbose    # verbose = 1
    myTool --no-verbose # verbose = 0

## repeatable

It appends to the ["format"](#format) the array attribute `@`.

I advise to add a default value to your attribute to always have an array.
Otherwise the default value will be an undefined value.

    option foo => (is => 'rw', format => 's@', default => sub { [] });

    myTool --foo="abc" --foo="def" # foo = ["abc", "def"]

## autosplit

For repeatable option, you can add the autosplit feature with your specific parameters.

    option test => (is => 'ro', format => 'i@', default => sub {[]}, autosplit => ',');
    
    myTool --test=1 --test=2 # test = (1, 2)
    myTool --test=1,2,3      # test = (1, 2, 3)

It will also handle quoted params with the autosplit.

    option testStr => (is => 'ro', format => 's@', default => sub {[]}, autosplit => ',');

    myTool --testStr='a,b,"c,d",e,f' # testStr ("a", "b", "c,d", "e", "f")

## autorange

For another repeatable option you can add the autorange feature with your specific parameters. This 
allows you to pass number ranges instead of passing each individual number.

    option test => (is => 'ro', format => 'i@', default => sub {[]}, autorange => 1);
    
    myTool --test=1 --test=2 # test = (1, 2)
    myTool --test=1,2,3      # test = (1, 2, 3)
    myTool --test=1,2,3..6   # test = (1, 2, 3, 4, 5, 6)

It will also handle quoted params like `autosplit`, and will not rangify them.

    option testStr => (is => 'ro', format => 's@', default => sub {[]}, autorange => 1);

    myTool --testStr='1,2,"3,a,4",5' # testStr (1, 2, "3,a,4", 5)

`autosplit` will be set to ',' if undefined. You may set `autosplit` to a different delimiter than ','
for your group separation, but the range operator '..' cannot be changed. 

    option testStr => (is => 'ro', format => 's@', default => sub {[]}, autorange => 1, autosplit => '-');

    myTool --testStr='1-2-3-5..7' # testStr (1, 2, 3, 5, 6, 7) 

## short

Long option can also have short version or aliased.

    option 'verbose' => (is => 'ro', short => 'v');

    myTool --verbose # verbose = 1
    myTool -v        # verbose = 1

    option 'account_id' => (is => 'ro', format => 'i', short => 'a|id');

    myTool --account_id=1
    myTool -a=1
    myTool --id=1

You can also use a shorter option without attribute :

    option 'account_id' => (is => 'ro', format => 'i');

    myTool --acc=1
    myTool --account=1

## order

Specifies the order of the attribute. If you want to push some attributes at the end of the list.
By default all options have an order set to `0`, and options are sorted by their names.

    option 'at_the_end' => (is => 'ro', order => 999);

# ADDITIONAL MANUALS

- [Man parameters](https://metacpan.org/pod/MooX::Options::Manual::Man)
- [Using namespace::clean](https://metacpan.org/pod/MooX::Options::Manual::NamespaceClean)
- [Manage your tools with MooX::Cmd](https://metacpan.org/pod/MooX::Options::Manual::MooXCmd)

# EXTERNAL EXAMPLES

- [Slide3D about MooX::Options](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](https://metacpan.org/pod/MooX) module also)
- Jens Rehsack (REHSACK) : Use with [PkgSrc](http://www.pkgsrc.org/), and many really good idea ([MooX::Cmd](https://metacpan.org/pod/MooX::Cmd), [MooX::ConfigFromFile](https://metacpan.org/pod/MooX::ConfigFromFile), and more to come I'm sure)

# 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) 2013 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.
