# NAME
MooX::Options - Explicit Options eXtension for Object Class
# VERSION
version 4.009
# 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")
## 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) : For his patience and advice.
- Tomas Doran (t0m) : 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
# COPYRIGHT AND LICENSE
This software is copyright (c) 2013 by celogeek .
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.