columnist¶
The columnist library can be used to display textual output in columnar format with text wrapping, alignment, colorization, etc. within each cell.
Status¶
Done¶
Display rows of data in columns.
Dashed external and internal borders or internal whitespace borders.
Wrap text within cells.
Text alignment within cells.
Minimum and maximum cell width.
Display headers and a separator between headers and data rows.
To do¶
Better handling of too-wide cell data for column that doesn’t allow wrapping.
Maximum overall table width.
Column header wrapping.
Get default max width of table from terminal size if possible.
Handle cell data with Newline characters.
Cells that span multiple columns or rows.
Support terminal escape codes for colorizing etc.
Ability to modify how an individual cell or header is displayed, independent of the column description.
Probably lots of other things. See the bug list.
Usage¶
The main entry point is columnize. Just call it with some column definitions and
some row data. By default the output has no external borders and has two-space column
separators.
Example: Simple table¶
columnize(stream,
list(make(<column>),
make(<column>)),
#(#(1, 2), #(3, 4)))
1 2
3 4
Example: Borders and headers¶
columnize(stream,
list(make(<column>, header: "Letters"),
make(<column>, header" "Numbers")),
#(#("a", 1), #("bb", 22)),
borders: $dashed-borders)
+---------------+
|Letters|Numbers|
|===============|
|a |1 |
|-------+-------|
|bb |22 |
+---------------+
columnist reference¶
- columnize Generic function¶
- Signature:
columnize (stream columnist rows #rest columnist-options) => ()
- Parameters:
stream – An instance of
<stream>.columnist – An instance of
<column-spec>.rows – An instance of
<sequence>. Each row must have the same number of elements as there are columns in the table. All data is converted to strings using print-to-string(…, escape?: #f).columnist-options (#rest) – An instance of
<object>. See<columnist>init options.
- columnize(<stream>, <sequence>, <sequence>) Method¶
A method that accepts a sequence of
<column>objects.
- columnize(<stream>, <columnist>, <sequence>) Method¶
A method that accepts an instance of
<columnist>.
Alignment¶
- $align-center Constant¶
Center align cell text.
- $align-left Constant¶
Left align cell text.
- $align-right Constant¶
Right align cell text.
Borders¶
- $dashed-borders Constant¶
Use “dashed” borders. Using “+”, “-”, and “|” characters for all borders, including a border between each row.
- $default-borders Constant¶
Currently the same as
$internal-whitespace-borders.
- $internal-whitespace-borders Constant¶
No external borders, but a blank line after the column headers (if any) and two spaces between columns.
- <column> Open Class¶
A
<column>describes how each cell in a given column should be displayed.- Superclasses:
- Init-Keywords:
alignment – An instance of
<alignment>.header – An instance of
<string?>.maximum-width – An instance of
false-or(<integer>).minimum-width – An instance of
<integer>.pad? – An instance of
<boolean>. If#fthen no whitespace padding is output after the cell value. This is only useful if this is the last cell in the row to contain any data and there are no column borders. The intended use case is to avoid trailing whitespace in terminal output.
- <columnist> Open Class¶
A description of how to display a table. Currently the only attributes are a sequence of
<column>instances and a border specification.- Superclasses:
- Init-Keywords:
borders – An instance of
<border-style>.columns (required) – An instance of
<sequence>.
columnist-protocol reference¶
This module is provided for anyone who wants to create their own border type
- $border-bottom Constant¶
- $border-header Constant¶
- $border-internal Constant¶
- $border-top Constant¶
- <alignment> Constant¶
- <border-place> Constant¶
- <border-style> Class¶
- Superclasses:
- Init-Keywords:
bottom-inner – An instance of
<string>.bottom-left – An instance of
<string>.bottom-line – An instance of
<string?>.bottom-right – An instance of
<string>.data-row-inner – An instance of
<string>.data-row-left – An instance of
<string>.data-row-right – An instance of
<string>.header-separator-inner – An instance of
<string>.header-separator-left – An instance of
<string>.header-separator-line – An instance of
<string?>.header-separator-right – An instance of
<string>.separator-inner – An instance of
<string>.separator-left – An instance of
<string>.separator-line – An instance of
<string?>.separator-right – An instance of
<string>.top-inner – An instance of
<string>.top-left – An instance of
<string>.top-line – An instance of
<string?>.top-right – An instance of
<string>.
- bottom-inner Generic function¶
- Signature:
bottom-inner (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- bottom-left Generic function¶
- Signature:
bottom-left (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- bottom-line Generic function¶
- Signature:
bottom-line (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string?>.
- bottom-right Generic function¶
- Signature:
bottom-right (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- data-row-inner Generic function¶
- Signature:
data-row-inner (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- data-row-left Generic function¶
- Signature:
data-row-left (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- data-row-right Generic function¶
- Signature:
data-row-right (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- display-border-row Generic function¶
- Signature:
display-border-row (stream style column-widths place) => ()
- Parameters:
stream – An instance of
<stream>.style – An instance of
<border-style>.column-widths – An instance of
<sequence>.place – An instance of
<border-place>.
- display-data-row Generic function¶
- Signature:
display-data-row (stream columnist b column-widths row) => ()
- Parameters:
stream – An instance of
<stream>.columnist – An instance of
<columnist>.b – An instance of
<border-style>.column-widths – An instance of
<sequence>.row – An instance of
<sequence>.
- display-header Generic function¶
- Signature:
display-header (stream columnist b column-widths) => ()
- Parameters:
stream – An instance of
<stream>.columnist – An instance of
<columnist>.b – An instance of
<border-style>.column-widths – An instance of
<sequence>.
- display-table Generic function¶
- Signature:
display-table (stream columnist rows) => ()
- Parameters:
stream – An instance of
<stream>.columnist – An instance of
<columnist>.rows – An instance of
<sequence>.
- header-separator-inner Generic function¶
- Signature:
header-separator-inner (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- header-separator-left Generic function¶
- Signature:
header-separator-left (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- header-separator-line Generic function¶
- Signature:
header-separator-line (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string?>.
- header-separator-right Generic function¶
- Signature:
header-separator-right (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- separator-inner Generic function¶
- Signature:
separator-inner (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- separator-left Generic function¶
- Signature:
separator-left (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- separator-line Generic function¶
- Signature:
separator-line (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string?>.
- separator-right Generic function¶
- Signature:
separator-right (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- top-inner Generic function¶
- Signature:
top-inner (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- top-left Generic function¶
- Signature:
top-left (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- top-line Generic function¶
- Signature:
top-line (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string?>.
- top-right Generic function¶
- Signature:
top-right (object) => (value)
- Parameters:
object – An instance of
{<border-style> in columnist-protocol}.
- Values:
value – An instance of
<string>.
- validate-columns Generic function¶
- Signature:
validate-columns (columnist) => (#rest results)
- Parameters:
columnist – An instance of
<columnist>.
- Values:
#rest results – An instance of
<object>.
- validate-rows Generic function¶
- Signature:
validate-rows (columnist rows) => (#rest results)
- Parameters:
columnist – An instance of
<columnist>.rows – An instance of
<sequence>.
- Values:
#rest results – An instance of
<object>.