App::Y...ptions(3pm)

📦
version 1.000172 · 8 versions
, in ubuntu stonking

💖 App::Yath::Options 💖

okay bestie, welcome to App::Yath::Options — that's the Perl package doc, straight out of the User Contributed Perl Documentation shelf. sit down, grab a strawberry 🍓, we're building CLI options today.

✨ NAME ✨

App::Yath::Options — the tools for defining and tracking yath CLI options. that's it, that's the whole vibe. no cap. 👑

🌸 DESCRIPTION 🌸

okay so picture this: this class is basically a collection of options, and it's also holding all the logic for processing them. like, it's the group chat admin of your CLI flags. 💅

and plot twist — this package also exports sugar 🍬 to help you define options, because writing option definitions by hand is giving ✨unnecessary suffering✨ and we don't do that here.

🦋 SYNOPSIS 🦋

here's the whole thing, bestie, in all its glory:

package My::Options;

use App::Yath::Options;

# This package now has a package instance of options, which can be obtained
# via the options() method.
my $options = __PACKAGE__->options;

# We can include options from other packages
include_options(
    'Package::With::Options::A',
    'Package::With::Options::B',
    ...,
);

# Define an option group with some options
option_group { %common_fields } => sub {

    # Define an option
    option foo => (
        type => 's',
        default => "FOOOOOOO",
        category => 'foo',
        description => "This is foo"
        long_examples => [' value'],
        ...
    );

    option bar => ( ... );
    ...
};

# Action to call right after options are parsed.
post sub {
    my %params = @_;

    ...
};

like… look at it. it's clean. it's iconic. it ate. 🔥

🎀 EXPORTS 🎀

these are the lil gifts this package hands you. every single one, no skipping:

  • $opts = options()
  • $opts = $class->options()

this hands you back the options instance that's associated with your package. your very own options bestie. 🫶

  • include_options(@CLASSES)

this is the "let me borrow your options real quick" function — it lets you include options defined in other packages. sharing is caring, periodt.

  • option_group \%COMMON_FIELDS => sub { ... }

okay so an option group is literally just a block where every single call to option() automatically gets those common fields added on top. it makes defining a bunch of options that share fields so much easier, like, you're not retyping the same thing forty times. 🙈

and the common fields can be overridden inside any individual option definition, so you're never stuck.

these two are both doing the exact same thing, fyi:

# Using option group
option_group { category => 'foo', prefix => 'foo' } => sub {
    option a => (type => 'b');
    option b => (type => 's');
};

# Not using option group
option a => (type => 'b', category => 'foo', prefix => 'foo');
option b => (type => 's', category => 'foo', prefix => 'foo');

same energy. same result. one of them is just prettier. 💅

  • option TITLE => %FIELDS

define an option, bestie! the first argument is the "title" attribute for your shiny new option, and every argument after that should be attribute/value pairs used to construct the option. want the whole 411 on attributes? go peek at App::Yath::Option, it's all documented over there. 📚

  • post sub { ... }
  • post $weight => sub { ... }

post callbacks run after all the command line arguments have been processed. so this is your moment to verify how several options look when combined, do a lil sanity check, or even add short-circuit behavior. this is, in fact, exactly how the --help and --show-opts options get implemented. main character behavior honestly. ⭐

if you don't specify a $weight, then 0 is used. post callbacks get sorted based on weight, and higher values run later. so if you need something to happen last, give it the big number. 👑

💜 OPTIONS INSTANCES 💜

so like, generally speaking, you should not be touching the options instance directly. it's mostly an implementation detail and you should treat it like a black box — mysterious, pretty, don't open it. 🎁

but there are a few legit reasons to interact with one directly. in those cases, here are the public attributes/methods you can work with. this section documents the public interface. everything else? internal. hands off. 🙅

💅 ATTRIBUTES 💅

this only lists the attributes that might actually be useful to people working with options instances. there are a ton of internal (to yath) attributes that are implementation details and are not listed here. anything not listed here is not meant for external use and may change at any time. consider yourself warned, bestie. 😭

  • $arrayref = $options->all

an arrayref holding all the App::Yath::Option instances in the options instance. all of them. the whole squad. 👯

  • $settings = $options->settings

grab the Test2::Harness::Settings instance. easy.

  • $arrayref = $options->args

get the reference to the list of command line arguments. heads up: this list gets modified as arguments are processed, and there are literally no guarantees about what's in here at any given stage of argument processing. it's giving chaotic and we accept that. 🌪️

  • $class_name = $options->command_class

if yath has figured out what command is being executed, this gets populated with the command class. if the class hasn't been determined yet, it'll be undefined. patience, babe. 🧘

  • $arrayref = $options->used_plugins

a list of all the plugins whose options have been used. and yes — plugins may appear more than once in this list. it's fine. it's fine.

  • $hashref = $options->included

a hashref where every key is a package whose options have been included into this options instance. the values are an implementation detail — do not rely on them. literally just don't. 💀

🌈 METHODS 🌈

same deal, this only lists the methods that may be useful to people working with options instances. there are a lot of internal (to yath) methods that are implementation details and are not listed here. methods not listed here are not intended for external use and may change at any time. 📌

  • $opt = $options->option(%OPTION_ATTRIBUTES)

this creates a brand new option with the attributes you pass in and adds it to the options instance. a "trace" attribute gets set for you automatically, so you don't even have to think about it. 🎀

  • $options->include($options_instance)

this one lets you directly include options from a second instance into the first. copy-paste but make it official.

  • $options->include_from(@CLASSES)

lets you include options from multiple classes that have options defined. the more the merrier. 🦋

  • $options->include_option($opt)

this lets you include a single already defined option instance. one (1) option, hand-picked, VIP treatment. 👑

  • $options->pre_docs($format, @args)

get documentation for pre-command options. $format can be 'cli' or 'pod'. that's the whole menu. 🍽️

  • $options->cmd_docs($format, @args)

get documentation for command options. $format can be 'cli' or 'pod'. same menu, different section. ✨

🔥 SOURCE 🔥

the source code repository for Test2-Harness lives right here:

http://github.com/Test-More/Test2-Harness/

go. look. contribute. slay. 💖

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org>

⭐ AUTHORS ⭐

Chad Granum <exodist@cpan.org>

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

and that's the whole page, bestie 💖 this was App::Yath::Options from the perl v5.40.1 docs, dated 2026-05-10, brought to you by the fine folks at User Contributed Perl Documentation. drink some water, go write some options, ily 🫶✨

📦 where this page comes from