-
-
18 Jun 2021 10:45:13 UTC
- Distribution: String-Tagged-Terminal
- Module version: 0.05
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Issues (0)
- Testers (968 / 0 / 0)
- Kwalitee
Bus factor: 1- 76.70% Coverage
- License: perl_5
- Perl: v5.14.0
- Activity
24 month- Tools
- Download (17.48KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- Convert::Color
- Convert::Color::XTerm
- String::Tagged
- constant
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
NAME
String::Tagged::Terminal
- format terminal output usingString::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 therand
function for generating random colours:$st->append_tagged( "text", fgindex => 1 + rand 6 );
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 usingaltfont
.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
andbgindex
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
andbgindex
are supported. Thebold
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
andreverse
are supported.The attributes
italic
,strike
,altfont
,blink
are not supported on any Windows version.On Windows, only a single output console is supported.
TODO
Consider a
->parse_terminal
constructor method, which would attempt to parse SGR sequences from a given source string.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
Module Install Instructions
To install String::Tagged::Terminal, copy and paste the appropriate command in to your terminal.
cpanm String::Tagged::Terminal
perl -MCPAN -e shell install String::Tagged::Terminal
For more information on module installation, please visit the detailed CPAN module installation guide.