OptionParser

OptionParser parses command line options from a tool’s POD. By default it parses a description and usage from the POD’s SYNOPSIS section and command line options from the OPTIONS section.

The SYNOPSIS section should look like,

=head1 SYNOPSIS

Usage: mk-archiver [OPTION...] --source DSN --where WHERE

mk-archiver nibbles records from a MySQL table.  The --source and --dest
arguments use DSN syntax; if COPY is yes, --dest defaults to the key's value
from --source.

Examples:
...

The key, required parts are the “Usage:” line and the following description paragraph.

The OPTIONS section shoud look like,

=head1 OPTIONS

Optional rules, one per line.

=over

=item --analyze

type: string

Run ANALYZE TABLE afterwards on L<"--source"> and/or L<"--dest">.
ect.

The option’s full name is given as the “=item”. The next, optional para is the option’s attributes. And the next, required para is the option’s description (the first period-terminated sentence).

Summary

OptionParser	OptionParser parses command line options from a tool’s POD.
Variables
$POD_link_re
Functions
new
get_specs	Read and parse options from the OPTIONS section of the POD.
DSNParser	Return the DSNParser object automatically created for DSN type opts.
get_defaults_files	Return the program’s defaults files.
_pod_to_specs()	Parse basic specs for each option.
_parse_specs	Parse option specs and rules.
_get_participants	Extract option names from a string.
opts	A copy of the internal opts hash
short_opts	A copy of the internal short_opts hash
set_defaults	Set default values for options.
get_defaults
get_groups
_set_option	Getopt::Long calls this sub for each opt it finds on the cmd line.
get_opts	Get command line options and enforce option rules.
_check_opts	Check options against rules and group restrictions.
_validate_type	Validate special option types like sizes and DSNs.
get	Get an option’s value.
got	Test if an option was explicitly given on the command line.
has	Test if an option exists (i.e.
set	Set an option’s value.
save_error	Save an error message to be reported later by usage_or_errors().
errors	Used for testing.
usage
descr
usage_or_errors
print_errors
print_usage
prompt_noecho
read_para_after	Read the POD paragraph after a magical regex.

Variables

$POD_link_re

my $POD_link_re

Functions

new

sub new

Parameters

%args

Arguments

Optional Arguments

file	Filename to parse POD stuff from. Several subs take a $file param mostly for testing purposes. This arg provides a “global” default for even easier testing.
description	Tool’s description (overrides description from SYNOPSIS).
usage	Tool’s usage line (overrides Usage from SYNOPSIS).
head1	head1 heading under which options are listed
skip_rules	Don’t read paras before options as rules
item	Regex pattern to match options after =item
attributes	Hashref of allowed option attributes
parse_attributes	Coderef for parsing option attributes

Returns

OptionParser object

get_specs

sub get_specs

Read and parse options from the OPTIONS section of the POD. This sub should be called first, then get_opts(). _pod_to_specs() and _parse_specs() do most of the work. If the POD has a DSN OPTIONS section then a DSNParser object is created which can be accessed with DSNParser().

Parameters

$file

File name to read, FILE if none given

DSNParser

sub DSNParser

Return the DSNParser object automatically created for DSN type opts.

Returns

DSNParser object

get_defaults_files

sub get_defaults_files

Return the program’s defaults files.

Returns

Array of defaults files

_pod_to_specs()

sub _pod_to_specs

Parse basic specs for each option. Each opt spec is a hashref like:

{
   spec  => GetOpt::Long specification,
   desc  => short description for --help
   group => option group (default: 'default')
}

This is step 1 of 2 of parsing the POD opts. The second is C<_parse_specs()>.

Parameters

$file

File name to read, FILE if none given

Returns

Array of opt spec hashrefs to pass to _parse_specs().

_parse_specs

sub _parse_specs

Parse option specs and rules. The opt specs and rules are returned by _pod_to_specs(). The following attributes are added to each opt spec:

short         => the option's short key (-A for --charset)
is_cumulative => true if the option is cumulative
is_negatable  => true if the option is negatable
is_required   => true if the option is required
type          => the option's type, one of $self->{types}
got           => true if the option was given explicitly on the cmd line
value         => the option's value

Parameters

@specs

Opt specs and rules from _pod_to_specs()

_get_participants

sub _get_participants

Extract option names from a string. This is used to find the “participants” of option rules (i.e. the options to which a rule applies).

Parameters

$str	String containing option names like “Options L<”--[no]foo”> and --bar are mutually exclusive.”

Returns

Array of option names

opts

sub opts

Returns

A copy of the internal opts hash

short_opts

sub short_opts

Returns

A copy of the internal short_opts hash

set_defaults

sub set_defaults

Set default values for options.

get_defaults

sub get_defaults

get_groups

sub get_groups

_set_option

sub _set_option

Getopt::Long calls this sub for each opt it finds on the cmd line. We have to do this in order to know which opts were “got” on the cmd line.

get_opts

sub get_opts

Get command line options and enforce option rules. Option values are saved internally in $self->{opts} and accessed later by get(), got(), and set(). Call get_specs() before calling this sub.

_check_opts

sub _check_opts

Check options against rules and group restrictions.

Parameters

@long

Array of option names

_validate_type

sub _validate_type

Validate special option types like sizes and DSNs.

Parameters

$opt	Long option name to validate

get

sub get

Get an option’s value. The option can be either a short or long name (e.g. -A or --charset).

Parameters

$opt	Option name, long (--charset) or short (-A)

Returns

The option’s value

got

sub got

Test if an option was explicitly given on the command line.

Parameters

$opt	Option name, long (--charset) or short (-A)

Returns

Bool

has

sub has

Test if an option exists (i.e. is specified in the tool’s POD).

Parameters

$opt	Option name, long (--charset) or short (-A)

Returns

Bool

set

sub set

Set an option’s value. No type checking is done so be careful to not set, for example, an integer option with a DSN.

Parameters

$opt	Option name, long (--charset) or short (-A)
$val	Option’s new value

save_error

sub save_error

Save an error message to be reported later by usage_or_errors().

Parameters

$error

Error message

errors

sub errors

Used for testing.

usage

sub usage

descr

sub descr

usage_or_errors

sub usage_or_errors

print_errors

sub print_errors

print_usage

sub print_usage

prompt_noecho

sub prompt_noecho

read_para_after

Read the POD paragraph after a magical regex. This is used, for exmaple, to get default CREATE TABLE from the POD. We write something like:

This is the default MAGIC_foo_table:

  CREATE TABLE `foo` (i INT)

Blah blah...

Then to get that CREATE TABLE, you pass “MAGIC_foo_table” as the magical regex.

Parameters

$file	File to read
$regex	Regex to find something magical before the desired POD paragraph

Returns

POD paragraph after magical regex