LispKit Text-Table

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-type-tag [constant]

Symbol representing the text-table type. The type-for procedure of library (lispkit type) returns this symbol for all text table objects.

(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:

(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:

(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.