---
name: "String::Tagged::Terminal"
section: "3pm"
platform: "linux"
package: "libstring-tagged-terminal-perl"
version: "0.08-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/String::Tagged::Terminal"
---

# String::Tagged::Terminal(3pm)

format terminal output using "String::Tagged"

## 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\>