NAME
SYNOPSIS
DESCRIPTION
TAGS
CONSTRUCTORS
- new_from_formatting
METHODS
COMPATIBILITY NOTES
TODO
AUTHOR

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 );

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.

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 )