oracular (3) String::Tagged::Terminal.3pm.gz

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>