Skip to content

LispKit Text Table

Jump to bottom
Matthias Zenger edited this page Dec 11, 2021 · 1 revision

Library (lispkit text-table) provides an API for creating tables of textual content. The library supports column and cell-based text alignment, allows for multi-line rows, and supports different types of row separators.

Overview

A text table consists of one header row followed by regular text and separator rows. As part of the header row, it is possible to specify the text alignment of the header cell, the default text alignment of the corresponding column and a minimum and maximum size of the column (in terms of characters).

The following example shows how text tables are created:

(define tt (make-text-table
             '(("ID" center right)
               ("Name" center left)
               ("Address" center left 10 20)
               ("Approved" center center))
             double-line-sep))
(add-text-table-row! tt
  '("1" "Mark Smith"
        "2600 Windsor Road\nRedwood City, CA" "Yes"))
(add-text-table-separator! tt line-sep)
(add-text-table-row! tt
  '("2" "Emily Armstrong"
        "160 Randy Rock Way\nMountain View, CA" "No"))
(add-text-table-separator! tt line-sep)
(add-text-table-row! tt
  '("3" "Alexander Montgomery"
        "1500 Valencia Street\nSuite 100\nLos Altos, CA" "Yes"))
(add-text-table-separator! tt line-sep)
(add-text-table-row! tt
  '("4" "Myra Jones"
        "1320 Topaz Street\nPalo Alto, CA" "Yes"))

A displayable string representation can be generated via procedure text-table->string. This is what the result looks like:

┌────┬──────────────────────┬──────────────────────┬──────────┐
│ ID │         Name         │       Address        │ Approved │
╞════╪══════════════════════╪══════════════════════╪══════════╡
│  1 │ Mark Smith           │ 2600 Windsor Road    │   Yes    │
│    │                      │ Redwood City, CA     │          │
├────┼──────────────────────┼──────────────────────┼──────────┤
│  2 │ Emily Armstrong      │ 160 Randy Rock Way   │    No    │
│    │                      │ Mountain View, CA    │          │
├────┼──────────────────────┼──────────────────────┼──────────┤
│  3 │ Alexander Montgomery │ 1500 Valencia Street │   Yes    │
│    │                      │ Suite 100            │          │
│    │                      │ Los Altos, CA        │          │
├────┼──────────────────────┼──────────────────────┼──────────┤
│  4 │ Myra Jones           │ 1320 Topaz Street    │   Yes    │
│    │                      │ Palo Alto, CA        │          │
└────┴──────────────────────┴──────────────────────┴──────────┘

API

(text-table? obj)     [procedure]

Returns #t if obj is a text table object; returns #f otherwise.

(text-table-header? obj)     [procedure]

Returns #t if obj is a valid text table header. A text table header is a proper list of header cells, one for each column of the text table. A header cell has one of the following forms:

  • "title", just specifying the column title.
  • ("title" halign) where halign is an alignment specifier (i.e. either left, right, center) that declares how the title is aligned.
  • ("title" halign calign) where halign and calign are alignment specifiers. halign declares how the column title is aligned, calign declares how the content in the rest of the column is aligned by default.
  • ("title" halign calign min) where halign and calign are alignment specifiers and min is the minimum size of the column.
  • ("title" halign calign min max) where halign and calign are alignment specifiers and min is the minimum and max the maximum size of the column.

(text-table-row? obj)     [procedure]

Returns #t if obj is a valid text table row. A text table row is a proper list of row cells, one for each column of the text table. A row cell has one of the following forms:

  • "content", just specifying the content of the cell.
  • ("content" align) where align is an alignment specifier (i.e. either left, right, center) that declares how the content in the row cell is aligned.

(make-text-table headers)     [procedure]
(make-text-table headers sep)
(make-text-table headers sep edges)

Returns a new text table with the given header row. headers is a valid text table header, sep is a separator between header and table rows (i.e. an object for which text-table-separator? returns #t) and edges specifies whether the table edges are round (round-edges) or sharp (sharp-edges).

(make-text-table
  '(("x" center right 3 5) ("f(x)" center right))
  double-line-sep)

(add-text-table-row! table row)     [procedure]

Adds a new row to the given text table. row is a valid text table row, i.e. it is a proper list of row cells, one for each column of the text table. A row cell is either a string or a list with two elements, a string and an alignment specifier (i.e. either left, right, center) which declares how the content in the row cell is aligned.

(add-text-table-separator! table)     [procedure]
(add-text-table-separator! table sep)

Adds a new row separator to the given table. sep is a separator, i.e. it is either space-sep, line-sep, double-line-sep, bold-line-sep, dashed-line-sep, or bold-dashed-line-sep. The default for sep is line-sep.

(alignment-specifier? obj)     [procedure]

Returns #t if obj is a valid alignment specifier. Supported alignment specifiers are left, right, and center.

left     [object]
right
center

Corresponds to one of the three supported alignment specifiers for text tables.

(text-table-edges? obj)     [procedure]

Returns #t if obj is a valid text table edges specifier. Supported edges specifiers are no-edges, round-edges, and sharp-edges.

no-edges     [object]
round-edges
sharp-edges

Corresponds to one of the three supported edges specifiers for text tables.

(text-table-separator? obj)     [procedure]

Returns #t if obj is a valid text table separator. Supported separators are no-sep, space-sep, line-sep, double-line-sep, bold-line-sep, dashed-line-sep, bold-dashed-line-sep.

no-sep     [object]
space-sep
line-sep
double-line-sep
bold-line-sep
dashed-line-sep
bold-dashed-line-sep

Corresponds to one of the seven supported text table separators.

(text-table->string table)     [procedure]
(text-table->string table border)

Returns the given text table as a string that can be displayed. border is a boolean argument specifying whether a border is printed around the table.

Clone this wiki locally