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

📦
version 1.000172 · 8 versions
, in ubuntu stonking

💖 App::Yath::Command(3pm) — the vibe 💖

okay bestie, welcome to App::Yath::Command, aka the base class for every single yath command. like, all of them. every one. this is the blueprint, the blueprint-est blueprint. 🫶

✨ NAME ✨

App::Yath::Command — it's literally the base class for yath commands. that's the whole job description. 👑

🌸 DESCRIPTION 🌸

so this is the parent class for any and all yath commands, no exceptions, no cap. if you wanna add a shiny new yath command of your own? you subclass this package. that's it, that's the door, come on in. 💅

🦋 SYNOPSIS 🦋

here's the whole ritual, copy it exactly:

package App::Yath::Command::mycommand;
use strict;
use warnings;

use App::Yath::Options();
use parent 'App::Yath::Command';

# Include existing option sets
include_options(
    'App::Yath::Options::Debug',
    'App::Yath::Options::PreCommand',
    ...,
);

# Add some custom options
option_group {prefix => 'mycommand', category => 'mycommand options'} => sub {
    option foo => (
        description => "the foo option",
        default     => 0,
    );
};

# This is used to sort/group commands in the "yath help" output
sub group { 'thirdparty' }

# Brief 1-line summary
sub summary { "This is a third party command, it does stuff..." }

# Longer description of the command (used in yath help mycommand)
sub description {
    return <<"    EOT";
This command does:
This
That
Those
    EOT
}

# Entrypoint
sub run {
    my $self = shift;

    my $settings = $self->settings;
    my $args     = $self->args;

    print "Hello Third Party!\n"

    # Return an exit value.
    return 0;
}

iconic. genuinely ate. ✨

💅 CLASS METHODS 💅

watch closely, these are the class-level ones:

  • $string = $cmd_class->cli_help(settings => $settings, options => $options) — this generates the command line help for whatever command you throw at it. and ngl? you are generally NOT gonna wanna override this one. it's doing great actually. $settings should be an instance of Test2::Harness::Settings. and $options should be an instance of App::Yath::Options if you provide it — but lowkey this method is usually smart enough to fill in the details itself when you leave it out. 🧚
  • $multi_line_string = $cmd_class->description() — the long-form description of the command. this is the one used inside cli_help(). 📝
  • @list = $cmd_class->doc_args() — gives you a list of argument names for the command, which gets used to generate documentation. 🎀
  • $string = $cmd_class->generate_pod() — this can generate POD documentation straight from the command itself, using all the other fields listed in this section, plus all the applicable command line options specified in the command. self-documenting queen behavior. 💜
  • $string = $cmd_class->group() — used for sorting/grouping commands in the "yath help" output. the existing groups are:
' test'     # Space in front to make sure test related command float up
'log'       # Log processing commands
'persist'   # Commands related to the persistent runner
'zinit'     # The init command and related command sink to the bottom.

okay so unless your command OBVIOUSLY and CLEARLY belongs in one of the groups up there, you should probably just make your own group, fr fr. and please do not prefix it with a space to make it float — ' test' is a special case, you are not that special. 😭 (affectionate)

  • $string = $cmd_class->name() — the name of the command. by default it's the last part of the package name. you will probably never, ever want to override this. please don't. 🙈
  • $short_string = $cmd_class->summary() — a short summary of what this command is. the lil one-liner intro. 🌸

🎀 OBJECT METHODS 🎀

and now the instance-level ones:

  • $bool = $cmd->always_keep_dir() — by default the working directory gets deleted when yath exits 💀. some commands, like App::Yath::Command::start, need to keep that directory around. so override this method and return true if your command uses the workdir and needs it to survive. 📁
  • $arrayref = $cmd->args() — get an arrayref of the command line arguments AFTER options have been process/removed. so like, the leftovers. the after-party of args. ✨
  • $bool = $cmd->internal_only() — set this to true if you do not want your command showing up in the help output. secret menu energy, iykyk. 🤫
  • $exit_code = $cmd->run() — this is the main entrypoint for the command. you MUST override this one, no skipping bestie. and this method should return an exit code. 🏁
  • $settings = $cmd->settings() — get the settings as populated by the command line options. 🫶
  • $cmd->write_settings_to($directory, $filename) — a lil helper method that writes the settings to a specified directory and filename. the file gets written as JSON. 📄

here's a heads up tho: if you're subclassing another command like App::Yath::Command::test, you may want to override this to a no-op so the settings file doesn't get written at all — the App::Yath::Command:run command does exactly that. 💜

🔥 SOURCE 🔥

the source code repository for Test2-Harness lives at http://github.com/Test-More/Test2-Harness/. go peek, it's giving open source royalty. 👑

🌈 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 lil beauty comes from perl v5.40.1, dated 2026-05-10, and yes the manpage header is out here looking like App::Y...ommand(3pm) — truncated for the drama of it all. periodt. 🎀🦋💜

📦 where this page comes from