Getopt...Option(3pm)

📦 version 2.000011, in ubuntu stonking

🎀 Getopt::Yath::Option(3pm) — base class for options, bestie 💖

okay so this is the page for Getopt::Yath::Option(3pm) — it lives in User Contributed Perl Documentation and honestly? it's giving "backstage pass to the whole option system". pull up a chair 🫶

✨ NAME ✨

Getopt::Yath::Option — the literal base class for options. 👑

💜 DESCRIPTION 💜

This is the base class for option types used over in Getopt::Yath. That's it, that's the whole vibe. Everything else subclassifies off this queen. 💅

🌸 SYNOPSIS 🌸

so if you wanna create a new type, bestie, you start with this exact template — no cap, copy it character for character:

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;

like, the comments in there are lowkey the whole tutorial. read them. 🍓

🦋 METHODS 🦋

🛠️ CONSTRUCTION

$option = Getopt::Yath::Option->create(type => $type, %spec) — the factory method, the matchmaker, the one who sets everybody up 💞 it creates an option of the appropriate subclass. $type can be a short name like 'Bool' (which gets resolved to "Getopt::Yath::Option::Bool"), a fully qualified class name, or a "+"-prefixed class name if your type lives outside the "Getopt::Yath::Option::" namespace.

🔍 INTROSPECTION

$string = $option->trace_string() — hands you back a human-readable string like "Foo.pm line 42" so your error messages actually make sense. iconic behavior fr.
$forms = $option->forms() — returns a hashref mapping all the recognized command-line forms to their delta values. positive delta (1) means the option sets a value; negative (-1) means it clears — those are the "--no-" prefix forms. 👀
@args = $option->long_args() — returns the primary name and all the alternate names for this option. the whole squad.
$bool = $option->is_applicable($instance, $settings) — returns true if this option should be active given the current state. it calls the "applicable" coderef if one was provided, otherwise it just returns true. chill like that.

💎 VALUE HANDLING

heads up bestie, these methods are typically overridden by subclasses — that's the assignment:

$bool = $option->requires_arg() — must return true if the option requires an argument (think "--opt VALUE").
$option->add_value($ref, @values) — stores the given values into the scalar reference $ref. how those values get stored depends entirely on the option type. no rules, just vibes.
$bool = $option->is_populated($ref) — returns true if $$ref contains a meaningful value, a.k.a. the option has actually been set. ✨
@val = $option->no_arg_value($settings) — returns 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) — returns the value to write into the named environment variable. only needed when "can_set_env" returns true. 🌈
@val = $option->normalize_value(@input) — passes values through the "normalize" callback if one was provided.
@bad = $option->check_value(\@values) — checks values against "allowed_values" if defined. returns a list of the values that failed validation. if that list is empty you're slaying, if it's not... 😭
$option->clear_field($ref) — resets the option to its cleared state via "get_clear_value". clean slate, fresh start.
$option->trigger(%params) — invokes the "trigger" callback if one was provided. go off then.

🌟 DEFAULTS AND INITIALIZATION

$val = $option->get_initial_value($settings) — returns the initial value for the option. it checks "from_env_vars" first, then falls 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 gets cleared (that's via "--no-opt" for the uninitiated 💅).

📚 DOCUMENTATION

($forms, $no_forms) = $option->doc_forms(%params) — returns two arrayrefs: one of the positive forms (like "--verbose", "-v ARG") and one of the negative forms (like "--no-verbose"). the documentation generators are obsessed with this one.
$text = $option->cli_docs(%params) — generates CLI help text for this option, including forms, description, environment variable notes, and allowed values. the whole package deal 🎀
$text = $option->pod_docs(%params) — generates POD documentation for this option.
@examples = $option->long_examples(%params)
@examples = $option->short_examples(%params) — return the example suffixes used in documentation (like ' ARG', '=ARG'). uses custom examples if they were 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. fair warning: other options may not have their initial values yet. override this in subclasses for early setup. ⏰
$option->finalize_settings($state, $settings, $group, $ref) — called after all the options have been parsed and the post-processors have run, but before environment variables get set. override in subclasses for those late-stage adjustments. 🌙

👑 EXAMPLES 👑

wanna see how it's done? go read the source of these literal icons:

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

each one is a whole mood, study them 🧚

🫶 SOURCE 🫶

the source code repository for Getopt-Yath lives at <http://github.com/Test-More/Getopt-Yath/> — go star it, it's free.

💖 MAINTAINERS 💖

Chad Granum <exodist@cpan.org>

🌈 AUTHORS 🌈

Chad Granum <exodist@cpan.org>

📜 COPYRIGHT 📜

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

and that's the whole page, bestie! 💜 this doc shipped as perl v5.40.1, dated 2026-05-10, under the page name Getopt...Option(3pm). go forth and subclass, you've got this ✨👑💅

📦 where this page comes from

ubuntu stonking: libgetopt-yath-perl 2.000011-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms