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/