Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
String::Tagged::TerminUser)Contributed Perl DocumenString::Tagged::Terminal(3)

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.

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 )

       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:

       o   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.

       o   Starting with Windows 10, also "under" and "reverse"	are supported.

       o   The attributes "italic", "strike", "altfont", "blink" are not
	   supported on	any Windows version.

       o   On Windows, only a single output console is supported.

TODO
       o   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>

perl v5.32.1			  2021-02-28	   String::Tagged::Terminal(3)

NAME | SYNOPSIS | DESCRIPTION | TAGS | CONSTRUCTORS | METHODS | COMPATIBILITY NOTES | TODO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=String::Tagged::Terminal&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help