NAME

Getopt::AsDocumented - declare options as pod documentation

SYNOPSIS

  =head1 Options
  ...
  =item -w, --what WHAT

  =cut

  sub main {
    my (@args) = @_;
    my $opt = Getopt::AsDocumented->process(\@args) or return;

    my $what = $opt->what;
    ...
  }

About

This module allows you to declare your program's command-line options as pod documentation. It provides syntax to declare types and defaults in a way which is also readable as documentation.

Note: This is built on Getopt::Base and some advanced features are still growing. Your help is welcome.

Methods

process

Loads the pod from your current file and processes the command-line arguments.

  my $opt = Getopt::AsDocumented->process(\@args) or return;

Option Specification

With/Without Opterands

If an option is followed by a word, it requires an opterand.

  =item --foo FOO

Otherwise, it is a simple flag (boolean) option

  =item --foo

Booleans

Each boolean option will automatically generate a '--no-' form which negates it. You may choose to mention this and/or link aliases to it.

  =item --foo

  Sets the fooness.

  =item -x, --ex-foo, --no-foo

Types

Non-boolean options may be typed as strings, numbers, or integers. The type is included in parenthesis after the option spec. If the type is not mentioned, it defaults to string.

integer

An integer.

  =item --foo FOO (integer)

number

A floating-point number.

  =item --foo FOO (number)

string

A string. This is the default, but may be included for clarity.

  =item --foo FOO (string)

Scalar/HASH/ARRAY

Any non-boolean option can take one of the following forms.

Scalar

An option followed by a simple word means that only one value is assigned to it (if the user repeats it, a prior value is overwritten.)

  =item --foo FOO

HASH

A HASH option is followed by something of the form \w+=.*. Each opterand is treated as a $key=$value pair.

  =item --foo BAR=BAZ

LIST

A LIST option is followed by another mention of itself within [] brackets with an ellipsis to indicate optional additional elements.

  =item --foo FOO [--foo ...]

If a list option requires an explicit type, this must be included after the bracketed text.

  =item --foo FOO [--foo ...] (integer)

Defaults

An option's default may be set by the string "DEFAULT: " at the beginning of a paragraph. The remainder of that paragraph contains the default value.

  =item --foo FOO

  The setting for foo.

  DEFAULT: bar

Any leading whitespace after the ':' is removed.

A single leading backslash (if present) will be removed and the rest of the string will be treated as a literal.

A boolean default may be "NO". Without a value, a boolean will default to undef. Anything true will be translated to '1'.

  =item --foo

  Whether to foo or not.

  DEFAULT:  yes.  Use --no-foo to disable this.

The strings "no" or "false" may also be used as "0".

If the default is enclosed with braces ({}), it is interpreted as a block of code. For literal braces, use a leading backslash.

  =item --input FILENAME

  Input file.

  DEFAULT: {File::Fu->home + 'input.txt'}

Handlers

config_file_handler

Loads the user's configuration file. All of the values from the configuration will be loaded into the options object before any options from the command-line are processed.

  $go->config_file_handler;

load_config_file

  $self->load_config_file($file);

make_object

Wraps the super method in order to load the config file.

  $obj = $self->make_object;

handler

Accessor.

  my $handler = $go->handler;

version_handler

Prints the version from your handler/caller()'s package.

  $go->version_handler;

Sets the quit flag.

help_handler

Prints a help message based on the USAGE and OPTIONS sections from your pod. Uses the first sentence from each =item section, or alternatively: =for help content found within the =item section.

  $go->help_handler;

Sets the quit flag.

Other Methods

new

  my $go = Getopt::AsDocumented->new(%settings);

pod => $string

from_file => $filename

handler => $classname

  $self->_init(%setup);

AUTHOR

Eric Wilhelm @ <ewilhelm at cpan dot org>

http://scratchcomputing.com/

BUGS

If you found this module on CPAN, please report any bugs or feature requests through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

If you pulled this development version from my /svn/, please contact me directly.

COPYRIGHT

Copyright (C) 2009 Eric L. Wilhelm, All Rights Reserved.

NO WARRANTY

Absolutely, positively NO WARRANTY, neither express or implied, is offered with this software. You use this software at your own risk. In case of loss, no person or entity owes you anything whatsoever. You have been warned.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Getopt::AsDocumented

perl -MCPAN -e shell
install Getopt::AsDocumented