(std fmt)

Overview

Formatting in two layers: interpolation of scalars, and a composable layout of blocks.

(import (std prelude))
(import (std fmt))

;; Layer 1: interpolation
(println* ["Hello, " 42 ", ok? " #t])

;; Layer 2: layout
(show "Hello\n")
(show ["Padding: [" (padded/left 10 "foo") "]" nl])
(show ["Number: " (numeric/comma 1234567.89) nl])
(show ["Columns:" nl
       (columnar [["first long text string" "second text string"]
                  ["col 2" "more text for col 2"]])])

;; A string, an int or a char is a block, as a variable or a call as
;; well as written out. A vec of blocks is a block too.
(def name "Ada")
(def n 3)
(show (padded/left 8 name))                     ;;      Ada
(show ["Hello, " name "! You have " n " new messages" #\. nl])
;; Hello, Ada! You have 3 new messages.
(show [(padded/left 8 ["x = " n]) "|" nl])      ;;    x = 3|

;; A block made from a record, by a function with a signature.
;; A double goes through numeric; an if picks a block or nothing.
(type (: Item (Record (: name string) (: price double) (: stock int))))

(: item-line (-> Item Block))
(defun (item-line i)
  [(padded/right 10 (record-ref i name))
   (padded/left 9 (numeric (record-ref i price) #:precision 2 #:comma 3))
   (if (= (record-ref i stock) 0) "  sold out" nothing)
   nl])

;; vec-map gives a vec of blocks, which is a block.
(show (vec-map item-line stock))
;; Green tea      3.50
;; Gaiwan     1,240.00
;; Kettle        89.90  sold out

;; A row per record. A row is a (Vec Block), a block per cell.
(: item-row (-> Item (Vec Block)))
(defun (item-row i)
  [(record-ref i name)
   (numeric (record-ref i price) #:precision 2)
   (record-ref i stock)])

(show (tabular/rows (vec-map item-row stock)
                    #:titles ["Item" "Price" "Stock"]
                    #:align [AlignLeft (AlignOn #\.) AlignRight]
                    #:style StyleAscii))
;; +-----------+---------+-------+
;; | Item      |   Price | Stock |
;; +-----------+---------+-------+
;; | Green tea |    3.50 |    12 |
;; | Gaiwan    | 1240.00 |     2 |
;; | Kettle    |   89.90 |     0 |
;; +-----------+---------+-------+

;; What an if, a cond, a match or a let gives is a block if it is
;; one of the things a block can be.
(show ["Title: " (match title ((Some t) t) (None "-")) nl])

(: greeting (-> string (Option string) Block))
(defun (greeting name title)
  ["Hello, "
   (match title
     ((Some t) [t " "])
     (None nothing))
   name "!"])

(show [(greeting "Ada" (Some "Dr")) nl (greeting "Bob" None) nl])
;; Hello, Dr Ada!
;; Hello, Bob!

Interpolation combines scalars of mixed types into text. It works on a (Vec Disp): a vec literal whose elements are strings, ints, doubles, chars and bools. The grammar Disp reads each element into the case that holds it. println* prints one.

Layout is a block algebra, for padding, aligning, wrapping paragraphs and laying out tables. Everything is a Block: a piece of output. Every function here that lays something out takes its content as a block and gives back a block, so they nest. Nothing is written until a block is run by show, render or render->string.

What is a block. Where a Block is wanted, as an argument or in a vec literal of blocks, each of these is one:

What you write	What it is
A string, an int or a char: written out, a variable or a call	`BStr`, `BInt`, `BChar`
A vec of any of these, written out or a `(Vec Block)`	`BMany`: its blocks in order
A `Block`: `nl`, `nothing`, a call such as `(padded/left 5 "x")`	itself
An `if`, `cond`, `match` or `let` whose results are any of these	the result it gives

So a single thing needs no brackets, and several things are a vec:

(show "hej")                                   ; hej
(show (padded/left 5 name))                    ; "  Ada"
(show (padded/left 8 ["x = " n]))              ; "   x = 3"
(show [(padded/left 5 "x") (padded/left 5 "y") nl])

A vec in a vec is a block in a block, so extra brackets change nothing. A table is the place where the brackets matter: tabular/rows takes a vec of rows, and a row is a (Vec Block) with a block for each cell. A cell of several pieces is a vec in the row: ["tea" [3 " cups"]] is two cells.

Anything else is converted first:

You have	Write
A double `x`	`(numeric x)`, or `(numeric x #:precision 2)`
A bool `b`	`(if b "yes" "no")`
A long `n`	`(long->string n)`, or `(bytes n)` for a size
A `(Vec string)` `xs`	`(vec-map BStr xs)`
A `(List %a)` `xs`	`(joined f xs ", ")`, where `f` makes the block of one element

Where the type is known. A string or a vec is read as a block where a block is wanted: as an argument, as what a function declared to return a Block returns, and as the value of a binding whose type is written. A lambda given to a function that does not say what the lambda returns, such as vec-map, has no type to read a vec literal at, so a vec of mixed pieces that it returns is refused: give it to each, as in (vec-map (fun (x) (each [x nl])) xs), or write a function with a signature. A function of your own that takes blocks needs its signature for the same reason.

A number bound by def. (def n 3) does not say what kind of number n is. Where a block is wanted, it is read as the number written there would be: ["n = " n] is what ["n = " 3] is, and n is an int from then on. A number used as a double later, as in (+ n 0.5), needs (: n double) above its def.

When it does not compile. The messages for the common mistakes, and what to write instead:

The compiler says	Write
Block: … found a double	`(numeric x)`
Block: … found the number 1.5	`(numeric 1.5)`
Block: … found a boolean, or found a bool	`(if b "yes" "no")`
Block: … found a (Vec string)	`(vec-map BStr xs)`, or `(: xs (Vec Block))` above `(def xs ...)`
Block: … found a (Vec (Vec …)), at a lambda that returns a vec	`(each [...])` around the vec the lambda returns

A combinator of your own is a BRun and the two functions that run blocks, run-block and run-blocks. It is the same kind of thing as the ones in this module:

(: boxed (-> Block Block))
(defun (boxed b)
  (BRun (fun (out col)
          (run-blocks out col ["[" (render->string b) "]"]))))

Settings are parameters, so they are dynamically scoped: with-fmt binds one around a block while it runs, and it is restored when the block ends; with-fmt* binds several, as parameterize does. A block reads a setting when it runs, so a parameterize works around show, but not around the code that builds the block. The settings here are:

Parameter	Default	What it sets
`current-pad`	`#\space`	The character padding is made of.
`current-width`	`78`	The right margin of `wrapped`, `justified`, `columnar`, and a table that cuts or wraps.
`current-ellipsis`	`""`	What replaces the part a trim cuts off.
`current-string-width`	the character count	How wide a string is, in columns. `terminal-width` counts as a terminal does.
`current-precision`	`-1`	Digits after the decimal separator; negative is as many as needed.
`current-comma`	`0`	Digits per group; zero is no grouping.
`current-comma-sep`	`#\,`	The character between groups.
`current-decimal-sep`	`#\.`	The decimal separator.
`current-signed`	`#f`	Whether a positive number gets a leading `+`.

A setting of your own works the same way: with-fmt takes the parameter as an argument. Read it with parameter-ref inside the BRun’s function, when the block runs. Read where the block is built, it is read before any enclosing with-fmt has bound it.

Tables are tabular, tabular/rows and columnar as functions, table-row a row at a time, and Table as a quoted literal that the compiler checks. They draw borders in a TableStyle, a header and rules, align a column on a character, and fit current-width by cutting or wrapping cells. bytes, percent, bar and sparkline are blocks for what goes in a cell, or anywhere else. Set current-string-width to terminal-width for text with wide characters or colours in it.

Reference

Types

`Disp`

union ↑ Types

A scalar to interpolate: a string, int, double, char or bool.

DStr: A string, as it is.
DInt: An int, by int->string.
DDouble: A double, by double->string.
DChar: A char, as one character.
DBool: A bool, as #t or #f.

Disp is a grammar (see def/grammar). In a vec literal of mixed scalars, such as ["n = " 42 ", ok? " #t], the grammar reads each element into the case that can hold it. Thus you rarely write the cases.

`Sink`

type alias ↑ Types

Where a block writes its text: a function given each piece of it.

`Block`

union ↑ Types

A piece of layout: a scalar, or a function that writes output and returns the final column position.

BStr: A string, written as it is.
BInt: An int, written in decimal.
BChar: A char.
BMany: Blocks in order: what a vec of blocks is.
BRun: A function taking (sink, col) that writes output and returns the resulting column.

(render->string ["x = " 7 #\!])   ; "x = 7!": a vec of a string, an int and a char

;; The cases are rarely written: where a block is wanted, a value is
;; read as the case that holds it.
(def s "tea")
(: b Block)
(def b s)                      ; (BStr "tea")
(: bs (Vec Block))
(def bs [s " and " b])
(show [bs nl])                 ; tea and tea: a vec in a vec is a block in a block
(show (vec-map BStr ["a" "b"]))   ; ab: a vec of strings made a vec of blocks

;; A function that returns a block.
(: bullets (-> (Vec string) Block))
(defun (bullets xs)
  (vec-map (fun (x) (each ["  * " x nl])) xs))

(: labelled (-> string int Block))
(defun (labelled label n)
  [label ": " n nl])

(show [(bullets ["tea" "milk"]) (labelled "cups" 3)])
;;   * tea
;;   * milk
;; cups: 3

The column is counted in characters since the last newline written. It is the one thing threaded through every block, and what lets fl, space-to and wrapped know where the cursor is.

Block is a grammar (see def/grammar). Where a block is wanted, a string, an int, a char or a vec of blocks is read as the case that holds it, whether it is written out or the value of a variable or a call. The module doc lists what else is a block, and how to convert what is not.

See also: run-block, each, captured

`Align`

union ↑ Types

Where a cell sits in its table column.

AlignLeft: Against the left edge, padded on the right. The default.
AlignRight: Against the right edge, padded on the left: what numbers want.
AlignCentre: In the middle, the odd column of padding on the right.
AlignOn: Every line of the column has the character in the same place, as a decimal point is in a column of numbers. A line without the character ends where the character would be. The part as a whole is aligned to the right, and so is the title over it.

(show (tabular/rows [["tea" "3.5"] ["gaiwan" "1240"] ["kettle" "89.90"]]
                    #:align [AlignLeft (AlignOn #\.)]))
;; tea       3.5
;; gaiwan 1240
;; kettle   89.90

AlignOn needs the widest part of a line before the character and the widest part from it on, so it is measured by the tables that see all their rows: tabular and tabular/rows. A table laid out a row at a time, and columnar, align such a column to the right.

`TableStyle`

union ↑ Types

How a table’s borders and rules are drawn.

StyleNone: No borders: the columns with a separator between them. The default.
StyleSimple: No borders, two spaces between the columns, and a line of ─ under the header.
StyleAscii: A box of +, - and |.
StyleLight: A box of light lines: ┌─┬─┐.
StyleHeavy: A box of heavy lines: ┏━┳━┓.
StyleDouble: A box of double lines: ╔═╦═╗.
StyleRounded: A box of light lines with round corners: ╭─┬─╮.
StyleMarkdown: A Markdown table, whose rule under the header says how each column is aligned.
StyleCustom: The pieces of a BorderChars.

(show (tabular/rows [["tea" "3.50"] ["gaiwan" "1240.00"]]
                    #:titles ["Item" "Price"]
                    #:style StyleAscii
                    #:align [AlignLeft AlignRight]))
;; +--------+---------+
;; | Item   |   Price |
;; +--------+---------+
;; | tea    |    3.50 |
;; | gaiwan | 1240.00 |
;; +--------+---------+
;;
;; The other boxes are the same table drawn with other characters.

A style with a box pads each cell with a space on each side, and pads every cell to its column, the last one too, so that the right edge is straight. A Markdown column is at least three wide, as its rule needs.

`TableRules`

union ↑ Types

Which horizontal rules a table has inside its borders.

RulesHeader: A rule under the header. The default.
RulesEvery: A rule under the header and between every two rows. Markdown has none between rows.
RulesNone: No rules inside the table.

`ColumnWidth`

union ↑ Types

How wide a table column is.

WidthAuto: As wide as its widest line. The default.
WidthFixed: This many columns, at least one.
WidthAtLeast: As wide as its content, and at least this many columns.
WidthAtMost: As wide as its content, and at most this many columns.
WidthShare: A share of what the other columns and the borders leave of current-width: two columns of shares 1 and 2 take a third and two thirds of it.

(with-fmt current-width 30
  (tabular/rows [["a" "b" "c"]] #:style StyleAscii
                #:widths [(WidthFixed 5) (WidthShare 1) (WidthShare 2)]))
;; +-------+-------+------------+
;; | a     | b     | c          |
;; +-------+-------+------------+

A column narrower than its content shows the content as its Overflow says: pushed out of line, cut or wrapped. A width of no more than zero is one.

`Overflow`

union ↑ Types

What a table cell wider than its column does.

OverflowPush: It pushes the rest of its row out of line. The default, and what a table without width rules does.
OverflowCut: It is cut to the column, on the side away from its alignment, with current-ellipsis in place of what is cut.
OverflowWrap: It is broken at its spaces onto more lines, and a word wider than the column is broken where it reaches the edge.

(with-fmt current-width 40
  (tabular/rows [["tea" "A green tea from the hills, picked in spring and rolled by hand."]]
                #:titles ["Item" "Note"] #:style StyleAscii #:overflow OverflowWrap))
;; +------+-------------------------------+
;; | Item | Note                          |
;; +------+-------------------------------+
;; | tea  | A green tea from the hills,   |
;; |      | picked in spring and rolled   |
;; |      | by hand.                      |
;; +------+-------------------------------+

A table that cuts or wraps is made to fit current-width: while it is too wide, the widest column that may shrink loses a column. A column of a fixed width does not shrink, nor one at its WidthAtLeast, nor one below one column. A column aligned on a character is neither cut nor wrapped, since the character would no longer line up.

`BorderChars`

record ↑ Types

The pieces a table’s borders are drawn with, for a style of your own.

top-left: The start of the line above the table.
top: Repeated across each column in the line above the table. Empty means there is no such line.
top-join: Where two columns meet in the line above the table.
top-right: The end of the line above the table.
left: Before the first cell of a row.
column: Between two cells of a row.
right: After the last cell of a row.
rule-left: The start of a rule.
rule: Repeated across each column in a rule. Empty means there are no rules.
rule-join: Where two columns meet in a rule.
rule-right: The end of a rule.
bottom-left: The start of the line under the table.
bottom: Repeated across each column in the line under the table. Empty means there is no such line.
bottom-join: Where two columns meet in the line under the table.
bottom-right: The end of the line under the table.
marks: Whether the rule under the header marks each column's alignment with colons, as Markdown's does.

A piece of a horizontal line is as wide as the piece of a row it is under: top-left as left, top-join as column, and so on. The built-in boxes put a space on each side of a cell, so their left is "│ " and their top-left is "┌─". A table without left and right leaves out the empty cells at the end of a line and does not pad its last cell, as a table without borders does.

`TableLayout`

record ↑ Types

The widths, alignments, separator and style of a table laid out a row at a time.

widths: The width of each column.
aligns: The alignment of each column, from the first; a column not given one is AlignLeft.
sep: Written between the columns, without borders.
style: How the borders are drawn.

`Table`

record ↑ Types

A table written as a quoted literal: its options, its columns, and its rows.

options: The table's style, header, rules, width and overflow, each there or not.
columns: The columns, each with its title, alignment, width and kind.
rows: The rows, each written or spliced.

(: (Vec (Vec TableCell)))
(def products
  [[(CellText "Green tea") (CellNum 3.5) (CellInt 12) (CellNum 0.4)]
   [(CellText "Gaiwan") (CellNum 1240.0) (CellInt 2) (CellNum 1.0)]])

(show-table
 '(table (style ascii) header
         (column "Item")
         (column "Price" (align (on #\.)) (number (precision 2) (comma 3)))
         (column "Stock" (align right))
         (column "Share" (percent (precision 0)))
         (rows ,products)))
;; +-----------+----------+-------+-------+
;; | Item      |    Price | Stock | Share |
;; +-----------+----------+-------+-------+
;; | Green tea |     3.50 |    12 |   40% |
;; | Gaiwan    | 1,240.00 |     2 |  100% |
;; +-----------+----------+-------+-------+
;;
;; A column of (bar (max 100.0)) shows each number as a bar of its
;; share of the max, as the block bar does.

(show-table '(table (style markdown) header (column "Key") (column "Value")
                    (rows (row "width" 78) (row "style" "markdown"))))

The literal is (table option ... column ... (rows row ...)). The options come first, each at most once and in any order: (style s) with a TableStyle as its name, rounded or markdown; header, which makes the column titles a header row; (rules r) with a TableRules; (width n), the width the table is fitted to in place of current-width; and (overflow o) with an Overflow.

A column is (column "Title" option ...), its options again each at most once: (align a) with an Align, as right or (on #\.); (width w) with a ColumnWidth, as 12 or (share 2); and a kind, which shows the column’s numbers as one of this module’s blocks: (number (precision 2) (comma 3) signed) as numeric, bytes, (percent (precision 1)), or (bar (max 100.0) (width 10)), a bar of the number’s share of the max. A column of a kind other than a bar is aligned to the right unless it says otherwise. A cell that is not a number is shown as it is in any column.

A row is written, (row cell ...), a cell being a string or a number or a spliced value of one; or spliced, as a (Vec TableCell) for one row or a (Vec (Vec TableCell)) for many. A spliced number bound by a def of a bare literal is read as the number written there would be, as it is in a block.

The literal is read where it is written, so a misspelled option, an option given twice, a style that is not one, a table with no columns and a splice of the wrong type are compile errors that say where.

`TableCell`

union ↑ Types

A cell of a Table: what a written cell is, and what a spliced row holds.

CellText: Text, shown as it is.
CellInt: A whole number, shown as its column's kind says.
CellNum: A number, shown as its column's kind says.
CellBlocks: Blocks, shown as they are, as each shows them.

Overview

Reference

Types

Disp

Sink

Block

Align

TableStyle

TableRules

ColumnWidth

Overflow

BorderChars

TableLayout

Table

TableCell

Functions

println*

render

show

render->string

run-block

run-blocks

with-fmt

with-pad

terminal-width

each

captured

width-of

space-to

tab-to

padded/left

padded/right

padded/both

trimmed/left

trimmed/right

trimmed/both

fitted/left

fitted/right

fitted/both

joined

joined/prefix

joined/suffix

joined/last

numeric

numeric/comma

bytes

percent

bar

sparkline

wrapped

justified

columnar

tabular

tabular/rows

table-layout

table-top

table-rule

table-bottom

table-widths

table-row

table-block

show-table

Values

current-pad

current-width

current-ellipsis

current-string-width

current-precision

current-comma

current-comma-sep

current-decimal-sep

current-signed

nothing

nl

fl

Macros

with-fmt*

`Disp`

`Sink`

`Block`

`Align`

`TableStyle`

`TableRules`

`ColumnWidth`

`Overflow`

`BorderChars`

`TableLayout`

`Table`

`TableCell`

`println*`

`render`

`show`

`render->string`

`run-block`

`run-blocks`

`with-fmt`

`with-pad`

`terminal-width`

`each`

`captured`

`width-of`

`space-to`

`tab-to`

`padded/left`

`padded/right`

`padded/both`

`trimmed/left`

`trimmed/right`

`trimmed/both`

`fitted/left`

`fitted/right`

`fitted/both`

`joined`

`joined/prefix`

`joined/suffix`

`joined/last`

`numeric`

`numeric/comma`

`bytes`

`percent`

`bar`

`sparkline`

`wrapped`

`justified`

`columnar`

`tabular`

`tabular/rows`

`table-layout`

`table-top`

`table-rule`

`table-bottom`

`table-widths`

`table-row`

`table-block`

`show-table`

`current-pad`

`current-width`

`current-ellipsis`

`current-string-width`

`current-precision`

`current-comma`

`current-comma-sep`

`current-decimal-sep`

`current-signed`

`nothing`

`nl`

`fl`

`with-fmt*`