19 KiB
[ Main Table Of Contents | Table Of Contents | Keyword Index ]
NAME
punkshell_module_punk::ansi - Ansi string functions
Table Of Contents
SYNOPSIS
package require punk::ansi
stripansi text
stripansi text
a? ?ansicode...?
a+ ?ansicode...?
a ?ansicode...?
get_code_name code
reset
reset_soft
reset_colour
clear
clear_above
clear_below
cursor_on
cursor_off
move row col
move_emit row col data ?row col data...?
move_forward n
move_back n
move_up n
move_down n
move_column col
move_row row
cursor_save
cursor_restore
cursor_save_dec
cursor_restore_attributes
enable_line_wrap
disable_line_wrap
query_mode_line_wrap
erase_line
erase_sol
erase_eol
scroll_up n
scroll_down n
insert_spaces count
delete_characters count
erase_characters count
insert_lines count
delete_lines count
cursor_pos
request_cursor_information
request_tabstops
titleset windowtitles
is_sgr_reset code
has_sgr_leadingreset code
detect text
detect_csi text
detect_sgr text
strip text
length text
VIEW string
COUNT string
index string index
DESCRIPTION
Ansi based terminal control string functions
See punk::ansi::console for related functions for controlling a console
Overview
overview of punk::ansi
punk::ansi functions return their values - no implicit emission to console/stdout
Concepts
Ansi codes can be used to control most terminals on most platforms in an 'almost' standard manner
There are many differences in terminal implementations - but most should support a core set of features
punk::ansi does not contain any code for direct terminal manipulation via the local system APIs.
Sticking to ansi codes where possible may be better for cross-platform and remote operation where such APIs are unlikely to be useable.
dependencies
packages used by punk::ansi
-
Tcl 8.6-
-
punk::char
API
Namespace punk::ansi
Core API functions for punk::ansi
-
Return a string with ansi codes stripped out
Alternate graphics chars are replaced with modern unicode equivalents (e.g boxdrawing glyphs)
-
Return a string with ansi codes stripped out
Alternate graphics modes will be stripped - exposing the raw characters as they appear without graphics mode.
ie instead of a horizontal line you may see: qqqqqq e.g who is to know that 'Rabbit Paws', 'Forbidden Thrill' and 'Tarsier' refer to a particular shade of pinky-red? (code 95) Perhaps it's an indication that colour naming once we get to 256 colours or more is a fool's errand anyway. The xterm names are boringly unimaginative - and also have some oddities such as: DarkSlateGray1 which looks much more like cyan.. The greyxx names are spelt with an e - but the darkslategrayX variants use an a. Perhaps that's because they are more cyan than grey and the a is a hint? there is no gold or gold2 - but there is gold1 and gold3 but in general the names bear some resemblance to the colours and are at least somewhat intuitive.
-
Return an ansi string representing a table of codes and a panel showing the colours
-
Returns the ansi code to apply those from the supplied list - without any reset being performed first
e.g to set foreground red and bold
punk::ansi::a red bold
to set background red
punk::ansi::a Red
see punk::ansi::a? to display a list of codes
-
Returns the ansi code to reset any current settings and apply those from the supplied list
by calling punk::ansi::a with no arguments - the result is a reset to plain text
e.g to set foreground red and bold
punk::ansi::a red bold
to set background red
punk::ansi::a Red
see punk::ansi::a? to display a list of codes
-
for example
get_code_name red will return 31
get_code_name 31 will return red
-
reset console
-
reset colour only
-
Return an ansi sequence to move to row,col
aka cursor home
-
move_emit row col data ?row col data...?
Return an ansi string representing a move to row col with data appended
row col data can be repeated any number of times to return a string representing the output of the data elements at all those points
Compare to punk::console::move_emit which calls this function - but writes it to stdout
punk::console::move_emit_return will also return the cursor to the original position
There is no punk::ansi::move_emit_return because in a standard console there is no ansi string which can represent a jump back to starting position.
There is an ansi code to write the current cursor position to stdin (which will generally display on the console) - this is not quite the same thing.
punk::console::move_emit_return does it by emitting that code and starting a loop to read stdin
punk::ansi could implement a move_emit_return using the punk::console mechanism - but the resulting string would capture the cursor position at the time the string is built - which is not necessarily when the string is used.
The following example shows how to do this manually, emitting the string blah at screen position 10,10 and emitting DONE back at the line we started:
punk::ansi::move_emit 10 10 blah {*}[punk::console::get_cursor_pos_list] DONEA string created by any move_emit_return for punk::ansi would not behave in an intuitive manner compared to other punk::ansi move functions - so is deliberately omitted.
-
VPA - Vertical Line Position Absolute
-
equivalent term::ansi::code::ctrl::sc
This is the ANSI/SCO cursor save as opposed to the DECSC version
On many terminals either will work - but cursor_save_dec is shorter and perhaps more widely supported
-
equivalent term::ansi::code::ctrl::rc
ANSI/SCO - see also cursor_restore_dec for the DECRC version
-
equivalent term::ansi::code::ctrl::sca
DECSC
-
equivalent term::ansi::code::ctrl::rca
DECRC
-
enable automatic line wrapping when characters entered beyond rightmost column
This will also allow forward movements to move to subsequent lines
This is DECAWM - and is the same sequence output by 'tput smam'
-
disable automatic line wrapping
reset DECAWM - same sequence output by 'tput rmam' tput rmam
-
DECRQM to query line-wrap state
The punk::ansi::query_mode_ functions just emit the ansi query sequence.
-
Erase to start of line, leaving cursor position alone.
-
cursor_pos unlikely to be useful on it's own like this as when written to the terminal, this sequence causes the terminal to emit the row;col sequence to stdin
The output on screen will look something like ^[[47;3R
Use punk::console::get_cursor_pos or punk::console::get_cursor_pos_list instead.
These functions will emit the code - but read it in from stdin so that it doesn't display, and then return the row and column as a colon-delimited string or list respectively.
The punk::ansi::cursor_pos function is used by punk::console::get_cursor_pos and punk::console::get_cursor_pos_list
-
DECRQPSR (DEC Request Presentation State Report) for DECCCIR Cursor Information report
When written to the terminal, this sequence causes the terminal to emit cursor information to stdin
A stdin readloop will need to be in place to read this information
-
DECRQPSR (DEC Request Presentation State Report) for DECTABSR Tab stop report
When written to the terminal, this sequence causes the terminal to emit tabstop information to stdin
-
Returns the code to set the title of the terminal window to windowtitle
This may not work on terminals which have multiple panes/windows
Namespace punk::ansi::codetype
API functions for punk::ansi::codetype
Utility functions for processing ansi code sequences
-
Return a boolean indicating whether this string has a trailing pure SGR reset
Note that if the reset is not the very last item in the string - it will not be detected.
This is primarily intended for testing a single ansi code sequence, but code can be any string where the trailing SGR code is to be tested.
-
The reset must be the very first item in code to be detected. Trailing strings/codes ignored.
Namespace punk::ansi::ta
text ansi functions
based on but not identical to the Perl Text Ansi module:
https://github.com/perlancar/perl-Text-ANSI-Util/blob/master/lib/Text/ANSI/BaseUtil.pm
-
Return a boolean indicating whether Ansi codes were detected in text
-
Return a boolean indicating whether an Ansi Control Sequence Introducer (CSI) was detected in text
The csi is often represented in code as \x1b or \033 followed by a left bracket [
The initial byte or escape is commonly referenced as ESC in Ansi documentation
There is also a multi-byte escape sequence \u009b
This is less commonly used but is also detected here
(This function is not in perl ta)
-
Return a boolean indicating whether an ansi Select Graphics Rendition code was detected.
This is the set of CSI sequences ending in 'm'
This is most commonly an Ansi colour code - but also things such as underline and italics
An SGR with empty or a single zero argument is a reset of the SGR features - this is also detected.
(This function is not in perl ta)
-
Return text stripped of Ansi codes
This is a tailcall to punk::ansi::stripansi
-
Return the character length after stripping ansi codes - not the printing length
Namespace punk::ansi::ansistring
punk::ansi::ansistring ensemble - ansi-aware string operations
Working with strings containing ansi in a way that preserves/understands the codes is always going to be significantly slower than working with plain strings
Just as working with other forms of markup such as HTML - you simply need to be aware of the tradeoffs and design accordingly.
-
Return a string with specific ANSI control characters substituted with visual equivalents frome the appropriate unicode C0 and C1 visualisation sets
For debugging purposes, certain other standard control characters are converted to visual representation, for example backspace (mapped to \\U2408 '\U2408')
Horizontal tab is mapped to \\U2409 '\U2409'. For many of the punk terminal text operations, tabs have already been mapped to the appropriate number of spaces using textutil::tabify functions
As punkshell uses linefeed where possible in preference to crlf even on windows, cr is mapped to \\U240D '\U240D' - but lf is left as is.
-
Returns the count of visible graphemes and non-ansi control characters
Incomplete! grapheme clustering support not yet implemented - only diacritics are currently clustered to count as one grapheme.
This will not count strings hidden inside a 'privacy message' or other ansi codes which may have content between their opening escape and their termination sequence.
This is not quite equivalent to calling string length on the result of stripansi $string due to diacritics and/or grapheme combinations
Note that this returns the number of characters in the payload (after applying combiners) It is not always the same as the width of the string as rendered on a terminal due to 2wide Unicode characters and the usual invisible control characters such as \r and \n
To get the width, use punk::ansi::printing_length instead, which is also ansi aware.
-
Takes a string that possibly contains ansi codes such as colour,underline etc (SGR codes)
Returns the character (with applied ansi effect) at position index
The string could contain non SGR ansi codes - and these will (mostly) be ignored, so shouldn't affect the output.
Some terminals don't hide 'privacy message' and other strings within an ESC X ESC ^ or ESC _ sequence (terminated by ST)
It's arguable some of these are application specific - but this function takes the view that they are probably non-displaying - so index won't see them.
If the caller wants just the character - they should use a normal string index after calling stripansi, or call stripansi afterwards.
As any operation using end-+ will need to strip ansi to precalculate the length anyway; the caller should probably just use stripansi and standard string index if the ansi coded output isn't required and they are using and end-based index.
In fact, any operation where the ansi info isn't required in the output would probably be slightly more efficiently obtained by using stripansi and normal string operations on that.
The returned character will (possibly) have a leading ansi escape sequence but no trailing escape sequence - even if the string was taken from a position immediately before a reset or other SGR ansi code
The ansi-code prefix in the returned string is built up by concatenating previous SGR ansi codes seen - but it is optimised to re-start the process if any full SGR reset is encountered.
The code sequence doesn't detect individual properties being turned on and then off again, only full resets; so in some cases the ansi-prefix may not be as short as it could be.
This shouldn't make any difference to the visual output - but a possible future enhancement is something to produce the shortest ansi sequence possible
Notes:
This function has to split the whole string into plaintext & ansi codes even for a very low index
Some sort of generator that parses more of the string as required might be more efficient for large chunks.
For end-x operations we have to pre-calculate the content-length by stripping the ansi - which is also potentially sub-optimal
KEYWORDS
ansi, console, module, string, terminal
COPYRIGHT
Copyright © 2023