.\" 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::Terminal 3pm"
.TH String::Tagged::Terminal 3pm "2023-02-10" "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::Terminal" \- format terminal output using "String::Tagged"
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   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;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This subclass of String::Tagged provides a method, \f(CW\*(C`build_terminal\*(C'\fR,
for outputting the formatting tags embedded in the string as terminal escape
sequences, to render the the output in the appropriate style.
.SH "TAGS"
.IX Header "TAGS"
The following tag names are recognised:
.SS "bold, under, italic, strike, blink, reverse"
.IX Subsection "bold, under, italic, strike, blink, reverse"
These tags take a boolean value. If the value is true then the corresponding
terminal rendering attribute is enabled.
.SS "altfont"
.IX Subsection "altfont"
This tag takes an integer value. If defined it uses the \*(L"alternate font
selection\*(R" sequence.
.SS "fgindex, bgindex"
.IX Subsection "fgindex, bgindex"
These tags take an integer value in the range 0 to 255. These select the
foreground or background colour by using \s-1VGA,\s0 high-brightness extended 16
colour, or xterm 256 palette mode attributes, depending on the value.
.PP
The ECMA\-48\-corrected string encoding form of \f(CW\*(C`CSI 38:5:nnn m\*(C'\fR is used to set
the 256 palette values.
.PP
Values will be rounded down to the nearest integer by calling \f(CW\*(C`int()\*(C'\fR. This
convenience allows things like the \f(CW\*(C`rand\*(C'\fR function for generating random
colours:
.PP
.Vb 1
\&   $st\->append_tagged( "text", fgindex => 1 + rand 6 );
.Ve
.SS "sizepos"
.IX Subsection "sizepos"
(experimental)
.PP
This tag takes a value indicating an adjustment to the vertical positioning,
and possibly also size, in order to create subscript or superscript effects.
.PP
Recognised values are \f(CW\*(C`sub\*(C'\fR for subscript, and \f(CW\*(C`super\*(C'\fR for superscript.
These are implemented using the \fImintty\fR\-style \f(CW\*(C`CSI 73/74/75 m\*(C'\fR codes.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.SS "new_from_formatting"
.IX Subsection "new_from_formatting"
.Vb 1
\&   $st = String::Tagged::Terminal\->new_from_formatting( $fmt )
.Ve
.PP
Returns a new instance by converting String::Tagged::Formatting standard
tags.
.PP
Foreground and background colours are converted to their nearest index in the
xterm 256 colour palette. The \f(CW\*(C`monospace\*(C'\fR Formatting attribute is rendered by
selecting the first alternate font using \f(CW\*(C`altfont\*(C'\fR.
.SH "METHODS"
.IX Header "METHODS"
The following methods are provided in addition to those provided by
String::Tagged.
.SS "build_terminal"
.IX Subsection "build_terminal"
.Vb 1
\&   $str = $st\->build_terminal( %opts )
.Ve
.PP
Returns a string containing terminal escape sequences mixed with string
content to render the string to a terminal.
.PP
As this string will contain literal terminal control escape sequences, care
should be taken when passing it around, printing it for debugging purposes, or
similar.
.PP
Takes the following additional named options:
.IP "no_color" 4
.IX Item "no_color"
If true, the \f(CW\*(C`fgindex\*(C'\fR and \f(CW\*(C`bgindex\*(C'\fR attributes will be ignored. This has
the result of performing some formatting using the other attributes, but not
setting colours.
.SS "as_formatting"
.IX Subsection "as_formatting"
.Vb 1
\&   $fmt = $st\->as_formatting
.Ve
.PP
Returns a new \f(CW\*(C`String::Tagged\*(C'\fR instance tagged with
String::Tagged::Formatting standard tags.
.SS "print_to_terminal"
.IX Subsection "print_to_terminal"
.Vb 1
\&   $str\->print_to_terminal( $fh )
.Ve
.PP
\&\fISince version 0.03.\fR
.PP
Prints the string to the terminal by building a terminal escape string then
printing it to the given \s-1IO\s0 handle (or \f(CW\*(C`STDOUT\*(C'\fR if not supplied).
.PP
This method will pass the value of the \f(CW\*(C`NO_COLOR\*(C'\fR environment variable to the
underlying \*(L"build_terminal\*(R" method call, meaning if that has a true value
then colouring tags will be ignored, yielding a monochrome output. This
follows the suggestion of <http://no\-color.org/>.
.SS "say_to_terminal"
.IX Subsection "say_to_terminal"
.Vb 1
\&   $str\->say_to_terminal( $fh )
.Ve
.PP
\&\fISince version 0.03.\fR
.PP
Prints the string to the terminal as per \*(L"print_to_terminal\*(R", followed by a
linefeed.
.SH "COMPATIBILITY NOTES"
.IX Header "COMPATIBILITY NOTES"
On Windows, the following notes apply:
.IP "\(bu" 4
On all versions of Windows, the attributes \f(CW\*(C`bold\*(C'\fR, \f(CW\*(C`fgindex\*(C'\fR and \f(CW\*(C`bgindex\*(C'\fR
are supported. The \f(CW\*(C`bold\*(C'\fR attribute is implemented by using high-intensity
colours, so will be indistinguishable from using high-intensity colour indexes
without bold. The full 256\-color palette is not supported by Windows, so it is
down-converted to the 16 colours that are.
.IP "\(bu" 4
Starting with Windows 10, also \f(CW\*(C`under\*(C'\fR and \f(CW\*(C`reverse\*(C'\fR are supported.
.IP "\(bu" 4
The attributes \f(CW\*(C`italic\*(C'\fR, \f(CW\*(C`strike\*(C'\fR, \f(CW\*(C`altfont\*(C'\fR, \f(CW\*(C`blink\*(C'\fR are not supported on
any Windows version.
.IP "\(bu" 4
On Windows, only a single output console is supported.
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
Consider a \f(CW\*(C`\->parse_terminal\*(C'\fR constructor method, which would attempt to
parse \s-1SGR\s0 sequences from a given source string.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>