DESCRIPTION

Perl Moose Role that extends MooseX::Getopt to provide usage printing and man page generation 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.

The message is formatted to the width of the terminal when STDOUT is a tty, to a width of 72 characters otherwise.

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.

The usage message can be extended and controlled by including sections selected from the modules POD, with the default to automatically generate SYNOPSIS and OPTIONS sections.

By also using the MooseX::Getopt::Usage::Role::Man role a --man option is added to your class that will display the man page generated from your modules POD documentation. This POD will include the generated SYNOPSIS and OPTIONS sections if they are selected.

This is all much inspired (and partly implemented) by the excellent Pod::Usage module, but with added Moose meta goodness.

ATTRIBUTES

help_flag

Indicates if any of -?, --help, or --usage where given in the command line args.

man

Added when using MooseX::Getopt::Usage::Role::Man. The --man option on the command line. If true after class construction program will exit displaying the man generated from the POD.

METHODS

new_with_options( %params )

The normal MooseX::Getopt entry point, over ridden here to add our own usage handling. If help_flag (-?, --help or --usage) is given in the options will display the usage message and exit.

Traps errors from the command line processing, displaying them along with the usage message. Will also trap type constraint fails and missing required attribute errors from your classes constructor.

getopt_usage( %args )

Generate the usage message and return or output to stdout and exit. Used by new_with_options. Without exit arg returns the usage string, with an exit arg prints the usage to stdout and exits with the given exit code.

Options are printed required first, then optional. These two sections get a heading unless headings arg or config is false. Note that required attributes of your class that have a default or builder will be considered optional options.

%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.

man

Display the man page instead of the usage message.

getopt_usage_config

Return a hash (ie a list) of config to override the defaults. Default returns empty list. See "CONFIGURATION" for details of the option keys.

Note that this method gets called as a class method, before the class is constructed. If you wish to change this method from a role you will need to use the around method modifier. See "Sharing config".

format

String to format the usage/synopsis section of the usage message. %c is substituted for the command name. Use %% for a literal %.

If not set it will check the POD for "format_sections", using the POD selected if it is found. That defaults to the SYNOPSIS section, so the easy way to add your own usage section is to add a SYNOPSIS to your POD.

If no POD is found a default string of "%c [OPTIONS]" is used.

Note that when selecting POD the headings are removed.

%a, %r and %o expand to a list of all the options on a line. %a gives all options, %r only required and %o only optional. Option args get square brackets around them, while non-boolean options get an =VALUE added. e.g. using a format string of "%c %r %o" might produce:

usage_sections

When generating a usage message the POD sections to select. Default is SYNOPSIS and OPTIONS sections (which will be auto generated from meta if they don't exist). Value is an array ref of "SECTION SPECIFICATIONS" in Pod::Select strings.

Headings will be displayed, titled cased with a colon on the end. Use the "headings" option to hide the headings. Order displayed will be the same as the POD.

You can use this to expand the usage message. e.g. you might also want the DESCRIPTION and EXAMPLE from your POD in the usage message:

usage_sections => ['SYNOPSIS|USAGE|DESCRIPTION|EXAMPLES']

man_sections

When generating a man page the POD sections to select. Default is everything except ATTRIBUTES and METHODS (as we will generate an OPTIONS section instead of ATTRIBUTES and METHODS isn't relevant to command line users). Value is an array ref of "SECTION SPECIFICATIONS" in Pod::Select strings.

Use an empty array to include all POD sections.

man_sections => [],

e.g. to exclude TODO, keeping the default excludes you could do:

man_sections => ["!ATTRIBUTES|METHODS","!TODO"],

or maybe you only want the NAME and DESCRIPTION (along with the generated SYNOPSIS and OPTIONS):

man_sections => ["NAME|DESCRIPTION"],

use_color

Whether to use color in the usage message. One of 'auto', 'never', 'always' or 'env'. Auto will use color if the output is a tty, otherwise not. 'env' looks at the ANSI_COLORS_DISABLED environment variable (see Term::ANSIColor). Note that the env is also read in auto mode.

unexpand

tabstop

auto_man

Defaults to true. Display usage when --help option is given. Set false to disable this, allowing you to do your own processing after new_with_options then probably call getopt_usage yourself.

auto_help

Defaults to true. Display man page when --man option is given. Set false to disable this, allowing you to do your own processing after new_with_options then probably call getopt_usage( man => 1,.. ) yourself.

POD GENERATION

Both the usage message and man page are generated by selecting sections (headings) from your modules POD documentation. It will auto generate both SYNOPSIS (usage) and OPTIONS sections if they do not exist, which means you still get a nice usage message (and basic man page) with no POD.

The SYNOPSIS, if not present, will just contain the default "format" message and is inserted after NAME or at the start of the POD. If present it is used as is, still getting %c etc substituted.

OPTIONS will generate a list of the options by examining your classes attributes. The section is inserted after DESCRIPTION or at the end of the file. If an OPTIONS section already exists the list of options will be appended to it, allowing you to add some extra documentation above the options.

All section selecting options are applied after POD generation so can be used to hide as well as include generated sections.

EXAMPLES

Expanding the usage message.

This adds the DESCRIPTION from the POD to the usage and changes the usage message to show it takes files.

Sharing config

You may find that you want to have a common set of config (ie "getopt_usage_config" return) shared by a number of command classes. You could do this with a common base class or as this is Moose do it with a role.

Note that if the consuming class also impliments getopt_usage_config then the configs will be combined, with config from the class overriding that from the role. You can change this order by moving the $class->$orig(@_), in the return in the role above.