Author image Eric Wilhelm
and 1 contributors


Getopt::AsDocumented - declare options as pod documentation


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


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

    my $what = $opt->what;


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.



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


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


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.


An integer.

  =item --foo FOO (integer)


A floating-point number.

  =item --foo FOO (number)


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

  =item --foo FOO (string)


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


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


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

  =item --foo BAR=BAZ


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)


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'}



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.





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

  $obj = $self->make_object;



  my $handler = $go->handler;


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


Sets the quit flag.


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.


Sets the quit flag.

Other Methods


  my $go = Getopt::AsDocumented->new(%settings);
pod => $string
from_file => $filename
handler => $classname


Eric Wilhelm @ <ewilhelm at cpan dot org>


If you found this module on CPAN, please report any bugs or feature requests through the web interface at 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 (C) 2009 Eric L. Wilhelm, All Rights Reserved.


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.


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