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 Test2::Harness::Util::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;

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

SOURCE

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

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/