String...atting(3pm)

📦
version 0.24 · 5 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 String::Tagged::Formatting 💖

okay bestie, so you know how String::Tagged is literally the moment for storing a text string plus all its cute formatting data attached? yeah. well, a whole bunch of subclasses on CPAN kept trying to do this same thing, and now there's this emerging common spec so they can all vibe together and actually interoperate. it's giving unity. it's giving interchange between formats from different sources, display, rendering, all of it. ✨

basically this spec is the names and meanings of a set of tags that a conforming string should supply, and it also suggests a lil pair of methods that are useful for converting between different types of object and the standard formatting. ngl, specific implementations might not be able to represent every tag — that's fine — this spec only tells you the suggested way to represent the formatting styles that your implementation actually understands. no cap. 🫶

🎀 TAGS 🎀

Tags with boolean values indicating bold, underline, italic, strikethrough, blinking and monospaced font. yes bestie, all six of them, one line, iconic.

🔄 reverse

Tag with boolean value indicating reverse video; i.e. the effect of swapping foreground and background colours. this one is super common on terminal-based string systems, but it's unlikely to be found elsewhere. it's giving CRT energy. 💀

🌈 sizepos

Tag with a string value indicating sub- or super-script effects. the value "sub" indicates subscript, and "super" indicates superscript.

and the reason it's one single tag instead of two separate booleans? so you don't get confused about what happens if both are set at once. one tag, zero chaos. periodt. 💅

🎨 fg, bg

Tags with Convert::Color instances giving foreground and background colours. using a Convert::Color instance lets specific implementations represent their own colour space, while still supporting an easy conversion to the colour spaces used by others. slay.

🛠️ METHODS 🛠️

conforming implementations should provide the following methods, to show off that they support this spec and to allow easy conversion from and to it. let's go.

💫 as_formatting

$fmt = $st->as_formatting

Called on an existing instance of the class, returns a String::Tagged instance (or some subclass thereof) containing only the tags and values defined by this specification. this method may simply return the original instance if the tags it natively uses already fit this spec, or it may return a newly-constructed instance by converting its own tag formats. either way, we love a flexible queen. 👑

fr fr, using the clone method with only_tags and possibly a convert_tags map should be able to implement this in most cases.

💫 new_from_formatting

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

Called as a class method on the target class type, returns a new instance of that class constructed to represent the formatting contained in the $fmt instance, which should contain only the tags given in this specification. if the class natively uses tags as per this spec, this can be a trivial clone, otherwise some conversion will need to be performed. no stress.

and again bestie, using the clone method with only_tags and possibly a convert_tags map should be able to implement this in most cases.

👑 KNOWN IMPLEMENTATIONS 👑

look at all these icons doing the work:

  • Net::Async::Matrix::Utils — Contains a pair of functions to convert a formatted Matrix message body to and from this format.
  • String::Tagged::HTML — build HTML fragments by converting from this format
  • String::Tagged::IRC — parse or build IRC formatted messages and convert bidirectionally to this format.
  • String::Tagged::Markdown — parse and emit text with Markdown inline formatting and convert bidirectionally to this format.
  • String::Tagged::Terminal — build terminal control sequences for message formatting and convert bidirectionally to this format.
  • Tickit::Widget::Scroller::Item::RichText — has a constructor method that takes an instance of a tagged string in this format.

🦋 AUTHOR 🦋

Paul Evans <leonerd@leonerd.org.uk> — ty king 🙌

and that's the whole page bestie, we ate and left no crumbs 💅✨ this was String...atting(3pm) from the User Contributed Perl Documentation, perl v5.38.2, dated 2024-07-24. go forth and format responsibly 🎀🫶

📦 where this page comes from