1NAME
2
3    String::Tagged::Terminal - format terminal output using String::Tagged
4
5SYNOPSIS
6
7     use String::Tagged::Terminal;
8
9     my $st = String::Tagged::Terminal->new
10        ->append( "Hello my name is " )
11        ->append_tagged( $name, bold => 1, fgindex => 4 );
12
13     $st->say_to_terminal;
14
15DESCRIPTION
16
17    This subclass of String::Tagged provides a method, build_terminal, for
18    outputting the formatting tags embedded in the string as terminal
19    escape sequences, to render the the output in the appropriate style.
20
21TAGS
22
23    The following tag names are recognised:
24
25 bold, under, italic, strike, blink, reverse
26
27    These tags take a boolean value. If the value is true then the
28    corresponding terminal rendering attribute is enabled.
29
30 altfont
31
32    This tag takes an integer value. If defined it uses the "alternate font
33    selection" sequence.
34
35 fgindex, bgindex
36
37    These tags take an integer value in the range 0 to 255. These select
38    the foreground or background colour by using VGA, high-brightness
39    extended 16 colour, or xterm 256 palette mode attributes, depending on
40    the value.
41
42    The ECMA-48-corrected string encoding form of CSI 38:5:nnn m is used to
43    set the 256 palette values.
44
45    Values will be rounded down to the nearest integer by calling int().
46    This convenience allows things like the rand function for generating
47    random colours:
48
49       $st->append_tagged( "text", fgindex => 1 + rand 6 );
50
51CONSTRUCTORS
52
53 new_from_formatting
54
55       $st = String::Tagged::Terminal->new_from_formatting( $fmt )
56
57    Returns a new instance by converting String::Tagged::Formatting
58    standard tags.
59
60    Foreground and background colours are converted to their nearest index
61    in the xterm 256 colour palette. The monospace Formatting attribute is
62    rendered by selecting the first alternate font using altfont.
63
64METHODS
65
66    The following methods are provided in addition to those provided by
67    String::Tagged.
68
69 build_terminal
70
71       $str = $st->build_terminal( %opts )
72
73    Returns a string containing terminal escape sequences mixed with string
74    content to render the string to a terminal.
75
76    As this string will contain literal terminal control escape sequences,
77    care should be taken when passing it around, printing it for debugging
78    purposes, or similar.
79
80    Takes the following additional named options:
81
82    no_color
83
84      If true, the fgindex and bgindex attributes will be ignored. This has
85      the result of performing some formatting using the other attributes,
86      but not setting colours.
87
88 as_formatting
89
90       $fmt = $st->as_formatting
91
92    Returns a new String::Tagged instance tagged with
93    String::Tagged::Formatting standard tags.
94
95 print_to_terminal
96
97       $str->print_to_terminal( $fh )
98
99    Since version 0.03.
100
101    Prints the string to the terminal by building a terminal escape string
102    then printing it to the given IO handle (or STDOUT if not supplied).
103
104    This method will pass the value of the NO_COLOR environment variable to
105    the underlying "build_terminal" method call, meaning if that has a true
106    value then colouring tags will be ignored, yielding a monochrome
107    output. This follows the suggestion of http://no-color.org/.
108
109 say_to_terminal
110
111       $str->say_to_terminal( $fh )
112
113    Since version 0.03.
114
115    Prints the string to the terminal as per "print_to_terminal", followed
116    by a linefeed.
117
118COMPATIBILITY NOTES
119
120    On Windows, the following notes apply:
121
122      * On all versions of Windows, the attributes bold, fgindex and
123      bgindex are supported. The bold attribute is implemented by using
124      high-intensity colours, so will be indistinguishable from using
125      high-intensity colour indexes without bold. The full 256-color
126      palette is not supported by Windows, so it is down-converted to the
127      16 colours that are.
128
129      * Starting with Windows 10, also under and reverse are supported.
130
131      * The attributes italic, strike, altfont, blink are not supported on
132      any Windows version.
133
134      * On Windows, only a single output console is supported.
135
136TODO
137
138      * Consider a ->parse_terminal constructor method, which would attempt
139      to parse SGR sequences from a given source string.
140
141AUTHOR
142
143    Paul Evans <leonerd@leonerd.org.uk>
144
145