Getopt::Yath::Option(3)

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/>