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.
508 lines
12 KiB
508 lines
12 KiB
'\" |
|
'\" Generated from file '_module_textblock-0\&.1\&.3\&.tm\&.man' by tcllib/doctools with format 'nroff' |
|
'\" Copyright (c) 2024 |
|
'\" |
|
.TH "punkshell_module_textblock" 0 0\&.1\&.3 doc "punk textblock" |
|
.\" 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_textblock \- punk textblock functions |
|
.SH SYNOPSIS |
|
package require \fBtextblock\fR |
|
.sp |
|
class::table \fBconstructor\fR \fIargs\fR |
|
.sp |
|
class::table \fBconfigure\fR \fIargs\fR |
|
.sp |
|
class::table \fBprintmatrix\fR \fImatrix\fR |
|
.sp |
|
class::table \fBas_matrix\fR \fI?cmd?\fR |
|
.sp |
|
class::table \fBadd_column\fR \fIargs\fR |
|
.sp |
|
class::table \fBcolumn_count\fR |
|
.sp |
|
class::table \fBconfigure_column\fR \fIindex_expression\fR \fIargs\fR |
|
.sp |
|
class::table \fBheader_count\fR |
|
.sp |
|
class::table \fBheader_height\fR \fIheader_index\fR |
|
.sp |
|
class::table \fBheader_colspans\fR |
|
.sp |
|
class::table \fBconfigure_header\fR |
|
.sp |
|
class::table \fBadd_row\fR \fIvaluelist\fR ?\fB-minheight\fR \fIint_minheight\fR? ?\fB-maxheight\fR \fIint_maxheight\fR? ?\fB-ansibase\fR \fIansicode\fR? |
|
.sp |
|
class::table \fBconfigure_row\fR \fIindex_expression\fR ?\fB-minheight\fR \fIint_minheight\fR? ?\fB-maxheight\fR \fIint_maxheight\fR? ?\fB-ansibase\fR \fIansicode\fR? |
|
.sp |
|
class::table \fBrow_count\fR |
|
.sp |
|
class::table \fBrow_clear\fR |
|
.sp |
|
class::table \fBclear\fR |
|
.sp |
|
class::table \fBget_column_cells_by_index\fR \fIindex_expression\fR |
|
.sp |
|
class::table \fBget_column_values_by_index\fR \fIindex_expression\fR |
|
.sp |
|
class::table \fBdebug\fR |
|
.sp |
|
class::table \fBcolumn_width\fR \fIindex_expression\fR |
|
.sp |
|
class::table \fBcolumn_width\fR |
|
.sp |
|
class::table \fBwidth\fR |
|
.sp |
|
class::table \fBspangroups\fR |
|
.sp |
|
class::table \fBprint\fR |
|
.sp |
|
class::table \fBprint_bodymatrix\fR |
|
.sp |
|
.BE |
|
.SH DESCRIPTION |
|
.PP |
|
Ansi-aware terminal textblock manipulation |
|
.SH OVERVIEW |
|
.PP |
|
overview of textblock |
|
.SS CONCEPTS |
|
.PP |
|
.SS DEPENDENCIES |
|
.PP |
|
packages used by textblock |
|
.IP \(bu |
|
\fBTcl 8\&.6-\fR |
|
.IP \(bu |
|
\fBpunk::args\fR |
|
.IP \(bu |
|
\fBpunk::char\fR |
|
.IP \(bu |
|
\fBpunk::ansi\fR |
|
.IP \(bu |
|
\fBpunk::lib\fR |
|
.IP \(bu |
|
\fBovertype\fR |
|
.IP \(bu |
|
\fBterm::ansi::code::macros\fR |
|
.IP \(bu |
|
\fBtextutil\fR |
|
.PP |
|
.SH API |
|
.SS "NAMESPACE TEXTBLOCK::CLASS" |
|
.PP |
|
class definitions |
|
.IP \(bu |
|
.sp |
|
\fIhandler_classes\fR |
|
.RS |
|
.IP [1] |
|
CLASS \fBtextblock::class::table\fR |
|
.RS |
|
.sp |
|
Create a table suitable for terminal output with various border styles\&. |
|
.sp |
|
The table can contain multiline cells and ANSI colour and text style attributes\&. |
|
.sp |
|
Multiple header rows can be configured\&. |
|
.sp |
|
Header rows can span columns - data rows cannot\&. |
|
.sp |
|
The restriction on data rows is to maintain compatibility of the data with a Tcl matrix command |
|
.sp |
|
(see get_matrix command) |
|
.sp |
|
Both header and data cells can have various text and blockalignments configured\&. |
|
.sp |
|
\fIMETHODS\fR |
|
.TP |
|
class::table \fBconstructor\fR \fIargs\fR |
|
.sp |
|
TODO - document the many options |
|
.TP |
|
class::table \fBconfigure\fR \fIargs\fR |
|
.sp |
|
get or set various table-level properties |
|
.TP |
|
class::table \fBprintmatrix\fR \fImatrix\fR |
|
.sp |
|
clear all table rows and print a matrix into the table |
|
.sp |
|
The rowxcolumn structure must match |
|
.TP |
|
class::table \fBas_matrix\fR \fI?cmd?\fR |
|
.sp |
|
return a struct::matrix command representing the data portion of the table\&. |
|
.TP |
|
class::table \fBadd_column\fR \fIargs\fR |
|
.TP |
|
class::table \fBcolumn_count\fR |
|
.sp |
|
return the number of columns |
|
.TP |
|
class::table \fBconfigure_column\fR \fIindex_expression\fR \fIargs\fR |
|
.sp |
|
- undocumented |
|
.TP |
|
class::table \fBheader_count\fR |
|
.sp |
|
return the number of header rows |
|
.TP |
|
class::table \fBheader_height\fR \fIheader_index\fR |
|
.sp |
|
return the height of a header as the number of content-lines |
|
.TP |
|
class::table \fBheader_colspans\fR |
|
.sp |
|
Show the colspans configured for all headers |
|
.TP |
|
class::table \fBconfigure_header\fR |
|
.sp |
|
- configure header row-wise |
|
.TP |
|
class::table \fBadd_row\fR \fIvaluelist\fR ?\fB-minheight\fR \fIint_minheight\fR? ?\fB-maxheight\fR \fIint_maxheight\fR? ?\fB-ansibase\fR \fIansicode\fR? |
|
.TP |
|
class::table \fBconfigure_row\fR \fIindex_expression\fR ?\fB-minheight\fR \fIint_minheight\fR? ?\fB-maxheight\fR \fIint_maxheight\fR? ?\fB-ansibase\fR \fIansicode\fR? |
|
.TP |
|
class::table \fBrow_count\fR |
|
.sp |
|
return the number of data rows in the table\&. |
|
.TP |
|
class::table \fBrow_clear\fR |
|
.sp |
|
Remove all rows without resetting column data\&. |
|
.sp |
|
When adding new rows the number of entries will need to match the existing column count\&. |
|
.TP |
|
class::table \fBclear\fR |
|
.sp |
|
Remove all row and column data\&. |
|
.sp |
|
If a subsequent call to add_row is made it can contain any number of values\&. |
|
.sp |
|
Further calls to add_row will need to contain the same number of values |
|
.sp |
|
as the first call unless default values have been set for the missing columns (review - in flux)\&. |
|
.TP |
|
class::table \fBget_column_cells_by_index\fR \fIindex_expression\fR |
|
.sp |
|
Return a dict with keys 'headers' and 'cells' giving column header and data values |
|
.TP |
|
class::table \fBget_column_values_by_index\fR \fIindex_expression\fR |
|
.sp |
|
List the cell values of a column from the data area only (no header values) |
|
.TP |
|
class::table \fBdebug\fR |
|
.sp |
|
display lots of debug information about how the table is constructed\&. |
|
.TP |
|
class::table \fBcolumn_width\fR \fIindex_expression\fR |
|
.sp |
|
inner width of column ie the available cell-width without borders/separators |
|
.TP |
|
class::table \fBcolumn_width\fR |
|
.sp |
|
ordered list of column widths (inner widths) |
|
.TP |
|
class::table \fBwidth\fR |
|
.sp |
|
width of the table including borders and separators |
|
.sp |
|
calculate width based on assumption frame verticals are 1 screen-column wide |
|
.sp |
|
(review - consider possibility of custom unicode double-wide frame?) |
|
.TP |
|
class::table \fBspangroups\fR |
|
.sp |
|
return a dict keyed by column-index showing advanced span information |
|
.sp |
|
(debug tool) |
|
.TP |
|
class::table \fBprint\fR |
|
.sp |
|
Return the table as text suitable for console display |
|
.TP |
|
class::table \fBprint_bodymatrix\fR |
|
.sp |
|
output the matrix string corresponding to the body data using the matrix 2string format |
|
.sp |
|
this will be a table without borders,headers,title etc and will exclude additional ANSI applied due to table, row or column settings\&. |
|
.sp |
|
If the original cell data itself contains ANSI - the output will still contain those ansi codes\&. |
|
.RE |
|
.RE |
|
.PP |
|
.SH KEYWORDS |
|
ansi, colour, console, frame, layout, module, table, terminal, text |
|
.SH COPYRIGHT |
|
.nf |
|
Copyright (c) 2024 |
|
|
|
.fi
|
|
|