Getopt...stance(3pm)

💖 Getopt::Yath::Instance — the manual page, but make it a group chat 💖

okay bestie, so this is the Getopt::Yath::Instance page from the User Contributed Perl Documentation (manual name: Getopt...stance(3pm) — yeah it's giving "my name got truncated by the terminal", iconic). Sit down, hydrate, and let's talk about an instance of options. 🫶

---

✨ NAME ✨

Getopt::Yath::Instance — an instance of options. that's it, that's the whole vibe. an instance. of options. 💅

---

🌸 DESCRIPTION 🌸

okay so here's the tea: this module does the real work for Getopt::Yath under the hood. it's the engine, the backstage crew, the little guy running around making everything happen while the star takes the bow. 🎀

and because of that — it is probably better not to use this directly.

like. it's not for you bestie. no cap. 🫣

---

🦋 SYNOPSIS 🦋

Do not use this directly. The user interface you should be looking at is Getopt::Yath.

that's the entire synopsis. it's four words of "don't". the audacity. the confidence. we love a boundary-setting manpage. ✨

---

👑 METHODS 👑

get into it, here's every single one, no skipping, we don't do that here:

• $state = $instance->process_args(\@argv, %params) — okay so this one parses the given argument list according to the defined options. what you get back is a Getopt::Yath::State object, and that lil guy has the "settings", "skipped", "remains", "stop", "cleared", "modules", and "env" accessors. if you want the full list of parameters, go check Getopt::Yath, and for the returned object go check Getopt::Yath::State. 🧚
• $option = $instance->add_option(%option_spec) — adds a brand new option to this instance. the %option_spec gets passed directly to "create" in Getopt::Yath::Option. no middleman, no filtering, straight through. 💫
• $instance->add_post_process($weight, $applicable, $callback) — registers a post-processing callback. so: $weight controls the ordering (lower runs first — remember that, it's the whole point), $applicable is an optional coderef filter, and $callback is the coderef that actually runs after parsing. 🎯
• $instance->include($other_instance) $instance->include($other_instance, \@list) — merges options and post-processors from another instance into this one. and if you pass "\@list", then only options whose title, field, or name appears in that list get included. so it's a guest list, basically. bouncer energy. 🚪
• $text = $instance->docs($format, %params) — generates documentation for all applicable options. $format must be 'cli' or 'pod'. those are your only two, don't try anything else. the params can include:
  • head => $level — the heading level for POD output (like, 2 for "=head2").
  • group => $group_name — only show options from the specified group.
  • settings => $settings — an Getopt::Yath::Settings object used to evaluate option applicability.
  • applicable => $bool — if true, include all options regardless of their applicability filter. yes, all of them. no filtering, full chaos. 🔥
  • color => $bool — turns ANSI color on or off in CLI output. defaults to true if color is available and STDOUT is a terminal.
• $map = $instance->option_map() $map = $instance->option_map(\@options) — returns a hashref mapping all option forms (like "--verbose", "-v", "--no-verbose") to their Getopt::Yath::Option objects. it also includes a "custom_match" key holding an arrayref of custom match coderefs. and heads up: results are cached unless you provide an explicit option list. 🍓
• $groups = $instance->option_groups() — returns a hashref of the group names defined by the current options. results are cached. 💜
• $bool = $instance->have_group($name) — returns true if any option defines the given group name. simple. clean. does exactly one thing. we stan. ✅
• $instance->set_category_sort_map(%map) — sets the sort ordering for documentation categories. see "category_sort_map" in Getopt::Yath. 📚
• $options = $instance->options() — returns the arrayref of Getopt::Yath::Option objects registered in this instance. the whole roster. the full squad. 🌈

---

🔗 SOURCE 🔗

the source code repository for Getopt-Yath can be found at <http://github.com/Test-More/Getopt-Yath/>.

go look. go star it. go read the code. main character behavior. ⭐

---

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

---

and that's the page bestie!! 🎀 perl v5.40.1, dated 2026-05-10, filed under Getopt...stance(3pm) — mwah, slay, go parse some args responsibly, drink water, and do not use this directly. periodt. 💅✨