.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "String::Tagged::Formatting 3pm" .TH String::Tagged::Formatting 3pm "2023-10-04" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "String::Tagged::Formatting" \- an API specification for simple formatted strings .SH "DESCRIPTION" .IX Header "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 \s-1CPAN\s0 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. .PP 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. .SH "TAGS" .IX Header "TAGS" .SS "bold, under, italic, strike, blink, monospace" .IX Subsection "bold, under, italic, strike, blink, monospace" Tags with boolean values indicating bold, underline, italic, strikethrough, blinking and monospaced font. .SS "reverse" .IX Subsection "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. .SS "sizepos" .IX Subsection "sizepos" Tag with a string value inidicating sub\- or super-script effects. The value \&\f(CW"sub"\fR indicates subscript, and \f(CW"super"\fR indicates superscript. .PP 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. .SS "fg, bg" .IX Subsection "fg, bg" Tags with Convert::Color instances giving foreground and background colours. The use of a \f(CW\*(C`Convert::Color\*(C'\fR 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. .SH "METHODS" .IX Header "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. .SS "as_formatting" .IX Subsection "as_formatting" .Vb 1 \& $fmt = $st\->as_formatting .Ve .PP Called on an existing instance of the class, returns a \f(CW\*(C`String::Tagged\*(C'\fR 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. .PP Use of the \f(CW\*(C`clone\*(C'\fR method with \f(CW\*(C`only_tags\*(C'\fR and possibly a \f(CW\*(C`convert_tags\*(C'\fR map should be able to implement this in most cases. .SS "new_from_formatting" .IX Subsection "new_from_formatting" .Vb 1 \& $st = String::Tagged::Subclass\->new_from_formatting( $fmt ) .Ve .PP 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 \f(CW$fmt\fR 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. .PP Use of the \f(CW\*(C`clone\*(C'\fR method with \f(CW\*(C`only_tags\*(C'\fR and possibly a \f(CW\*(C`convert_tags\*(C'\fR map should be able to implement this in most cases. .SH "KNOWN IMPLEMENTATIONS" .IX Header "KNOWN IMPLEMENTATIONS" .IP "\(bu" 4 Net::Async::Matrix::Utils \- Contains a pair of functions to convert a formatted \fIMatrix\fR message body to and from this format. .IP "\(bu" 4 String::Tagged::HTML \- build \s-1HTML\s0 fragments by converting from this format .IP "\(bu" 4 String::Tagged::IRC \- parse or build \s-1IRC\s0 formatted messages and convert bidirectionally to this format. .IP "\(bu" 4 String::Tagged::Markdown \- parse and emit text with Markdown inline formatting and convert bidirectionally to this format. .IP "\(bu" 4 String::Tagged::Terminal \- build terminal control sequences for message formatting and convert bidirectionally to this format. .IP "\(bu" 4 Tickit::Widget::Scroller::Item::RichText \- has a constructor method that takes an instance of a tagged string in this format. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans