Comman...:Output(3pm)

✨ Commandable::Output ✨

okay so bestie, welcome to the Comman...:Output(3pm) page — it's part of the User Contributed Perl Documentation and honestly it's giving "quiet little module that does a LOT of the vibes work" 💅

💖 NAME 💖

Commandable::Output — abstractions for printing output from commands 🎀

---

🌸 DESCRIPTION 🌸

So this package is basically the default outfit for all the methods that print stuff out from commands built with Commandable. They're here for user code's convenience, but also — plot twist — the built-in commands that ship with the Commandable system itself use them too. ✨

And here's the thing: implementations are permitted to replace any of these methods to customise how they behave. Like, encouraged, even. Go off, honestly. 🫶

🦋 WITH String::Tagged 🦋

If String::Tagged and Convert::Color are around, this module starts doing formatting to strings using the String::Tagged::Formatting conventions. The format_heading and format_note methods will hand back results as instances of String::Tagged, which are perfect to pass straight into the main printf method. slay 💖

---

👑 METHODS 👑

🍓 printf

Commandable::Output->printf( $format, @args );

This is the main output method — the one you use to send messages out for the user to see. The arguments get formatted into a single string by Perl's printf function. And listen: this method does not append a linefeed. So if you want a whole complete line of text, don't forget to put the "\n" at the end of your format string. no cap, everybody forgets this. 😭

The default implementation writes output to the terminal via STDOUT.

But if your output needs to go somewhere else entirely — like, say, some kind of GUI display widget situation — then the application should swap this method out for something that writes the display somewhere more appropriate. And don't forget to use sprintf to format the arguments into a string, bestie. 💅

no warnings 'redefine';
sub Commandable::Output::printf
{
   shift; # the package name
   my ( $format, @args ) = @_;

   my $str = sprintf $format, @args;

   $gui_display_widget->append_text( $str );
}

Oh and — if String::Tagged::Terminal is available, the output gets printed using that module instead. How? It first converts the format string and arguments using from_sprintf in String::Tagged, and then constructs a terminal string using new_from_formatting in String::Tagged::Terminal. Which means the default implementation can output formatted strings using the String::Tagged::Formatting conventions. iconic behaviour honestly 🌈

🧚 print_heading

Commandable::Output->print_heading( $text, $level );

Sends output that should be treated like a section heading. 📢

$level can be an integer used to express sub-levels — values going up from 1 upwards mean increasing sub-levels. So like, level 1 is your main character, level 2 is its sub, level 3 is the sub's sub. you get it. 👑

The default implementation formats the text string using format_heading, then prints it using printf with a trailing linefeed.

🌟 format_heading

$str = Commandable::Output->format_heading( $text, $level );

Returns a value for printing that represents a section heading for the given text and level. 🎀

The default implementation applies this formatting if String::Tagged is available:

• Level 1 — Underlined
• Level 2 — Underlined, cyan colour
• Level 3 — Bold

💜 format_note

$str = Commandable::Output->format_note( $text, $level );

Returns a value for printing that somehow highlights the given text — which should be a short word or string — at the given level. ✨

The default implementation applies this formatting if String::Tagged is available:

• Level 0 — Bold, yellow colour
• Level 1 — Bold, cyan colour
• Level 2 — Bold, magenta colour

---

🫶 AUTHOR 🫶

Paul Evans <leonerd@leonerd.org.uk> — thank you for your service, king 👑

---

okay that's the whole page bestie, you're officially educated 💖 the source/version energy on this one is perl v5.40.0, dated 2024-09-08, and yeah — it's literally the Comman...:Output(3pm) manual, so go forth and print pretty things 🌸💅✨