String...rminal(3pm)

💖 String::Tagged::Terminal 💖

okay bestie so this is String::Tagged::Terminal, a whole module from the User Contributed Perl Documentation corner of the perl universe, and it's giving ✨aesthetic terminal output✨. fr fr.

---

🌸 NAME 🌸

String::Tagged::Terminal — format terminal output using String::Tagged. no cap, that's literally the whole thing.

---

🎀 SYNOPSIS 🎀

use String::Tagged::Terminal;

my $st = String::Tagged::Terminal->new
   ->append( "Hello my name is " )
   ->append_tagged( $name, bold => 1, fgindex => 4 );

$st->say_to_terminal;

look at her go 😭 she's so pretty and she just prints.

---

🦋 DESCRIPTION 🦋

so basically this is a subclass of String::Tagged (her iconic mother module 💅) and she brings one special gift to the group chat: a method called build_terminal. what does it do? it takes all the formatting tags you've tucked inside the string and turns them into actual terminal escape sequences, so your output renders in the right style when it hits the screen. it's giving glow-up. it's giving main character energy.

---

👑 TAGS 👑

these are the tag names she recognises. memorize them, bestie, they're on the exam:

✨ bold, under, italic, strike, blink, reverse ✨

these ones take a boolean value. if the value is true → the corresponding terminal rendering attribute gets switched on. that's it, that's the vibe.

✨ altfont ✨

takes an integer value. if it's defined, she uses the "alternate font selection" sequence. fancy. 🎩

✨ fgindex, bgindex ✨

these take an integer value in the range 0 to 255. they pick the foreground or background colour by using VGA, high-brightness extended 16 colour, or xterm 256 palette mode attributes — which one depends on the value you hand over.

the ECMA-48-corrected string encoding form of CSI 38:5:nnn m is what's used to set the 256 palette values.

values get rounded down to the nearest integer, by calling int(). and honestly? this convenience is a gift because it means you can do stuff like use the rand function to generate random colours:

$st->append_tagged( "text", fgindex => 1 + rand 6 );

random colour chaos, slay 🌈

✨ sizepos ✨

since version 0.06.

(experimental) — yes bestie, she said experimental, be careful.

this tag takes a value that indicates an adjustment to the vertical positioning, and possibly also the size, in order to create subscript or superscript effects.

the recognised values are sub for subscript and super for superscript. these get implemented using the mintty-style CSI 73/74/75 m codes. iykyk.

✨ link ✨

since version 0.08.

(experimental) — again, experimental, don't come for me.

this tag takes a HASH reference, whose uri key gets emitted using the OSC 8 hyperlink sequence. clickable text in the terminal, we love to see it 🔥

---

🧚 CONSTRUCTORS 🧚

💜 new_from_formatting 💜

$st = String::Tagged::Terminal->new_from_formatting( $fmt )

returns a new instance by converting String::Tagged::Formatting standard tags. 💫

foreground and background colours get converted to their nearest index in the xterm 256 colour palette. and the monospace Formatting attribute? she renders it by selecting the first alternate font using altfont. cute.

💜 parse_terminal 💜

$st = String::Tagged::Terminal->parse_terminal( $str );

since version 0.07.

returns a new instance by parsing a string that has SGR terminal escape sequences mixed in with plain string content.

now listen: the parser will only accept 7- or 8-bit encodings of the SGR escape sequence (\e[ ... m or \x9b ... m). if any other escape sequences show up? exception gets thrown. periodt. 💀

but conversely — and this is the chill part — unrecognised formatting codes inside SGR sequences are just simply ignored, no warning, no drama, nothing. 🙈

---

🌈 METHODS 🌈

these are the methods she provides in addition to everything String::Tagged already gives you. so many gifts.

⭐ build_terminal ⭐

$str = $st->build_terminal( %opts );

returns a string containing terminal escape sequences mixed with string content, so the whole thing renders to a terminal. ✨

careful bestie — since this string contains literal terminal control escape sequences, you should be careful when passing it around, printing it for debugging purposes, or doing anything similar. she's powerful and she's loud.

takes the following additional named options:

• no_color — if true, the fgindex and bgindex attributes get ignored. the result of this is that some formatting still happens using the other attributes, but colours are simply not set. monochrome moment 🖤

⭐ as_formatting ⭐

$fmt = $st->as_formatting;

returns a new String::Tagged instance tagged with String::Tagged::Formatting standard tags. she's bilingual, she translates. 🫶

⭐ print_to_terminal ⭐

$str->print_to_terminal( $fh );

since version 0.03.

prints the string to the terminal by building a terminal escape string, then printing it to the given IO handle — or STDOUT if you didn't supply one. no handle? she'll figure it out. 💅

this method passes the value of the NO_COLOR environment variable down to the underlying build_terminal method call. meaning: if that variable has a true value, then colouring tags get ignored and you get a monochrome output. this follows the suggestion of <http://no-color.org/>. respect the environment variable, bestie 🌱

⭐ say_to_terminal ⭐

$str->say_to_terminal( $fh );

since version 0.03.

prints the string to the terminal exactly like print_to_terminal does, and then follows it up with a linefeed. she says it. she adds the lil newline. iconic. 🎤

---

💀 COMPATIBILITY NOTES 💀

on Windows, the following notes apply — read them, i'm not joking:

• On all versions of Windows, the attributes bold, fgindex and bgindex are supported. the bold attribute is implemented by using high-intensity colours, so it will be indistinguishable from using high-intensity colour indexes without bold. also the full 256-color palette is not supported by Windows, so it gets down-converted to the 16 colours that are. tragic, honestly 😭
• Starting with Windows 10, under and reverse are also supported. progress!
• The attributes italic, strike, altfont, blink are not supported on any Windows version. at all. zero. nada. 💀
• On Windows, only a single output console is supported.

---

🌸 AUTHOR 🌸

Paul Evans <leonerd@leonerd.org.uk> — the legend, the icon, the moment 👑

---

okay that's the whole page bestie, you're officially certified 💖 go format some terminal output and make it gorgeous ✨

this has been String::Tagged::Terminal from the User Contributed Perl Documentation, perl v5.38.2, dated 2024-08-03 — mwah, love u, bye 🫶🎀🦋