report(3tcl)

📦

version 2.0 · 2 versions

2.0 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.21 · debian bookworm, ubuntu jammy, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

So this is report(3tcl), bestie — from the Matrix reports section of the Tcl manual. And what does it do? It creates and manipulates report objects. That's it, that's the name. 🎀

🌸 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 💅

Okay so picture this: this package hands you report objects, and those little guys are what the formatting methods of matrix objects use to spit out tabular reports of the matrix in various forms. Iconic. The report objects defined here chop every single report into three REGIONS and ten classes of lines (a whole buffet of separator-lines and data-lines, no cap). The next section explains it in more detail, so don't skip it. 👀

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

Creates a brand new report object for a report that has columns columns, and it comes with an associated global Tcl command whose name is reportName. That command is your handle for all the various configuration operations on the report, and it has this general form:

reportName option ?arg arg ...?

option plus the args decide the exact behavior of the command. For more explanations, go read REPORT METHODS. And if you don't specify a style, the report will use the builtin style plain as its default configuration. Simple as that, periodt. ✨

`::report::defstyle styleName arguments script`

Defines the new style styleName. The STYLES section has the full tea. 💖

`::report::rmstyle styleName`

Deletes the style styleName. Now listen — trying to delete an unknown or builtin style will result in an error. And beware, bestie: this command will not check that there are no other styles depending on the deleted one. Deleting a style which is still used by another style FOO will result in a runtime error when FOO is applied to a newly instantiated report. She does not warn you, she just lets it blow up. 💀

`::report::stylearguments styleName`

This introspection command returns the list of arguments associated with the style styleName. Very nosy of you, love it. 🦋

`::report::stylebody styleName`

This introspection command returns the script associated with the style styleName. 👑

`::report::styles`

This introspection command returns a list containing the names of all styles known to the package at the time of the call. And the order of the names in the list reflects the order in which the styles were created — in other words, the first item is the predefined style plain, followed by the first style defined by the user, and so on. Chronological, as she should be. 🎀

🌈 REGIONS 🌈

The three regions are the top caption, the data area and the bottom caption. Roughly speaking: the title, the values to report, and a title at the bottom. Yes, a title at the bottom, she's got main character energy at both ends. 👑

The size of the caption regions can be specified by the user as the number of rows they occupy in the matrix to format. The size of the data area, though? That's specified implicitly. Mystery. Vibe. 🫶

🔥 LINES 🔥

TEMPLATES are associated with each of the ten line classes, and each template defines the formatting for that kind of line. The user is able to enable and disable the separator lines at will — but not the data lines. Their usage is solely determined by the number of rows contained in the three regions. And here's the rule: data lines and all enabled separators must have a template associated with them. No template, no line, no exceptions.

Also note, and this one sneaks up on people: 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. One row can be several lines. Do with that information what you will. 😭

Here are the different kinds of lines, plus the codes that the report methods use to address them:

top — the topmost line of a report. Separates the report from anything which came before it. The user can enable the usage of this line at will.
topdatasep — this line separates the data rows in the top caption region, if it contains more than one row and the user enabled its usage.
topcapsep — this line separates the top caption and data regions, if the top caption is not empty and the user enabled its usage.
datasep — this line separates the data rows in the data region, if it contains more than one row and the user enabled its usage.
botcapsep — this line separates the data and bottom caption regions, if the bottom caption is not empty and the user enabled its usage.
botdatasep — this line separates 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 which comes after it. The user can enable the usage of this line at will.
topdata — this line defines the format of data lines in the top caption region of the report.
data — this line defines the format of data lines in the data region of the report.
botdata — this line 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 is associated with. And the math matters here, so pay attention:

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. Teamwork, honestly. 💖

Note that the corresponding items in all defined templates have to be of equal length. This will be checked by the report object, so don't try it. She will catch you.

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, the items in a separator template having 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.

And the items in a separator template having 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 are replicated to be at least as long as the size of their column and then cut to the exact size. Stretch, then snip. ✂️✨

🦋 STYLES 🦋

Styles are a way for the user of this package to define common configurations for report objects and then use them later, during the actual instantiation of report objects. They are defined as tcl scripts which, when executed, configure the report object into the requested configuration. A whole preset. A fit. An aesthetic. 💅

The command to define styles is ::report::defstyle. Its last argument is the tcl script performing the actual reconfiguration of the report object to obtain the requested style.

In this 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. The latter implicitly operate on the object currently executing the style script. The arguments declared here are available in the script as variables. And when calling the command of a previously declared style, all the arguments expected by it have to be defined in the call. No skipping arguments, bestie. 🎀

okay that's part one of this whole situation — there is more coming, so don't go anywhere 🫶

REPORT METHODS 🛠️✨

okay bestie, these are all the commands you can throw at a report object. periodt.

`reportName destroy`

yeets the entire report into the void — its storage space and its associated command go bye-bye too. no takebacks, no notes. 💀

`reportName templatecode disable|enable`

Turns the template pointed at by templatecode on or off. Only the codes for separator lines are allowed here, bestie. You literally cannot enable or disable data lines. When you enable a template, the report goes full detective mode and checks all used templates for inconsistencies in the definition of the vertical lines (peep the TEMPLATES section, iykyk).

`reportName templatecode enabled`

Returns whether the template addressed by templatecode is currently enabled or not. yes/no energy, slay.

`reportName templatecode get`

Returns the template currently associated with the kind of line addressed by templatecode. Every known templatecode is 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. Length constraints on templates? Check TEMPLATES, boo. 📏

`reportName tcaption ?size?`

Specifies the size of the top caption region as the number of rows it occupies in the matrix to be formatted. Only numbers greater than or equal to zero are allowed. If no size is specified, the command returns the current size instead.

Setting the size of the top caption to a value greater than zero enables the corresponding data template and causes the report to check all used templates for inconsistencies in the definition of the vertical lines (see TEMPLATES). consistency check era.

`reportName bcaption size`

Specifies the size of the bottom caption region as the number of rows it occupies in the matrix to be formatted. Only numbers greater than or equal to zero are allowed. If no size is specified, the command returns the current size instead.

Setting the size of the bottom caption to a value greater than zero enables the corresponding data template and causes the report to check all used templates for inconsistencies in the definition of the vertical lines (see TEMPLATES). same vibe, bottom edition.

`reportName size column ?number|dyn?`

Specifies the size of the column in the output. The value dyn means that the columnwidth returned by the matrix to be formatted for the specified column shall be used — the formatting of the column is dynamic. If a fixed number is used instead of dyn, it means the column has a width of that many characters (padding excluded). Only numbers greater than zero are allowed here.

If no size specification is given, the command returns the current size of the column instead. no guessing, just ask.

`reportName sizes ?size-list?`

This method lets you set the sizes of all columns in one call. Its argument is a list containing the sizes to associate with the columns. The first item goes with column 0, the next with column 1, and so on.

If no size-list is specified, the command returns a list containing the currently set sizes instead. bulk update, we love efficiency.

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

This method lets you specify padding on the left, right, or both sides of a column. If padstring is not specified, it defaults to a single space character. Note: an alternative way of specifying the padding is to use vertical separator strings longer than one character in the templates (see TEMPLATES). iykyk.

If no pad specification is given at all, the command returns the current state of padding for the column instead. This will be a list containing two elements: the first element is the left padding, the second describes the right padding. receipts.

`reportName justify column ?left|right|center?`

Declares how the cell values for a column are filled into the report given the specified size of a column in the report.

For left and right justification, a cell value shorter than the width of the column is bound with its named edge to the same edge of the column. The other side is filled with spaces. In the case of center, the spaces are placed to both sides of the value, and the left number of spaces is at most one higher than the right number of spaces. math but make it fashion.

For a value longer than the width of the column, the value is cut at the named edge. This means for left justification that the tail (i.e. the right part) of the value is made visible in the output. For center, the value is cut at both sides to fit into the column, and the number of characters cut at the left side of the value is at most one less than the number of characters cut from the right side. snip snip ✂️.

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

`reportName printmatrix matrix`

Formats the 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. 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. main character formatting moment.

`reportName printmatrix2channel matrix chan`

Formats the matrix according to the configuration of the report and writes the result into the channel chan. The matrix has to have the same number of columns as the report. 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. straight to the channel, no detours.

`reportName columns`

Returns the number of columns in the report. simple, iconic, done.

heads up bestie: the methods size, pad, and justify all take a column index as their first argument. This 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". don't test the limits unless you mean it.

EXAMPLES 🌈✨

Our examples define some generally useful report styles. slay.

A simple table 🎀

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
                  }

Captioned table 🦋

An extension of a simpletable, see above, with a title area.

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

Actually formatting a matrix 💅

Given the definitions above, now an example which actually formats a matrix into a tabular report. It assumes that 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

BUGS, IDEAS, FEEDBACK 🐛💡

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category report of the Tcllib Trackers http://core.tcl.tk/tcllib/reportlist. Please also report any ideas for enhancements you may have for either the package and/or documentation. we're all ears.

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

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. no drive-by pastes, bestie.

KEYWORDS 🔑

matrix, report, table

CATEGORY 🗂️

Data structures

COPYRIGHT 📝

that's the tea from tcllib, version 0.5, report(3tcl) — date? not in the footer but we're timeless 💅 bye bestie! 💖

📦 where this page comes from

debian trixie: tcllib 2.0+dfsg-4 · Tcl
ubuntu questing: tcllib 2.0+dfsg-4
ubuntu resolute: tcllib 2.0+dfsg-5 · Tcl
ubuntu stonking: tcllib 2.0+dfsg-6 · Tcl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms