/ 
Getopt-Yath-2.000010
/ Getopt::Yath::Option

NAME

Getopt::Yath::Option - Base class for options.

DESCRIPTION

This is the base class for option types used in Getopt::Yath.

SYNOPSIS

To create a new type you want to start with this template:

package Getopt::Yath::Option::MyType;
use strict;
use warnings;

# Become a subclass
use parent 'Getopt::Yath::Option';

# Bring in some useful constants;
use Getopt::Yath::HashBase;

# Must define these:
#######

# True if an arg is required
# True means you can do '--flag value'
# Without this you must do '--flag=value' to set a value, otherwise it can
# act like a bool or a counter and not need a value.
sub requires_arg { ... }

sub add_value {
    my $self = shift;
    my ($ref, $val) = @_;

    # $ref contains a scalar ref to where the value is stored
    # $val is the value being assigned to the option
    # Most types can get away with this:
    ${$ref} = $val;
}

sub is_populated {
    my $self = shift;
    my ($ref) = @_;

    # $$ref contains the slot where the value would be stored if it was set.
    # Most types can get away with this:
    return defined(${$ref}) ? 1 : 0;
}

sub no_arg_value {
    my $self = shift;

    # This only happens if you do not require an arg, and do not require an
    # autofill. Only bool nd count types currently do this.
    # This is the value that will be used in such cases.
    # If you do not meet the conditions for this to be called you can simply remove this method.
    ...;
}

# May want to define these, otherwise remove them from this file
#######

sub notes             { ... }    # Return a list of notes to include in documentation
sub allows_arg        { ... }    # True if an arg is allowed.
sub allows_autofill   { ... }    # True if autofill is allowed
sub allows_default    { ... }    # True if defaults are allowed
sub requires_autofill { ... }    # True if an auto-fill is allowed

# Change this to true if this option type can set an environment variable
sub can_set_env { 0 }

# You only need this if you can set an environment variable
get_env_value {
    my $self = shift;
    my ($envname, $ref) = @_;

    # For simple scalar values this is usually good enough
    # This should be the value to assign to environment variables that are
    # set by this option.
    return $$ref;
}

sub default_long_examples {
    my $self = shift;

    ...;

    return [' ARG', '=ARG'];    # If you require an argument
    return [''];                # If do not allow arguments
    return ['', '=ARG'];        # If arguments are optional
}

sub default_short_examples {
    my $self = shift;

    ...;

    return [' ARG', '=ARG'];    # If you require an argument
    return [''];                # If do not allow arguments
    return ['', '=ARG'];        # If arguments are optional
}

# Run right after the initial value for this option is set. Other options
# may not have their initial values yet.

sub init_settings {
    my $self = shift;
    my ($state, $settings, $group, $ref) = @_;

    ...
}

# Run after all the options have been set, parsed, and post-blocks have
# been run.
# This is run before the environment variable for this option has been set,
# but other options may have had theirs set.
sub finalize_settings {
    my $self = shift;
    my ($state, $settings, $group, $ref) = @_;

    ...
}

# Probably should not define these, but here for reference.
# Remove these if you do not plan to override them
# The base class implementations work for most types.
#######

sub clear_field        { ... }    # Used to clear the field
sub get_autofill_value { ... }    # Used to get the autofill value
sub get_default_value  { ... }    # Used to get the default value

1;

METHODS

CONSTRUCTION

$option = Getopt::Yath::Option->create(type => $type, %spec)

Factory method that creates an option of the appropriate subclass. $type can be a short name like 'Bool' (resolved to Getopt::Yath::Option::Bool), a fully qualified class name, or a +-prefixed class name for types outside the Getopt::Yath::Option:: namespace.

INTROSPECTION

$string = $option->trace_string()

Returns a human-readable string like "Foo.pm line 42" for error messages.

$forms = $option->forms()

Returns a hashref mapping all recognized command-line forms to their delta values. Positive delta (1) means the option sets a value, negative (-1) means it clears (the --no- prefix forms).

@args = $option->long_args()

Returns the primary name and all alternate names for this option.

$bool = $option->is_applicable($instance, $settings)

Returns true if this option should be active given the current state. Calls the applicable coderef if one was provided, otherwise returns true.

VALUE HANDLING

These methods are typically overridden by subclasses:

$bool = $option->requires_arg()

Must return true if the option requires an argument (e.g., --opt VALUE).

$option->add_value($ref, @values)

Store the given values into the scalar reference $ref. How values are stored depends on the option type.

$bool = $option->is_populated($ref)

Return true if $$ref contains a meaningful value (i.e., the option has been set).

@val = $option->no_arg_value($settings)

Return the value to use when the option is specified without an argument and without autofill. Only relevant for types like Bool and Count.

@val = $option->get_env_value($env_name, $ref)

Return the value to write to the named environment variable. Only needed when can_set_env returns true.

@val = $option->normalize_value(@input)

Pass values through the normalize callback if one was provided.

@bad = $option->check_value(\@values)

Check values against allowed_values if defined. Returns a list of values that failed validation.

$option->clear_field($ref)

Reset the option to its cleared state via get_clear_value.

$option->trigger(%params)

Invoke the trigger callback if one was provided.

DEFAULTS AND INITIALIZATION

$val = $option->get_initial_value($settings)

Returns the initial value for the option, checking from_env_vars first, then falling back to the initialize attribute.

@val = $option->get_default_value($settings)

Returns the default value from the default attribute.

@val = $option->get_autofill_value($settings)

Returns the autofill value from the autofill attribute.

$val = $option->get_clear_value()

Returns the value to use when the option is cleared (via --no-opt).

DOCUMENTATION

($forms, $no_forms) = $option->doc_forms(%params)

Returns two arrayrefs: one of the positive forms (e.g., --verbose, -v ARG) and one of the negative forms (e.g., --no-verbose). Used by the documentation generators.

$text = $option->cli_docs(%params)

Generate CLI help text for this option, including forms, description, environment variable notes, and allowed values.

$text = $option->pod_docs(%params)

Generate POD documentation for this option.

@examples = $option->long_examples(%params)
@examples = $option->short_examples(%params)

Return the example suffixes used in documentation (e.g., ' ARG', '=ARG'). Uses custom examples if provided, otherwise falls back to default_long_examples or default_short_examples.

HOOKS

$option->init_settings($state, $settings, $group, $ref)

Called right after the initial value is set for each option. Other options may not have their initial values yet. Override in subclasses for early setup.

$option->finalize_settings($state, $settings, $group, $ref)

Called after all options have been parsed and post-processors have run, but before environment variables are set. Override in subclasses for late adjustments.

EXAMPLES

See the following modules source for examples:

Getopt::Yath::Option::Scalar
Getopt::Yath::Option::Bool
Getopt::Yath::Option::Count
Getopt::Yath::Option::List
Getopt::Yath::Option::Map
Getopt::Yath::Option::Auto
Getopt::Yath::Option::AutoList
Getopt::Yath::Option::AutoMap
Getopt::Yath::Option::BoolMap
Getopt::Yath::Option::PathList
Getopt::Yath::Option::AutoPathList

SOURCE

The source code repository for Getopt-Yath can be found at http://github.com/Test-More/Getopt-Yath/.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

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

See http://dev.perl.org/licenses/