[comment {--- punk::docgen generated from inline doctools comments ---}]
[comment {--- punk::docgen DO NOT EDIT DOCS HERE UNLESS YOU REMOVE THESE COMMENT LINES ---}]
[comment {--- punk::docgen overwrites this file ---}]
[manpage_begin punkshell_module_textblock 0 0.1.3]
[copyright "2024"]
[titledesc {punk textblock functions}]  [comment {-- Name section and table of contents description --}]
[moddesc {punk textblock}]             [comment {-- Description at end of page heading --}]
[require textblock]
[keywords module ansi text layout colour table frame console terminal]
[description]
[para] Ansi-aware terminal textblock manipulation
[section Overview]
[para] overview of textblock
[subsection Concepts]
[para]
[subsection dependencies]
[para] packages used by textblock
[list_begin itemized]
[item] [package {Tcl 8.6-}]
[item] [package {punk::args}]
[item] [package {punk::char}]
[item] [package {punk::ansi}]
[item] [package {punk::lib}]
[item] [package {overtype}]
[item] [package {term::ansi::code::macros}]
[item] [package {textutil}]
[list_end]
[section API]
[subsection {Namespace textblock::class}]
[para] class definitions
[list_begin itemized] [comment {- textblock::class groupings -}]
  [item]
  [para] [emph {handler_classes}]
  [list_begin enumerated]
[enum] CLASS [class textblock::class::table]
[list_begin definitions]
[para] Create a table suitable for terminal output with various border styles.
[para] The table can contain multiline cells and ANSI colour and text style attributes.
[para] Multiple header rows can be configured.
[para] Header rows can span columns - data rows cannot.
[para] The restriction on data rows is to maintain compatibility of the data with a Tcl matrix command
[para] (see get_matrix command)
[para] Both header and data cells can have various text and blockalignments configured.
    [para] [emph METHODS]
[call class::table [method constructor] [arg args]]
[para] TODO - document the many options
[call class::table [method configure] [arg args]]
[para] get or set various table-level properties
[call class::table [method printmatrix] [arg matrix]]
[para] clear all table rows and print a matrix into the table
[para] The rowxcolumn structure must match
[call class::table [method as_matrix] [arg ?cmd?]]
[para] return a struct::matrix command representing the data portion of the table.
[call class::table [method add_column] [arg args]]
[call class::table [method column_count]]
[para] return the number of columns
[call class::table [method configure_column] [arg index_expression] [arg args]]
[para] - undocumented
[call class::table [method header_count]]
[para] return the number of header rows
[call class::table [method header_height] [arg header_index]]
[para] return the height of a header as the number of content-lines
[call class::table [method header_colspans]]
[para] Show the colspans configured for all headers
[call class::table [method configure_header]]
[para] - configure header row-wise
[call class::table [method add_row]\
  [arg valuelist]\
  [opt "[option -minheight] [arg int_minheight]"]\
  [opt "[option -maxheight] [arg int_maxheight]"]\
  [opt "[option -ansibase] [arg ansicode]"]\
]
[call class::table [method configure_row]\
  [arg index_expression]\
  [opt "[option -minheight] [arg int_minheight]"]\
  [opt "[option -maxheight] [arg int_maxheight]"]\
  [opt "[option -ansibase] [arg ansicode]"]\
]
[call class::table [method row_count]]
[para] return the number of data rows in the table.
[call class::table [method row_clear]]
[para] Remove all rows without resetting column data.
[para] When adding new rows the number of entries will need to match the existing column count.
[call class::table [method clear]]
[para] Remove all row and column data.
[para] If a subsequent call to add_row is made it can contain any number of values.
[para] Further calls to add_row will need to contain the same number of values
[para] as the first call unless default values have been set for the missing columns (review - in flux).
[call class::table [method get_column_cells_by_index] [arg index_expression]]
[para] Return a dict with keys 'headers' and 'cells' giving column header and data values
[call class::table [method get_column_values_by_index] [arg index_expression]]
[para] List the cell values of a column from the data area only (no header values)
[call class::table [method debug]]
[para] display lots of debug information about how the table is constructed.
[call class::table [method column_width] [arg index_expression]]
[para] inner width of column ie the available cell-width without borders/separators
[call class::table [method column_width]]
[para] ordered list of column widths (inner widths)
[call class::table [method width]]
[para] width of the table including borders and separators
[para] calculate width based on assumption frame verticals are 1 screen-column wide
[para] (review - consider possibility of custom unicode double-wide frame?)
[call class::table [method spangroups]]
[para] return a dict keyed by column-index showing advanced span information
[para] (debug tool)
[call class::table [method print]]
[para] Return the table as text suitable for console display
[call class::table [method print_bodymatrix]]
[para] output the matrix string corresponding to the body data using the matrix 2string format
[para] this will be a table without borders,headers,title etc and will exclude additional ANSI applied due to table, row or column settings.
[para] If the original cell data itself contains ANSI - the output will still contain those ansi codes.

[list_end]
  [list_end] [comment {- end enumeration provider_classes }]
[list_end] [comment {- end itemized list textblock::class groupings -}]
[manpage_end]