1NAME 2 3 String::Tagged::Terminal - format terminal output using String::Tagged 4 5SYNOPSIS 6 7 use String::Tagged::Terminal; 8 9 my $st = String::Tagged::Terminal->new 10 ->append( "Hello my name is " ) 11 ->append_tagged( $name, bold => 1, fgindex => 4 ); 12 13 $st->say_to_terminal; 14 15DESCRIPTION 16 17 This subclass of String::Tagged provides a method, build_terminal, for 18 outputting the formatting tags embedded in the string as terminal 19 escape sequences, to render the the output in the appropriate style. 20 21TAGS 22 23 The following tag names are recognised: 24 25 bold, under, italic, strike, blink, reverse 26 27 These tags take a boolean value. If the value is true then the 28 corresponding terminal rendering attribute is enabled. 29 30 altfont 31 32 This tag takes an integer value. If defined it uses the "alternate font 33 selection" sequence. 34 35 fgindex, bgindex 36 37 These tags take an integer value in the range 0 to 255. These select 38 the foreground or background colour by using VGA, high-brightness 39 extended 16 colour, or xterm 256 palette mode attributes, depending on 40 the value. 41 42 The ECMA-48-corrected string encoding form of CSI 38:5:nnn m is used to 43 set the 256 palette values. 44 45 Values will be rounded down to the nearest integer by calling int(). 46 This convenience allows things like the rand function for generating 47 random colours: 48 49 $st->append_tagged( "text", fgindex => 1 + rand 6 ); 50 51CONSTRUCTORS 52 53 new_from_formatting 54 55 $st = String::Tagged::Terminal->new_from_formatting( $fmt ) 56 57 Returns a new instance by converting String::Tagged::Formatting 58 standard tags. 59 60 Foreground and background colours are converted to their nearest index 61 in the xterm 256 colour palette. The monospace Formatting attribute is 62 rendered by selecting the first alternate font using altfont. 63 64METHODS 65 66 The following methods are provided in addition to those provided by 67 String::Tagged. 68 69 build_terminal 70 71 $str = $st->build_terminal( %opts ) 72 73 Returns a string containing terminal escape sequences mixed with string 74 content to render the string to a terminal. 75 76 As this string will contain literal terminal control escape sequences, 77 care should be taken when passing it around, printing it for debugging 78 purposes, or similar. 79 80 Takes the following additional named options: 81 82 no_color 83 84 If true, the fgindex and bgindex attributes will be ignored. This has 85 the result of performing some formatting using the other attributes, 86 but not setting colours. 87 88 as_formatting 89 90 $fmt = $st->as_formatting 91 92 Returns a new String::Tagged instance tagged with 93 String::Tagged::Formatting standard tags. 94 95 print_to_terminal 96 97 $str->print_to_terminal( $fh ) 98 99 Since version 0.03. 100 101 Prints the string to the terminal by building a terminal escape string 102 then printing it to the given IO handle (or STDOUT if not supplied). 103 104 This method will pass the value of the NO_COLOR environment variable to 105 the underlying "build_terminal" method call, meaning if that has a true 106 value then colouring tags will be ignored, yielding a monochrome 107 output. This follows the suggestion of http://no-color.org/. 108 109 say_to_terminal 110 111 $str->say_to_terminal( $fh ) 112 113 Since version 0.03. 114 115 Prints the string to the terminal as per "print_to_terminal", followed 116 by a linefeed. 117 118COMPATIBILITY NOTES 119 120 On Windows, the following notes apply: 121 122 * On all versions of Windows, the attributes bold, fgindex and 123 bgindex are supported. The bold attribute is implemented by using 124 high-intensity colours, so will be indistinguishable from using 125 high-intensity colour indexes without bold. The full 256-color 126 palette is not supported by Windows, so it is down-converted to the 127 16 colours that are. 128 129 * Starting with Windows 10, also under and reverse are supported. 130 131 * The attributes italic, strike, altfont, blink are not supported on 132 any Windows version. 133 134 * On Windows, only a single output console is supported. 135 136TODO 137 138 * Consider a ->parse_terminal constructor method, which would attempt 139 to parse SGR sequences from a given source string. 140 141AUTHOR 142 143 Paul Evans <leonerd@leonerd.org.uk> 144 145