NAME

       "String::Tagged::Formatting" - an API specification for simple formatted strings

DESCRIPTION

       A primary use case of String::Tagged is to allow storage of a text string with associated formatting
       data. As there are a growing number of subclasses on CPAN that attempt to do this, a common specification
       is emerging to allow interoperability between them. This will allow interchange between formats from
       different sources, display or rendering, and so on.

       Primarily this specification consists of the names and meanings of a set of tags that a conforming string
       should supply, though it also suggests a pair of methods useful for converting between different types of
       object and the standard formatting. Specific implementations may not be able to represent all of the tags
       of course; this specification only gives the suggested way to represent those formatting styles that the
       implementation actually understands.

TAGS

   bold, under, italic, strike, blink, monospace
       Tags with boolean values indicating bold, underline, italic, strikethrough, blinking and monospaced font.

   reverse
       Tag with boolean value indicating reverse video; i.e. the effect of swapping foreground and background
       colours. This effect is common on terminal-based string systems, but is unlikely to be found elsewhere.

   sizepos
       Tag with a string value inidicating sub- or super-script effects. The value "sub" indicates subscript,
       and "super" indicates superscript.

       One single tag is used for both rather than using two separate booleans in order to avoid confusion over
       what would happen if both are set at once.

   fg, bg
       Tags with Convert::Color instances giving foreground and background colours. The use of a
       "Convert::Color" instance allows specific implementations to be able to represent their own colour space,
       while still supporting an easy conversion to the colour spaces used by others.

METHODS

       The following methods should be provided on conforming implementations, to indicate their support of this
       specification and to allow easy conversion from and to it.

   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 natively used by it already fit this specification, or it may return a
       newly-constructed instance by converting its own tag formats.

       Use of 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 specification, this can be a trivial clone,
       otherwise some conversion will need to be performed.

       Use of the "clone" method with "only_tags" and possibly a "convert_tags" map should be able to implement
       this in most cases.

KNOWN IMPLEMENTATIONS

       •   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>

perl v5.38.2                                       2024-07-24                    String::Tagged::Formatting(3pm)