You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
560 lines
14 KiB
560 lines
14 KiB
'\" |
|
'\" Generated from file '_module_ansi-0\&.1\&.0\&.tm\&.man' by tcllib/doctools with format 'nroff' |
|
'\" Copyright (c) 2023 |
|
'\" |
|
.TH "punkshell_module_punk::ansi" 0 0\&.1\&.0 doc "punk Ansi library" |
|
.\" The -*- nroff -*- definitions below are for supplemental macros used |
|
.\" in Tcl/Tk manual entries. |
|
.\" |
|
.\" .AP type name in/out ?indent? |
|
.\" Start paragraph describing an argument to a library procedure. |
|
.\" type is type of argument (int, etc.), in/out is either "in", "out", |
|
.\" or "in/out" to describe whether procedure reads or modifies arg, |
|
.\" and indent is equivalent to second arg of .IP (shouldn't ever be |
|
.\" needed; use .AS below instead) |
|
.\" |
|
.\" .AS ?type? ?name? |
|
.\" Give maximum sizes of arguments for setting tab stops. Type and |
|
.\" name are examples of largest possible arguments that will be passed |
|
.\" to .AP later. If args are omitted, default tab stops are used. |
|
.\" |
|
.\" .BS |
|
.\" Start box enclosure. From here until next .BE, everything will be |
|
.\" enclosed in one large box. |
|
.\" |
|
.\" .BE |
|
.\" End of box enclosure. |
|
.\" |
|
.\" .CS |
|
.\" Begin code excerpt. |
|
.\" |
|
.\" .CE |
|
.\" End code excerpt. |
|
.\" |
|
.\" .VS ?version? ?br? |
|
.\" Begin vertical sidebar, for use in marking newly-changed parts |
|
.\" of man pages. The first argument is ignored and used for recording |
|
.\" the version when the .VS was added, so that the sidebars can be |
|
.\" found and removed when they reach a certain age. If another argument |
|
.\" is present, then a line break is forced before starting the sidebar. |
|
.\" |
|
.\" .VE |
|
.\" End of vertical sidebar. |
|
.\" |
|
.\" .DS |
|
.\" Begin an indented unfilled display. |
|
.\" |
|
.\" .DE |
|
.\" End of indented unfilled display. |
|
.\" |
|
.\" .SO ?manpage? |
|
.\" Start of list of standard options for a Tk widget. The manpage |
|
.\" argument defines where to look up the standard options; if |
|
.\" omitted, defaults to "options". The options follow on successive |
|
.\" lines, in three columns separated by tabs. |
|
.\" |
|
.\" .SE |
|
.\" End of list of standard options for a Tk widget. |
|
.\" |
|
.\" .OP cmdName dbName dbClass |
|
.\" Start of description of a specific option. cmdName gives the |
|
.\" option's name as specified in the class command, dbName gives |
|
.\" the option's name in the option database, and dbClass gives |
|
.\" the option's class in the option database. |
|
.\" |
|
.\" .UL arg1 arg2 |
|
.\" Print arg1 underlined, then print arg2 normally. |
|
.\" |
|
.\" .QW arg1 ?arg2? |
|
.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation). |
|
.\" |
|
.\" .PQ arg1 ?arg2? |
|
.\" Print an open parenthesis, arg1 in quotes, then arg2 normally |
|
.\" (for trailing punctuation) and then a closing parenthesis. |
|
.\" |
|
.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
|
.if t .wh -1.3i ^B |
|
.nr ^l \n(.l |
|
.ad b |
|
.\" # Start an argument description |
|
.de AP |
|
.ie !"\\$4"" .TP \\$4 |
|
.el \{\ |
|
. ie !"\\$2"" .TP \\n()Cu |
|
. el .TP 15 |
|
.\} |
|
.ta \\n()Au \\n()Bu |
|
.ie !"\\$3"" \{\ |
|
\&\\$1 \\fI\\$2\\fP (\\$3) |
|
.\".b |
|
.\} |
|
.el \{\ |
|
.br |
|
.ie !"\\$2"" \{\ |
|
\&\\$1 \\fI\\$2\\fP |
|
.\} |
|
.el \{\ |
|
\&\\fI\\$1\\fP |
|
.\} |
|
.\} |
|
.. |
|
.\" # define tabbing values for .AP |
|
.de AS |
|
.nr )A 10n |
|
.if !"\\$1"" .nr )A \\w'\\$1'u+3n |
|
.nr )B \\n()Au+15n |
|
.\" |
|
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
|
.nr )C \\n()Bu+\\w'(in/out)'u+2n |
|
.. |
|
.AS Tcl_Interp Tcl_CreateInterp in/out |
|
.\" # BS - start boxed text |
|
.\" # ^y = starting y location |
|
.\" # ^b = 1 |
|
.de BS |
|
.br |
|
.mk ^y |
|
.nr ^b 1u |
|
.if n .nf |
|
.if n .ti 0 |
|
.if n \l'\\n(.lu\(ul' |
|
.if n .fi |
|
.. |
|
.\" # BE - end boxed text (draw box now) |
|
.de BE |
|
.nf |
|
.ti 0 |
|
.mk ^t |
|
.ie n \l'\\n(^lu\(ul' |
|
.el \{\ |
|
.\" Draw four-sided box normally, but don't draw top of |
|
.\" box if the box started on an earlier page. |
|
.ie !\\n(^b-1 \{\ |
|
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
|
.\} |
|
.el \}\ |
|
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
|
.\} |
|
.\} |
|
.fi |
|
.br |
|
.nr ^b 0 |
|
.. |
|
.\" # VS - start vertical sidebar |
|
.\" # ^Y = starting y location |
|
.\" # ^v = 1 (for troff; for nroff this doesn't matter) |
|
.de VS |
|
.if !"\\$2"" .br |
|
.mk ^Y |
|
.ie n 'mc \s12\(br\s0 |
|
.el .nr ^v 1u |
|
.. |
|
.\" # VE - end of vertical sidebar |
|
.de VE |
|
.ie n 'mc |
|
.el \{\ |
|
.ev 2 |
|
.nf |
|
.ti 0 |
|
.mk ^t |
|
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
|
.sp -1 |
|
.fi |
|
.ev |
|
.\} |
|
.nr ^v 0 |
|
.. |
|
.\" # Special macro to handle page bottom: finish off current |
|
.\" # box/sidebar if in box/sidebar mode, then invoked standard |
|
.\" # page bottom macro. |
|
.de ^B |
|
.ev 2 |
|
'ti 0 |
|
'nf |
|
.mk ^t |
|
.if \\n(^b \{\ |
|
.\" Draw three-sided box if this is the box's first page, |
|
.\" draw two sides but no top otherwise. |
|
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
|
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
|
.\} |
|
.if \\n(^v \{\ |
|
.nr ^x \\n(^tu+1v-\\n(^Yu |
|
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
|
.\} |
|
.bp |
|
'fi |
|
.ev |
|
.if \\n(^b \{\ |
|
.mk ^y |
|
.nr ^b 2 |
|
.\} |
|
.if \\n(^v \{\ |
|
.mk ^Y |
|
.\} |
|
.. |
|
.\" # DS - begin display |
|
.de DS |
|
.RS |
|
.nf |
|
.sp |
|
.. |
|
.\" # DE - end display |
|
.de DE |
|
.fi |
|
.RE |
|
.sp |
|
.. |
|
.\" # SO - start of list of standard options |
|
.de SO |
|
'ie '\\$1'' .ds So \\fBoptions\\fR |
|
'el .ds So \\fB\\$1\\fR |
|
.SH "STANDARD OPTIONS" |
|
.LP |
|
.nf |
|
.ta 5.5c 11c |
|
.ft B |
|
.. |
|
.\" # SE - end of list of standard options |
|
.de SE |
|
.fi |
|
.ft R |
|
.LP |
|
See the \\*(So manual entry for details on the standard options. |
|
.. |
|
.\" # OP - start of full description for a single option |
|
.de OP |
|
.LP |
|
.nf |
|
.ta 4c |
|
Command-Line Name: \\fB\\$1\\fR |
|
Database Name: \\fB\\$2\\fR |
|
Database Class: \\fB\\$3\\fR |
|
.fi |
|
.IP |
|
.. |
|
.\" # CS - begin code excerpt |
|
.de CS |
|
.RS |
|
.nf |
|
.ta .25i .5i .75i 1i |
|
.. |
|
.\" # CE - end code excerpt |
|
.de CE |
|
.fi |
|
.RE |
|
.. |
|
.\" # UL - underline word |
|
.de UL |
|
\\$1\l'|0\(ul'\\$2 |
|
.. |
|
.\" # QW - apply quotation marks to word |
|
.de QW |
|
.ie '\\*(lq'"' ``\\$1''\\$2 |
|
.\"" fix emacs highlighting |
|
.el \\*(lq\\$1\\*(rq\\$2 |
|
.. |
|
.\" # PQ - apply parens and quotation marks to word |
|
.de PQ |
|
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3 |
|
.\"" fix emacs highlighting |
|
.el (\\*(lq\\$1\\*(rq\\$2)\\$3 |
|
.. |
|
.\" # QR - quoted range |
|
.de QR |
|
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3 |
|
.\"" fix emacs highlighting |
|
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3 |
|
.. |
|
.\" # MT - "empty" string |
|
.de MT |
|
.QW "" |
|
.. |
|
.BS |
|
.SH NAME |
|
punkshell_module_punk::ansi \- Ansi string functions |
|
.SH SYNOPSIS |
|
package require \fBpunk::ansi \fR |
|
.sp |
|
\fBstripansi\fR \fItext\fR |
|
.sp |
|
\fBa?\fR ?ansicode\&.\&.\&.? |
|
.sp |
|
\fBa+\fR ?ansicode\&.\&.\&.? |
|
.sp |
|
\fBa\fR ?ansicode\&.\&.\&.? |
|
.sp |
|
\fBget_code_name\fR \fIcode\fR |
|
.sp |
|
\fBreset\fR |
|
.sp |
|
\fBreset_soft\fR |
|
.sp |
|
\fBreset_colour\fR |
|
.sp |
|
\fBclear\fR |
|
.sp |
|
\fBclear_above\fR |
|
.sp |
|
\fBclear_below\fR |
|
.sp |
|
\fBcursor_on\fR |
|
.sp |
|
\fBcursor_off\fR |
|
.sp |
|
\fBmove\fR \fIrow\fR \fIcol\fR |
|
.sp |
|
\fBmove_emit\fR \fIrow\fR \fIcol\fR \fIdata\fR ?row col data\&.\&.\&.? |
|
.sp |
|
\fBmove_forward\fR \fIn\fR |
|
.sp |
|
\fBmove_back\fR \fIn\fR |
|
.sp |
|
\fBmove_up\fR \fIn\fR |
|
.sp |
|
\fBmove_down\fR \fIn\fR |
|
.sp |
|
\fBerase_line\fR |
|
.sp |
|
\fBerase_sol\fR |
|
.sp |
|
\fBerase_eol\fR |
|
.sp |
|
\fBcursor_pos\fR |
|
.sp |
|
\fBtitleset\fR \fIwindowtitles\fR |
|
.sp |
|
\fBdetect\fR \fItext\fR |
|
.sp |
|
\fBdetect_csi\fR \fItext\fR |
|
.sp |
|
\fBdetect_sgr\fR \fItext\fR |
|
.sp |
|
\fBstrip\fR \fItext\fR |
|
.sp |
|
\fBlength\fR \fItext\fR |
|
.sp |
|
.BE |
|
.SH DESCRIPTION |
|
.PP |
|
Ansi based terminal control string functions |
|
.PP |
|
See \fBpunk::ansi::console\fR for related functions for controlling a console |
|
.SH OVERVIEW |
|
.PP |
|
overview of punk::ansi |
|
.PP |
|
punk::ansi functions return their values - no implicit emission to console/stdout |
|
.SS CONCEPTS |
|
.PP |
|
Ansi codes can be used to control most terminals on most platforms in an 'almost' standard manner |
|
.PP |
|
There are many differences in terminal implementations - but most should support a core set of features |
|
.PP |
|
punk::ansi does not contain any code for direct terminal manipulation via the local system APIs\&. |
|
.PP |
|
Sticking to ansi codes where possible may be better for cross-platform and remote operation where such APIs are unlikely to be useable\&. |
|
.SS DEPENDENCIES |
|
.PP |
|
packages used by punk::ansi |
|
.IP \(bu |
|
\fBTcl 8\&.6\fR |
|
.PP |
|
.SH API |
|
.SS "NAMESPACE PUNK::ANSI" |
|
.PP |
|
Core API functions for punk::ansi |
|
.TP |
|
\fBstripansi\fR \fItext\fR |
|
.sp |
|
Return a string with ansi codes stripped out |
|
.TP |
|
\fBa?\fR ?ansicode\&.\&.\&.? |
|
.sp |
|
Return an ansi string representing a table of codes and a panel showing the colours |
|
.TP |
|
\fBa+\fR ?ansicode\&.\&.\&.? |
|
.sp |
|
Returns the ansi code to apply those from the supplied list - without any reset being performed first |
|
.sp |
|
e\&.g to set foreground red and bold |
|
.sp |
|
punk::ansi::a red bold |
|
.sp |
|
to set background red |
|
.sp |
|
punk::ansi::a Red |
|
.sp |
|
see \fBpunk::ansi::a?\fR to display a list of codes |
|
.TP |
|
\fBa\fR ?ansicode\&.\&.\&.? |
|
.sp |
|
Returns the ansi code to reset any current settings and apply those from the supplied list |
|
.sp |
|
by calling punk::ansi::a with no arguments - the result is a reset to plain text |
|
.sp |
|
e\&.g to set foreground red and bold |
|
.sp |
|
punk::ansi::a red bold |
|
.sp |
|
to set background red |
|
.sp |
|
punk::ansi::a Red |
|
.sp |
|
see \fBpunk::ansi::a?\fR to display a list of codes |
|
.TP |
|
\fBget_code_name\fR \fIcode\fR |
|
.sp |
|
for example |
|
.sp |
|
get_code_name red will return 31 |
|
.sp |
|
get_code_name 31 will return red |
|
.TP |
|
\fBreset\fR |
|
.sp |
|
reset console |
|
.TP |
|
\fBreset_soft\fR |
|
.TP |
|
\fBreset_colour\fR |
|
.sp |
|
reset colour only |
|
.TP |
|
\fBclear\fR |
|
.TP |
|
\fBclear_above\fR |
|
.TP |
|
\fBclear_below\fR |
|
.TP |
|
\fBcursor_on\fR |
|
.TP |
|
\fBcursor_off\fR |
|
.TP |
|
\fBmove\fR \fIrow\fR \fIcol\fR |
|
.sp |
|
Return an ansi sequence to move to row,col |
|
.sp |
|
aka cursor home |
|
.TP |
|
\fBmove_emit\fR \fIrow\fR \fIcol\fR \fIdata\fR ?row col data\&.\&.\&.? |
|
.sp |
|
Return an ansi string representing a move to row col with data appended |
|
.sp |
|
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 |
|
.sp |
|
Compare to punk::console::move_emit which calls this function - but writes it to stdout |
|
.sp |
|
punk::console::move_emit_return will also return the cursor to the original position |
|
.sp |
|
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\&. |
|
.sp |
|
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\&. |
|
.sp |
|
punk::console::move_emit_return does it by emitting that code and starting a loop to read stdin |
|
.sp |
|
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\&. |
|
.sp |
|
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: |
|
.sp |
|
.CS |
|
|
|
punk::ansi::move_emit 10 10 blah {*}[punk::console::get_cursor_pos_list] DONE |
|
.CE |
|
.sp |
|
A 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\&. |
|
.TP |
|
\fBmove_forward\fR \fIn\fR |
|
.TP |
|
\fBmove_back\fR \fIn\fR |
|
.TP |
|
\fBmove_up\fR \fIn\fR |
|
.TP |
|
\fBmove_down\fR \fIn\fR |
|
.TP |
|
\fBerase_line\fR |
|
.TP |
|
\fBerase_sol\fR |
|
.sp |
|
Erase to start of line, leaving cursor position alone\&. |
|
.TP |
|
\fBerase_eol\fR |
|
.TP |
|
\fBcursor_pos\fR |
|
.sp |
|
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 |
|
.sp |
|
The output on screen will look something like ^[[47;3R |
|
.sp |
|
Use punk::console::get_cursor_pos or punk::console::get_cursor_pos_list instead\&. |
|
.sp |
|
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\&. |
|
.sp |
|
The punk::ansi::cursor_pos function is used by punk::console::get_cursor_pos and punk::console::get_cursor_pos_list |
|
.TP |
|
\fBtitleset\fR \fIwindowtitles\fR |
|
.sp |
|
Returns the code to set the title of the terminal window to windowtitle |
|
.sp |
|
This may not work on terminals which have multiple panes/windows |
|
.PP |
|
.SS "NAMESPACE PUNK::ANSI::TA" |
|
.PP |
|
text ansi functions |
|
.PP |
|
based on but not identical to the Perl Text Ansi module: |
|
.PP |
|
https://github\&.com/perlancar/perl-Text-ANSI-Util/blob/master/lib/Text/ANSI/BaseUtil\&.pm |
|
.TP |
|
\fBdetect\fR \fItext\fR |
|
.sp |
|
Return a boolean indicating whether Ansi codes were detected in text |
|
.sp |
|
.TP |
|
\fBdetect_csi\fR \fItext\fR |
|
.sp |
|
Return a boolean indicating whether an Ansi Control Sequence Introducer (CSI) was detected in text |
|
.sp |
|
The csi is often represented in code as \\x1b or \\033 followed by a left bracket [ |
|
.sp |
|
The initial byte or escape is commonly referenced as ESC in Ansi documentation |
|
.sp |
|
There is also a multi-byte escape sequence \\u009b |
|
.sp |
|
This is less commonly used but is also detected here |
|
.sp |
|
(This function is not in perl ta) |
|
.TP |
|
\fBdetect_sgr\fR \fItext\fR |
|
.sp |
|
Return a boolean indicating whether an ansi Select Graphics Rendition code was detected\&. |
|
.sp |
|
This is the set of CSI sequences ending in 'm' |
|
.sp |
|
This is most commonly an Ansi colour code - but also things such as underline and italics |
|
.sp |
|
An SGR with empty or a single zero argument is a reset of the SGR features - this is also detected\&. |
|
.sp |
|
(This function is not in perl ta) |
|
.TP |
|
\fBstrip\fR \fItext\fR |
|
.sp |
|
Return text stripped of Ansi codes |
|
.sp |
|
This is a tailcall to punk::ansi::stripansi |
|
.TP |
|
\fBlength\fR \fItext\fR |
|
.sp |
|
Return the character length after stripping ansi codes - not the printing length |
|
.PP |
|
.SS "NAMESPACE PUNK::ANSI::ANSISTRING" |
|
.PP |
|
punk::ansi::string ensemble |
|
.PP |
|
.SH KEYWORDS |
|
ansi, console, module, string, terminal |
|
.SH COPYRIGHT |
|
.nf |
|
Copyright (c) 2023 |
|
|
|
.fi
|
|
|