NAME
MooseX::Getopt::Usage - Extend MooseX::Getopt with usage message generated from attribute meta.
VERSION
Version 0.07
SYNOPSIS
## In your class
package My::App;
use Moose;
with 'MooseX::Getopt::Usage';
has verbose => ( is => 'ro', isa => 'Bool', default => 0,
documentation => qq{Say lots about what we are doing} );
has gumption => ( is => 'rw', isa => 'Int', default => 23,
documentation => qq{How much gumption to apply} );
# ... rest of class
## In your script
#!/usr/bin/perl
use My::App;
my $app = My::App->new_with_options;Can now get help,
$ synopsis.pl -?
Usage:
synopsis.pl [OPTIONS]
Options:
--help -? --usage - Bool. Display the usage message and exit
--verbose - Bool. Say lots about what we are doing
--gumption - Int. Default=23. How much gumption to applyand trap errors with usage.
$ synopsis.pl --elbowgrease --gumption=Lots
Unknown option: elbowgrease
Value "Lots" invalid for option gumption (number expected)
Usage:
synopsis.pl [OPTIONS]
Options:
--help -? --usage - Bool. Display the usage message and exit
--verbose - Bool. Say lots about what we are doing
--gumption - Int. Default=23. How much gumption to applyDESCRIPTION
Perl Moose Role that extends MooseX::Getopt to provide usage printing that inspects your classes meta information to build a (coloured) usage message including that meta information.
If stdout is a tty usage message is colourised. Setting the env var ANSI_COLORS_DISABLED will disable colour even on a tty.
Errors in command line option parsing will be displayed along with the usage, causing the program to exit with a non-zero status code when new_with_options is used.
ATTRIBUTES
help_flag
Indicates if any of -?, --help, or --usage where given in the command line args.
METHODS
getopt_usage( %args )
Generate the usage message and return or output to stdout and exit. Without exit arg returns the usage string, with an exit arg prints the usage to stdout and exits with the given exit code.
print $self->getopt_usage if $self->help_flag;
$self->getopt_usage( exit => 10, err => "Their all dead, Dave" );Options are printed required first, then optional. These two sections get a heading unless headings arg or config is false.
%args can have any of the options from "CONFIGURATION", plus the following.
- exit
-
If an exit arg is given and defined then this method will exit the program with that exit code after displaying usage to STDOUT.
- err | error
-
Error message string to display before the usage. Will get the error highlight.
getopt_usage_config
Return a hash (ie a list) of config to override the defaults. Default returns empty list. See "CONFIGURATION" for details.
CONFIGURATION
The configuration used is the defaults, followed by the return from "getopt_usage_config", followed by any args passed direct to "getopt_usage". The easiest way to configure the usage message is to override "getopt_usage_config" in your class. e.g. to use a more compact layout.
use Moose;
with 'MooseX::Getopt::Usage';
sub getopt_usage_config {
return (
format => "Usage: %c [OPTIONS]",
headings => 0,
);
}Availiable config is:
format
String to format the top of the usage message. %c is substituted for the command name. Use %% for a literal %. Default:
format => "Usage:\n %c [OPTIONS]",attr_sort
Sub ref used to sort the attributes and hence the order they appear in the usage message. Default is the order the attributes are defined.
NB: the sort terms ($a and $b) are passed as the first two arguments, do not use $a and $b (you will get warnings). The arguments will be Moose::Meta::Attributes. e.g. to sort by name alphabetically:
attr_sort => sub { $_[0]->name cmp $_[1]->name }headings
Whether to add headings of 'Options:' and 'Required:' to the list of options. Default is true.
colours | colors
Hash ref mapping highlight names to colours, given as strings to pass to Term::ANSIColor. Default looks like this:
colours => {
flag => ['yellow'],
heading => ['bold'],
command => ['green'],
type => ['magenta'],
default_value => ['cyan'],
error => ['red']
}unexpand
Set $Text::Wrap::unexpand, see "OVERRIDES" in Text::Wrap.
tabstop
Set $Text::Wrap::tabstop, see "OVERRIDES" in Text::Wrap.
EXAMPLE
Put this is a file called hello.pl and make it executable.
#!/usr/bin/env perl
package Hello;
use Modern::Perl;
use Moose;
with 'MooseX::Getopt::Usage';
has verbose => ( is => 'ro', isa => 'Bool',
documentation => qq{Say lots about what we do} );
has greet => ( is => 'ro', isa => 'Str', default => "World",
documentation => qq{Who to say hello to.} );
has times => ( is => 'rw', isa => 'Int', required => 1,
documentation => qq{How many times to say hello} );
sub run {
my $self = shift;
say "Printing message..." if $self->verbose;
say "Hello " . $self->greet for (1..$self->times);
}
package main;
Hello->new_with_options->run;Then call with any of these to get usage output.
$ ./hello.pl -?
$ ./hello.pl --help
$ ./hello.pl --usageWhich will look a bit like this, only in colour.
Usage:
hello.pl [OPTIONS]
Required:
--times - Int. How many times to say hello
Options:
--help -? --usage - Bool. Display the usage message and exit
--verbose - Bool. Say lots about what we do
--greet - Str. Default=World. Who to say hello to.SEE ALSO
perl, Moose, MooseX::Getopt, Term::ANSIColor, Text::Wrap.
BUGS
All complex software has bugs lurking in it, and this module is no exception. Please report any bugs or feature requests via the github page at:
http://github.com/markpitchless/moosex-getopt-usage
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc MooseX::Getopt::UsageThe source code and other information is hosted on github:
http://github.com/markpitchless/moosex-getopt-usage
AUTHOR
Mark Pitchless, <markpitchless at gmail.com>
ACKNOWLEDGEMENTS
COPYRIGHT & LICENSE
Copyright 2012 Mark Pitchless
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.