1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
NAME
String::Tagged::Terminal - format terminal output using String::Tagged
SYNOPSIS
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;
DESCRIPTION
This subclass of String::Tagged provides a method, build_terminal, for
outputting the formatting tags embedded in the string as terminal
escape sequences, to render the the output in the appropriate style.
TAGS
The following tag names are recognised:
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.
altfont
This tag takes an integer value. If defined it uses the "alternate font
selection" sequence.
fgindex, bgindex
These tags take an integer value in the range 0 to 255. These select
the foreground or background colour by using VGA, high-brightness
extended 16 colour, or xterm 256 palette mode attributes, depending on
the value.
The ECMA-48-corrected string encoding form of CSI 38:5:nnn m is used to
set the 256 palette values.
Values will be rounded down to the nearest integer by calling int().
This convenience allows things like the rand function for generating
random colours:
$st->append_tagged( "text", fgindex => 1 + rand 6 );
sizepos
Since version 0.06.
(experimental)
This tag takes a value indicating an adjustment to the vertical
positioning, and possibly also size, in order to create subscript or
superscript effects.
Recognised values are sub for subscript, and super for superscript.
These are implemented using the mintty-style CSI 73/74/75 m codes.
link
Since version 0.08.
(experimental)
This tag takes a HASH reference, whose uri key is emitted using the OSC
8 hyperlink sequence.
CONSTRUCTORS
new_from_formatting
$st = String::Tagged::Terminal->new_from_formatting( $fmt )
Returns a new instance by converting String::Tagged::Formatting
standard tags.
Foreground and background colours are converted to their nearest index
in the xterm 256 colour palette. The monospace Formatting attribute is
rendered by selecting the first alternate font using altfont.
parse_terminal
$st = String::Tagged::Terminal->parse_terminal( $str );
Since version 0.07.
Returns a new instance by parsing a string containing SGR terminal
escape sequences mixed with plain string content.
The parser will only accept 7- or 8-bit encodings of the SGR escape
sequence (\e[ ... m or \x9b ... m). If any other escape sequences are
present, an exception is thrown.
Conversely, unrecognised formatting codes in SGR sequences are simply
ignored without warning.
METHODS
The following methods are provided in addition to those provided by
String::Tagged.
build_terminal
$str = $st->build_terminal( %opts );
Returns a string containing terminal escape sequences mixed with string
content to render the string to a terminal.
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.
Takes the following additional named options:
no_color
If true, the fgindex and bgindex attributes will be ignored. This has
the result of performing some formatting using the other attributes,
but not setting colours.
as_formatting
$fmt = $st->as_formatting;
Returns a new String::Tagged instance tagged with
String::Tagged::Formatting standard tags.
print_to_terminal
$str->print_to_terminal( $fh );
Since version 0.03.
Prints the string to the terminal by building a terminal escape string
then printing it to the given IO handle (or STDOUT if not supplied).
This method will pass the value of the NO_COLOR environment variable to
the underlying "build_terminal" 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/.
say_to_terminal
$str->say_to_terminal( $fh );
Since version 0.03.
Prints the string to the terminal as per "print_to_terminal", followed
by a linefeed.
COMPATIBILITY NOTES
On Windows, the following notes apply:
* On all versions of Windows, the attributes bold, fgindex and
bgindex are supported. The bold 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.
* Starting with Windows 10, also under and reverse are supported.
* The attributes italic, strike, altfont, blink are not supported on
any Windows version.
* On Windows, only a single output console is supported.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
|
