report(n)

📦

version 2.0 · 2 versions

2.0 · fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
1.21 · alpine 3.24, epel 9, opensuse-leap 16.0

, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

report(n) — Matrix reports 💖

okay bestie, buckle up, this is the report(n) page from Matrix reports and it's a big one, so it's split into 2 parts. This is part 1 🎀

✨ NAME ✨

report — Create and manipulate report objects 🫶

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require report ?0.5?

::report::report reportName columns ?style style arg...?

reportName option ?arg arg ...?

::report::defstyle styleName arguments script

::report::rmstyle styleName

::report::stylearguments styleName

::report::stylebody styleName

::report::styles

reportName destroy

reportName templatecode disable|enable

reportName templatecode enabled

reportName templatecode get

reportName templatecode set templatedata

reportName tcaption ?size?

reportName bcaption size

reportName size column ?number|dyn?

reportName sizes ?size-list?

reportName pad column ?left|right|both ?padstring??

reportName justify column ?left|right|center?

reportName printmatrix matrix

reportName printmatrix2channel matrix chan

reportName columns

💅 DESCRIPTION 💅

so this package hands you report objects, and the formatting methods of matrix objects use them to spit out tabular reports of the matrix in all kinds of forms. no cap.

the report objects defined here break every report down into three REGIONS and ten classes of lines (various separator- and data-lines, iykyk). scroll down a sec for the detailed explanations, they're right there ⬇️

::report::report reportName columns ?style style arg...? — makes you a brand new report object for a report that has columns columns, with an associated global Tcl command whose name is reportName. that command is your main character: use it to invoke all the various configuration operations on the report. its general form is:
- reportName option ?arg arg ...? — option and the args decide the exact behavior of the command. see the REPORT METHODS section for way more detail. and bestie, if you don't specify a style, the report uses the builtin style plain as its default configuration. periodt.
::report::defstyle styleName arguments script — defines the new style styleName. check the STYLES section for the tea.
::report::rmstyle styleName — deletes the style styleName. trying to delete an unknown or builtin style? error, immediately. and ⚠️ beware: this command will not check that no other styles depend on the one you're deleting. deleting a style that's still used by another style FOO gives you a runtime error when FOO gets applied to a newly instantiated report. so like, be careful, that's a jumpscare.
::report::stylearguments styleName — introspection command, returns the list of arguments associated with the style styleName.
::report::stylebody styleName — introspection command, returns the script associated with the style styleName.
::report::styles — introspection command, returns a list with the names of every style the package knows about at the time of the call. the order of the names in the list mirrors the order the styles were created in. in other words: first item is the predefined style plain, then the first style the user defined, and so on. chronological, iconic, obsessed.

🦋 REGIONS 🦋

the three regions are:

the top caption
the data area
the bottom caption

roughly speaking: the title, the values you actually want to report, and a title at the bottom. 💀 simple. the size of the caption regions is yours to specify — as the number of rows they occupy in the matrix to format. the size of the data area is specified implicitly, it just is what it is.

🌈 LINES 🌈

TEMPLATES get associated with each of the ten line classes, defining the formatting for that kind of line. you can enable and disable the separator lines at will — but not the data lines. nope. their usage is solely determined by the number of rows contained in the three regions. and heads up: data lines and all enabled separators must have a template associated with them. non-negotiable.

also note: the data-lines in a report and the rows in the matrix the report was generated from are not in a 1:1 relationship if any row in the matrix has a height greater than one. just so you know. 👑

the different kinds of lines and the codes the report methods use to address them:

top — the topmost line of a report. separates the report from anything that came before it. the user can enable the usage of this line at will.
topdatasep — used to separate the data rows in the top caption region, if it contains more than one row and the user enabled its usage.
topcapsep — used to separate the top caption and data regions, if the top caption is not empty and the user enabled its usage.
datasep — used to separate the data rows in the data region, if it contains more than one row and the user enabled its usage.
botcapsep — used to separate the data and bottom caption regions, if the bottom caption is not empty and the user enabled its usage.
botdatasep — used to separate the data rows in the bottom caption region, if it contains more than one row and the user enabled its usage.
bottom — the bottommost line of a report. separates the report from anything that comes after it. the user can enable the usage of this line at will.
topdata — defines the format of data lines in the top caption region of the report.
data — defines the format of data lines in the data region of the report.
botdata — defines the format of data lines in the bottom caption region of the report.

✨ TEMPLATES ✨

each template is a list of strings used to format the line it's associated with. so for a report containing n columns:

a template for a data line has to contain "n+1" items
a template for a separator line has to contain "2*n+1" items

the items in a data template specify the strings used to separate the column information. together with the corresponding items in the separator templates they form the vertical lines in the report. the way that they just… align. 🧚

note: the corresponding items in all defined templates have to be of equal length. this gets checked by the report object, so no sneaky mismatches.

the first item defines the leftmost vertical line and the last item defines the rightmost vertical line. the item at index k ("1",...,"n-2") separates the information in the columns "k-1" and "k".

now, in a separator template:

items with an even-numbered index ("0","2",...) specify the column separators. the item at index "2*k" ("0","2",...,"2*n") corresponds to the items at index "k" in the data templates.
items with an odd-numbered index ("1","3",...) specify the strings used to form the horizontal lines in the separator lines. the item at index "2*k+1" ("1","3",...,"2*n+1") corresponds to column "k". when generating the horizontal lines, the items get replicated to be at least as long as the size of their column, and then cut to the exact size. slay. ✂️

🎀 STYLES 🎀

styles are the way for you, the user of this package, to define common configurations for report objects and then reuse them later during the actual instantiation of report objects. they're defined as tcl scripts which, when executed, configure the report object into the requested configuration. it's giving reusable outfit, honestly.

the command to define styles is ::report::defstyle. its last argument is the tcl script that performs the actual reconfiguration of the report object to obtain the requested style.

inside that script, the names of all previously defined styles are available as commands — as are all commands found in a safe interpreter, and the configuration methods of report objects. those configuration methods implicitly operate on the object currently executing the style script. and the arguments declared here are available in the script as variables. when you call the command of a previously declared style, all the arguments it expects have to be defined in the call. no skipping, bestie. 💖

part 2 coming right up, don't go anywhere 🦋

🌸 REPORT METHODS 🌸

okay bestie, these are all the commands you can throw at a report object. every single one, no skipping 💅

reportName destroy — bye bye report 👋 destroys the report, its storage space, and its associated command. it's giving "we don't know her anymore".
reportName templatecode disable|enable — turns the template addressed by templatecode off or on. heads up tho: only the codes for separator lines are allowed here. you literally cannot enable or disable data lines, so don't even try it 🙈

when you enable a template, the report goes and checks every template in use for inconsistencies in how the vertical lines are defined (peep the TEMPLATES section, iykyk).

reportName templatecode enabled — returns whether the template addressed by templatecode is currently enabled or not. just a lil true/false vibe check ✨
reportName templatecode get — returns the template currently associated with the kind of line addressed by templatecode. all known templatecodes are allowed here, no gatekeeping 🫶
reportName templatecode set templatedata — sets the template associated with the kind of line addressed by templatecode to the new value in templatedata. for constraints on how long templates can be, go read TEMPLATES. periodt.
reportName tcaption ?size? — sets the size of the top caption region, measured as the number of rows it takes up in the matrix that's gonna get formatted. only numbers greater than or equal to zero are allowed, bestie, don't be chaotic. if you don't pass a size, the command returns the current size instead 🎀

setting the top caption size to something greater than zero enables the corresponding data template and makes the report check all used templates for inconsistencies in the vertical line definitions (TEMPLATES section, again, it's important).

reportName bcaption size — same energy but for the bottom caption region 💜 specifies its size as the number of rows it occupies in the matrix to be formatted. only numbers greater than or equal to zero allowed. if no size is specified the command returns the current size instead.

setting the bottom caption to a size greater than zero enables the corresponding data template and, yes, causes the report to check all used templates for inconsistencies in the definition of the vertical lines (TEMPLATES. section. again.).

reportName size column ?number|dyn? — sets the size of column in the output. if you pass dyn, that means the columnwidth returned by the matrix to be formatted for that column shall be used — the formatting is dynamic, it's giving main character energy that adapts 💫 if you pass a fixed number instead of dyn, the column gets a width of that many characters (padding not included, don't get it twisted). only numbers greater than zero are allowed here.

no size specification? the command returns the current size of the column instead. cute.

reportName sizes ?size-list? — this one lets you set the sizes of all the columns in a single call, efficiency queen 👑 its argument is a list containing the sizes to associate with the columns. first item goes to column 0, next to column 1, and so on, forever and ever.

if you don't specify a size-list, the command returns a list containing the currently set sizes instead.

reportName pad column ?left|right|both ?padstring?? — lets you specify padding on the left, right, or both sides of column. if padstring isn't specified it defaults to a single space character. note: an alternative way of specifying padding is to use vertical separator strings longer than one character in the templates (TEMPLATES section, you know the drill 🌸).

if you give no pad specification at all, the command returns the current state of padding for the column instead — a list with two elements, the first being the left padding, the second describing the right padding.

reportName justify column ?left|right|center? — declares how the cell values for a column get filled into the report, given the specified size of that column in the report.

for left and right justification, a cell value shorter than the column width is bound with its named edge to the same edge of the column, and the other side gets filled with spaces. for center, the spaces go on both sides of the value, and the left number of spaces is at most one higher than the right number of spaces. balanced-ish, we love to see it ⚖️

for a value longer than the column width, the value gets cut at the named edge. this means for left justification the tail (i.e. the right part) of the value is what becomes visible in the output. for center, the value is cut at both sides to fit into the column, and the number of characters cut from the left side is at most one less than the number cut from the right side.

if no justification was specified, the command returns the current justification for the column instead.

reportName printmatrix matrix — formats matrix according to the configuration of the report and returns the resulting string. the matrix has to have the same number of columns as the report, no exceptions bestie. the matrix also has to have enough rows so that the top and bottom caption regions do not overlap. the data region is allowed to be empty tho, that's fine, empty is a valid vibe.
reportName printmatrix2channel matrix chan — formats matrix according to the report's configuration and writes the result into the channel chan. same rules apply: the matrix has to have the same number of columns as the report, and enough rows so that the top and bottom caption regions don't overlap. data region can be empty 🦋
reportName columns — returns the number of columns in the report. that's it. that's the whole thing.

quick lil note before you go: the methods size, pad and justify all take a column index as their first argument. that index is allowed to use all the forms of an index as accepted by the lindex command. the allowed range for indices is "0,...,[reportName columns]-1". respect the range, bestie, it's there for a reason 💖

✨ EXAMPLES ✨

our examples define some generally useful report styles. you're welcome, these are lowkey a gift 🎁

a simple table with lines surrounding all information and vertical separators, but without internal horizontal separators:

                  ::report::defstyle simpletable {} {
                data set [split "[string repeat "| "   [columns]]|"]
                top  set [split "[string repeat "+ - " [columns]]+"]
                bottom  set [top get]
                top  enable
                bottom  enable
                  }

an extension of a simpletable, see above, but with a title area:

                  ::report::defstyle captionedtable {{n 1}} {
                simpletable
                topdata   set [data get]
                topcapsep set [top get]
                topcapsep enable
                tcaption $n
                  }

given the definitions above, here's an example that actually formats a matrix into a tabular report. it assumes the matrix actually contains useful data 🙈

                  % ::struct::matrix m
                  % # ... fill m with data, assume 5 columns
                  % ::report::report r 5 style captionedtable 1
                  % r printmatrix m
                  +---+-------------------+-------+-------+--------+
                  |000|VERSIONS:          |2:8.4a3|1:8.4a3|1:8.4a3%|
                  +---+-------------------+-------+-------+--------+
                  |001|CATCH return ok    |7      |13     |53.85   |
                  |002|CATCH return error |68     |91     |74.73   |
                  |003|CATCH no catch used|7      |14     |50.00   |
                  |004|IF if true numeric |12     |33     |36.36   |
                  |005|IF elseif          |15     |47     |31.91   |
                  |   |true numeric       |       |       |        |
                  +---+-------------------+-------+-------+--------+
                  %
                  % # alternate way of doing the above
                  % m format 2string r

look at that alignment. it ate 💅🔥

💀 BUGS, IDEAS, FEEDBACK 💀

ngl this document, and the package it describes, will undoubtedly contain bugs and other problems. it's not a flaw, it's a personality trait. anyway — please report such in the category report of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist. and please also report any ideas for enhancements you may have for either the package and/or the documentation. we want the ideas, we're obsessed with the ideas 🫶

when proposing code changes, please provide unified diffs, i.e. the output of diff -u. no freestyling.

note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. that's the button. left-most. you got this ✨

🌈 KEYWORDS 🌈

matrix, report, table

🎀 CATEGORY 🎀

Data structures

👑 COPYRIGHT 👑

and that's a wrap on report(n), bestie!! 🦋 thank you for coming to my ted talk. this whole thing lives in tcllib, version 0.5, and it's the report(n) page — go format some matrices and slay 💖🌸✨

📦 where this page comes from

fedora 43: tcllib 2.0-3.fc43 · TCL
fedora 44: tcllib 2.0-4.fc44 · TCL
nixos 26.05: tcllib 2.0
nixpkgs unstable: tcllib 2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms