Opt::Imistic - Optimistic option parsing
use Opt::Imistic; die if $ARGV{exit};
Most option parsers end up doing the same thing but you have to write a whole spec to do it. This one just gets all the options and then gets out of your way.
For the most part, your command-line options will probably be one of two things: a toggle (or maybe a counter), or a key/value pair. Opt::Imistic assumes this and parses your options. If you need more control over it, Opt::Imistic is not for you and you might want to try a module such as Getopt::Long. That being said, see the CONFIGURATION section for ways to configure Opt::Imistic.
The hash %ARGV contains your arguments. The argument name is provided as the key and the value is provided as the value. If you use the same argument multiple times and sometimes without a value then that instance of the option will be represented as undef. If you provide the option multiple times and none has a value then your value is the count of the number of times the option appeared.
%ARGV
All arguments in %ARGV are now represented as array refs, blessed into a package that stringifies them to the last instance of that argument and boolifies to true. That means that you can always do
@{ $ARGV{option_name} }
or
$ARGV{option_name} =~ /cats/
if ($ARGV{option_name})
without having to test what $ARGV{option_name} actually is.
This basically means that the way you use the option determines what it should have been:
To follow convention, when you try to use an argument as a string, the end of the internal arrayref is returned: this implements the common behaviour that the last option of the same name is honoured.
Long options start with --. Short options are single letters and start with -. Multiple short options can be grouped without repeating the -, in the familiar perl -lne fashion.
--
-
perl -lne
For short options the value must be separated from the option letter; but for long options, both whitespace and a single = are considered delimiters. This is because Opt::Imistic doesn't take an option spec, and hence cannot distinguish between single-letter options with values and several single-letter options.
=
Repeated options with no values are counted. Repeated options with values are concatenated in an array ref. Note that all options can be treated as array refs.
The options are considered to stop on the first argument that does not start with a - and cannot be construed as the value to an option. You can use the standard -- to force the end of option parsing. Everything after the last option goes under the special key -, because that can never be an option name. These are also left on @ARGV so that <> still works.
<>
Examples help
script.pl -abcde a => 1 b => 1 c => 1 d => 1 e => 1
That one's obvious.
script.pl -a foo.pl a => ['foo.pl'] @ARGV = ()
script.pl -a -- foo.pl a => [ 1 ] - => [ 'foo.pl' ] @ARGV = ('foo.pl')
script.pl -foo f => [ 1 ] o => [ 2 ]
script.pl -foo bar f => [ 1 ] o => [undef, 'bar']
script.pl --foo bar --foo=bar foo => ['bar', 'bar']
Opt::Imistic can be crudely configured to deal with certain options specially. Configuration is done by means of the import list, meaning all requirements will have been satisfied before the program even finishes compiling.
If the first item in your import list is an integer, this will be used as the putback value. Observe that this will be shifted from the import list, and the rest of the list will be used to construct a hash.
shift
import
Putback refers to the act of putting arguments back onto @ARGV. This allows your script to be called with non-value options which are followed by actual arguments:
@ARGV
$ push.pl -v master # %ARGV { 'v' => bless( [ 'master' ], 'Opt::Imistic::Option' ) };
If push.pl is an Opt::Imistic script, $ARGV{v} would have the value master, and @ARGV would not have anything on it at all.
push.pl
$ARGV{v}
master
To fix this, you tell Opt::Imistic that you need at least one argument:
use Opt::Imistic (1);
Now, @ARGV will always have at least one (non-option) entry. If this cannot be satisfied, the script bails.
$ push.pl -v master # %ARGV: { '-' => bless( [ 'master' ], 'Opt::Imistic::Option' ), 'v' => [ 1, ] };
Note that $ARGV{'-'} is a copy of the remaining @ARGV.
$ARGV{'-'}
The putback argument will be observed before the demand or needs_val options. This means that if you provide an option that needs a value, and not enough arguments to the script itself, the script arguments will be checked before the option's argument:
demand
needs_val
use Opt::Imistic (1, needs_val => {remote => 1}); $ push.pl --remote master remote: value required but none given
In this example, master was used as the putback argument, leaving --remote with no value.
--remote
use Opt::Imistic (2, needs_val => {remote => 1}); $ push.pl --remote master Expected 2 arguments; 1 given
This is a bit clearer: putback wanted 2 arguments, so the script bailed before --remote even got a chance to look for arguments.
Sometimes your option is required. This is the case when it needs a value. It doesn't make sense for an option to be required with no value, unless you really want to make sure someone means it before they run your script. In that case, you can check %ARGV yourself.
Opt::Imistic will bail if any of the keys of the demand hashref are missing. It will also bail if the option is given without a value.
demand is provided as a hashref simply to make it easier to look up items.
use Opt::Imistic (demand => { branch => 1 });
This invocation means that --branch must be given and have a value:
--branch
$ push.pl Missing option: branch BEGIN failed--compilation aborted at push.pl line 4 $ push.pl --branch branch: value required but none given BEGIN failed--compilation aborted at push.pl line 4.
Some options are, well, optional, but don't make sense without a value. For this, use the needs_val hashref:
use Opt::Imistic (needs_val => { branch => 1 });
Now if --branch is given it must have a value, but if not, that's also fine:
$ push.pl $ push.pl --branch branch: value required but none given BEGIN failed--compilation aborted at push.pl line 4.
If you provide a usage key in the hash-like options list, it will be printed with anything that causes Opt::Imistic to die.
usage
use Opt::Imistic (2, needs_val => { remote => 1 }, usage => "Usage: push.pl [--remote=<remote>] branch\n" ); Expected 2 arguments; 1 given Usage: push.pl [--remote=<remote>] branch
It should be noted that Opt::Imistic does not observe a difference between -f and --f.
-f
--f
Counted options lose their blessing as Opt::Imistic::Option, which may sometimes break code that didn't expect it to be a counted option.
Usage messages cause the die line to be reported if they don't have their own newline.
Please report undesirable behaviour, but note the TODO list first:
Altreus <altreus@perl.org>
To install Opt::Imistic, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Opt::Imistic
CPAN shell
perl -MCPAN -e shell install Opt::Imistic
For more information on module installation, please visit the detailed CPAN module installation guide.