A simple formatter for Racket

1 Rationale

Simple formatting tools can be useful when readability of output for the human eye is of some importance, but not to the extent that a highly finished presentation is required. Examples of simple formatters for Racket are the various versions of procedure format. They are handy tools, but in some cases may not provide enough functionality. Which functions a simple formatter should provide and which shape it should have is a matter of personal taste, I think. In this document I show a simple formatter that more or less satisfies my own taste. It combines some of the powerful features of the format-statement of Fortran with the flexibility of Racket’s generic procedures write and display. The principles are simple enough to get started almost immediately. Nevertheless tools for padding, tabulation, several numerical formats, literals, iteration and compound instructions are included. Field widths, tabulator positions and repetition counts can be constants within the format, but can also be obtained from the data.

Warning: padding and tabulation are implemented by insertion of spaces and therefore require a fixed width character font, such as Courier, in order to function properly.

2 Format-procedures

Formats can be regarded as procedures that transform data from one representation into another one. Procedure fmt is based on this idea. It translates strings of format-instructions into a format-procedure, that is, a Racket procedure that accepts data and returns the formatted external representation of the data as a string or sends it through an output-port. The amount of output that can be produced by a single format-procedure call may be subjected to a platform dependent limit, because the produced output is gathered in an output-string before being committed. If during formatting an error is detected, an exception is raised and no output is produced at all.

3 Procedure fmt

procedure (fmt format ... [port]) → fmt?

format : (or/c string? fmt?)

port   :   (or/c output-port? 'string 'current 'argument)       =   'string

Procedure fmt returns a format-procedure. The port-argument may be placed at arbitrary position among the format-arguments. The symbols 'string, 'current and 'argument can be abbreviated as 'str, 'cur and 'arg. A format-argument is either a format-string or a format-procedure made by procedure fmt. All format-strings are parsed, checked for correctness and translated to subprocedures of the format-procedure to be produced. If no format-argument is given, "" is assumed. Adjacent format-strings are parsed as though concatenated to form one single string with commas inserted between the individual strings. The commas are separators. Each argument consisting of a format-procedure is inserted as a compound instruction without being parsed or translated again. The ports of the inserted format-procedures are ignored.

4 Format-procedure calls

When procedure fmt was called without a port argument or with an output-port or symbol 'string or 'current for its port argument, the returned format-procedure, say fmt-proc-1, can be called as follows:

format-procedure (fmt-proc-1 datum ...) → (or/c string? void?)

datum : any/c

When procedure fmt was called with symbol 'argument for its port argument, the returned format-procedure, say fmt-proc-2, can be called as follows:

format-procedure (fmt-proc-2 port datum ...) → (or/c void? string?)

port : (or/c output-port? 'string 'current)

datum : any/c

((fmt "I5") 12) → "◦◦◦12"

((fmt "I5" 'string) 12) → "◦◦◦12"

((fmt "I5" 'current) 12) → void, displays ◦◦◦12

((fmt "I5" (current-output-port)) 12) → void, displays ◦◦◦12

((fmt "I5" 'argument) 'string 12) → "◦◦◦12"

((fmt "I5" 'argument) 'current 12) → void, displays ◦◦◦12

((fmt "I5" 'argument) (current-output-port) 12) → void, displays ◦◦◦12

Forgetting the port-argument when calling a format-procedure made with port-argument 'argument raises an error:

> (require "fmt.rkt")

> (define my-fmt (fmt "I5" 'argument))

> (my-fmt 12)

fmt-proc: expected argument of type <output-port or symbol

current or string>; given: 12

5 Format-strings

A format-string describes a format-procedure in its own simple language. The format-instructions are non verbose. Each elementary instruction consists of one single character, possibly preceded by a repetition count and followed by one or more numeric arguments, such as a field width or tabulator position. A format-string can include literal data, for example for headers. There is no distinction between lower case and capital letters, except within literal data. Separators, id est white space and commas, are irrelevant except in the following cases:

• Within a literal, separators are part of the literal.

• No separator must appear within a numeric argument or iteration count.

• Some instructions may be followed by one or more numerical arguments. These arguments may be omitted starting from the last one. However, when omitting one or more arguments where the next instruction starts with a token that can be interpreted as a numerical argument, a comma is required as separator, optionally preceded and/or followed by other separators. Hence, no comma must appear before any numerical argument belonging to the preceding instruction. White space is required between two numerical arguments if the first character of the second one could be parsed as belonging to the previous one.

• Where a literal is followed by a literal beginning with a single quote a separator is required. The reason is that the start and end of a literal are marked by a single quote and that within a literal two immediately adjacent single quotes are read as one single quote belonging to the literal.

6 Format-instructions

See the synopsis for a list of all format-instructions.

A format-procedure is given data to be formatted. A format-instruction that consumes a datum, removes it from the list of data in order that the next data consuming instruction gets the next datum. An error is reported if an attempt is made to execute a data consuming instruction after all data already have been consumed or when unconsumed data remain after completion of the format-procedure. There are instructions that add data to the list of remaining data, possibly after consuming data. The added data always are the first to be consumed next. For example, instruction Y consumes a datum, which must be a number, and adds the real and the imaginary part of the number as two separate real numbers in front of the remaining data. Subsequent format-instructions can treat the real and imaginary part separately.

6.1 Instruction arguments

In the description of the instructions, ξ represents an argument consisting of an instruction. ν, μ and ε represent numerical arguments such as a field width or a tabulator position. Omitted numerical arguments are zero. A repetition count has the same form as a numerical argument. Numerical arguments and repetition counts can have one of the following three forms:

((fmt "I5") 12) → "◦◦◦12" integer format, field width 5.

((fmt "I5.3") 12) → "◦◦012" integer format, field width 5, at least 3 decimal figures.

((fmt "I##") 5 3 12) → "◦◦012" idem taking the arguments from the data.

6.2 Elementary format-instructions

See the Racket documentation: The Printer for the distinction between display, write and print

D

Consumes one datum and displays it according to the current padding mode. If the datum is a string and padding is switched on, heading and trailing spaces are removed before the string is padded. No spaces are removed from or added to strings that are non trivial parts of the datum, for example in case the datum is a list of strings.

W

Consumes one datum and writes it according to the current padding mode.

P

Consumes one datum and prints it according to the current padding mode.

X

Executes a newline instruction and marks the start of this line. See tabulation.

|

Executes a newline instruction only if not at the start of the current line.

Examples:

((fmt 'current "DXDXD")  "Jacob" 3 #\x) → void, displays Jacob 3 x

((fmt 'current "WXWXW")  "Jacob" 3 #\x) → void, displays "Jacob" 3 #\x

((fmt 'current "D") (list "Jacob" 3 #\x)) → void, displays (Jacob 3 x)

((fmt 'current "W") (list "Jacob" 3 #\x)) → void, displays ("Jacob" 3 #\x)

6.3 Padding

Padding applies to literal data and the instructions D W, P, B, O and H. When padding is switched on, these instructions add heading and/or trailing spaces if otherwise fewer characters would be generated than indicated by the field width. Instruction D first removes heading and trailing spaces when padding a string. The same holds when padding a literal datum. Output that does not fit within the field width is not truncated. Initially padding is switched off. When a format-procedure is called from another format-procedure, the former inherits the padding mode from the latter. If the called procedure alters the padding mode, the alteration remains effective after return. Instruction A can be used to restore the previous padding mode. Warning: because padding is done by insertion of spaces, it is useful only with a font of fixed character width.

N

Switches padding off. No spaces are removed or added.

Lν

For left alignment in fields of ν characters.

Rν

For centred alignment in fields of ν characters. When needed, spaces are added to the left and to the right in order to match the field width. If the number of spaces to be added is even, say 2k, then k spaces are added both at the left and at the right. If the number of spaces to be added is odd, say 2k+1, then k+1 spaces are added to the left and k spaces to the right.

Aξ

Memorizes the current padding mode and field width, executes instruction ξ and upon completion restores the memorized padding mode and field width.

((fmt "L5*D") 1 2 3) → "1◦◦◦◦2◦◦◦◦3◦◦◦◦"

((fmt "R5*D") 1 2 3) → "◦◦◦◦1◦◦◦◦2◦◦◦◦3"

((fmt "C5*D") 1 2 3) → "◦◦1◦◦◦◦2◦◦◦◦3◦◦"

((fmt "N  D") "◦◦Jacob◦◦") → "◦◦Jacob◦◦" ; no spaces removed, nor added.

((fmt "L0 D") "◦◦Jacob◦◦") → "Jacob" ; spaces removed, no spaces added.

((fmt "L8 D") "◦◦Jacob◦◦") → "Jacob◦◦◦" ; spaces first removed, then added.

6.4 Literal data

’κ ...’

Each κ is an arbitrary character, except that a single quote must be written as two immediately adjacent single quotes. The string "κ..."} is displayed according to the current padding mode.

Because within a literal, two adjacent single quotes are read as one single quote being part of the literal, a separator is required between two adjacent literals when the second one is of the first form. Warning: in the arguments of procedure fmt, ’κ...’ must not be split over two or more format-strings.

((fmt "R10'1Article','Price'")) → "◦◦◦Article◦◦◦◦◦Price"

((fmt "^'Article◦Price'R10◦2D")) → "◦◦◦Article◦◦◦◦◦Price"

> (require "fmt.rkt")

> (fmt "'Article" "Price'")

fmt: unbalanced quote in "'Article"

6.5 Numerical formats

The numerical format-instructions I, F and E have their own padding, independent from the padding mode described elsewhere in this document.

Iνμ

Consumes and displays a real number. First the sign of the datum is determined. Subsequently the datum is rounded to an exact integer number. If rounding produces zero, the sign is retained. If a sign is to be written, it is placed immediately in front of the first decimal figure. Leading spaces are added if otherwise less than ν characters would be produced. In all cases the result contains at least μ decimal figures, padding with heading zeros when necessary, or at least one decimal figure if μ is zero. The exceptional numbers ±inf.0 and ±nan.0 are treated specially. They are right justified in a field of at least ν characters. Instruction I is particularly useful for integer numbers, but nevertheless accepts any real number.

((fmt "*I3") 2 3.4 5.6) → "◦◦2◦◦3◦◦6"

((fmt "*I3.2") 2 3.4 5.6) → "◦02◦03◦06"

((fmt "I") 0.1) → "0"

((fmt "I") -0.1) → "-0"

((fmt "I") 1.0e-100000) → "0"

((fmt "I") -1.0e-100000) → "-0"

((fmt "I") 1.0e1000000) → "+inf.0"

((fmt "I") -1.0e1000000) → "-inf.0"

((fmt "I") (/ 0.0 0.0)) → "+nan.0"

(string-length ((fmt "I") #e1e100000)) → 100001

Fνμ

Consumes and displays a real number in decimal expansion: leading spaces, [sign], integer part, period, fraction of exactly μ decimal figures. The datum is rounded such as to fit the width of the fraction. If rounding yields zero, the sign is retained. The result has at least one decimal figure before the period. Leading spaces are added if otherwise less than ν characters would be produced. The exceptional numbers ±inf.0 and ±nan.0 are treated specially. They are right justified in a field of at least ν characters.

((fmt "*F3  ") 2 3.4 5.6) → "◦2.◦3.◦6."

((fmt "*F5.2") 2 3.4 5.6) → "◦2.00◦3.40◦5.60"

((fmt "F.4") 2/3) → "0.6667"

((fmt "D") 2/3) → "2/3"

((fmt "F.2")  1.0e1000000) → "+inf.0"

((fmt "F.2") -1.0e1000000) → "-inf.0"

((fmt "F.2") -1.0e-100000) → "-0.00"

Eνμε

Consumes and displays a real number in scientific notation: leading blanks, [sign], one decimal figure, period, exactly μ decimal figures, letter e, sign of exponent, ε or more decimal figures of exponent. If the number is not zero, the output is normalized such that the decimal figure before the decimal point is not zero. If the number is zero, all decimal figures are zero. Leading spaces are added if otherwise less than ν characters would be produced. The exceptional numbers ±inf.0 and ±nan.0 are treated specially. They are right justified in a field of at least ν characters.

((fmt "*E10.3.2") 2/3 2.3e-2) → "◦6.667e-01◦2.300e-02"

((fmt "E.5") 2/3) → "6.66667e-1"

((fmt "E15.5.4") 2/3) → "◦◦6.66667e-0001"

((fmt "EXE") #e-1e1000000 -1.0e1000000) → "-1.e+100000◦-inf.0"

((fmt "EXE") #e-1e-100000 -1.0e-100000) → "-1.e-100000◦-0.e+0"

B

Displays a real number in hexadecimal notation.

Instructions B, O and H convert the number into an exact one and use number->string to convert the absolute value and display the result according to the current padding and sign mode.

((fmt "H") 20/31) → "14/1f"

((fmt "D") 20/31) → "20/31"

((fmt "H") -2.71) → "-ad70a3d70a3d7/4000000000000"

((fmt "H") 2.71e-2) → "6f0068db8bac7/100000000000000"

((fmt "H") #e2.71e-2) → "10f/2710" ; 271 in the denominator is a coincidence.

((fmt "R8 H") 2.71e-200000) → "◦◦◦◦◦◦◦0"

((fmt "R8 H") -2.71e-200000) → "◦◦◦◦◦◦-0"

((fmt "R8 H") 2.71e2000000) → "◦◦+inf.0"

((fmt "H") 0) → "0"

6.6 Sign mode

The sign mode is relevant for the numerical instructions I, F, E, B, O and H. When sign mode is off, positive numbers get no sign. When sign mode is on, positive numbers, exact zero and +0.0 get a plus sign. Negative numbers always get a minus sign, -0.0 included. Instructions I, F and E may round the number such as to fit the width of the fraction. If rounding a negative number yields zero, the minus sign is retained. When a format-procedure is called from another format-procedure, the former inherits the sign mode from the latter. If the called procedure alters the sign mode, this mode remains effective after return. Instruction $ can be used to restore the previous sign mode.

+

Memorizes the current sign mode, executes instruction ξ and upon completion restores the memorized sign mode.

((fmt "+ F6.2 $(-F6.2) F6.2") 3.4 3.4 3.4) → "◦+3.40◦◦3.40◦+3.40"

6.7 Tabulation

Tabulator instructions reposition the write head within or beyond the end of the current line. The first character of the current line has index 0. Initially the current line starts at the very beginning of the output to be produced. The newline instructions / and | shift the start of the current line to the start of the new line. New lines made in any other way (for example when part of a literal datum) do not reposition the start of the current line. They are considered to be part of the current line. If the new position is beyond the end of the current line, spaces are added, but no existing output is erased. Placing the write head before the end of the current line does not erase output, but allows subsequent output to replace previous output. The instructions are effective even if the output device does not allow reposition of the write head. The tabulator is useful only with fixed width character fonts, such a Courier font.

Tν

Places the write head at position ν of the current line.

>ν

Positions the write head forward relative to the current position.

<ν

Positions the write head backwards relative to the current position. An error is signalled when an attempt is made to position the write head before the start of the current line.

&

Memorizes the position of the start of the current line, executes instruction ξ and upon completion restores the memorized position. Warning: after restoring, new lines produced by ξ become part of the original current line.

((fmt "T10 D T6 D T2 D &R4D") 1 2 3 4) → "◦◦3◦◦◦2◦◦◦1◦◦◦4"

((fmt "*(T#D)") 1 1 4 4 3 3 5 5 2 2 6 6 7 7 0 0) → "01234567"

6.8 Conditional instructions

!ξ

Executes instruction ξ only if there are more data.

?ξ

Executes instruction ξ only if there are no more data.

Qξξ

Inspects the next datum without consuming it. If it is true, the first ξ is executed. If it is false, the second ξ is executed. An error is signalled if there are no more data.

((fmt "!(*(D!X)/)") 1 2 3 4) → "1◦2◦3◦4\n"

((fmt "!(*(D!X)/)")) → ""

((fmt "Q'True','False'S") #t) → "True" ; Instruction S removes #t from the data.

((fmt "*Q(DX)S") 'a #f 'b) → "a◦b◦" ; Displays true data only.

6.9 Iterations

*ξ

Repeated execution of ξ until no data remain.

νξ

Instruction ξ is executed ν times.

((fmt "R3 4D")     1 2 3 4) → "◦◦1◦◦2◦◦3◦◦4"

((fmt "R3 *D")     1 2 3 4) → "◦◦1◦◦2◦◦3◦◦4"

((fmt "R# #D") 3 4 1 2 3 4) → "◦◦1◦◦2◦◦3◦◦4"

6.10 Compound instructions

(ξ ...)

Compound instruction. Useful for conditions and iterations.

[ξ ...]

Special compound instruction. The output of the instructions is gathered in a string which after completion of the compound instruction is added to the remaining data and becomes the first next datum. Each special compound instruction has its own offset for the tabulator. The square brackets are part of the instruction. They do not indicate that ξ... is optional. In fact the ellipsis makes ξ... optional. [] produces an empty string. Warning: new lines produced by ξ... become part of the original current line.

((fmt "!(*(D!X)/)") 1 2 3 4) → "1◦2◦3◦4\n"

((fmt "L3 [*D] C20 D") 1 2 3 4) → "◦◦◦◦◦1◦◦2◦◦3◦◦4◦◦◦◦◦"

((fmt "['123'/'456'] T1 D T0 '0'")) → "0123\n456"

6.11 Miscellaneous instructions

Mξ

Memorizes the current padding mode, field width, tabulator offset and sign mode, executes the instruction and restores the memorized state. Warning: new lines produced by ξ become part of the original current line.

:

Exits from a compound instruction or from a format-procedure or format-string called with instruction K. At top level same as instruction ;.

;

Exits from the top level format-procedure.

S

Skips one datum.

~

Positions the write head at the end of the current line and writes all remaining data separated by spaces and terminated by a newline. Same as "!(&n*(w!x)/)". Usually it is wise to write "x~" or "|~" in order to separate the remaining output from output already produced.

G

Consumes a datum which must be a natural number or #f. It is supposed to be a time measured in seconds from the platform specific starting time. #f is for the current time. The time is displayed as: DDD,◦dd◦MMM◦yyyy◦hh:mm:ss◦±hhmm (exactly 31 characters and ‘◦´ used to show spaces)}) A limit may be imposed on the number of seconds. On many platforms the datum is restricted to a fixnum or even less.

Examples (assuming Windows XP or Windows 7 in time zone +0100)

((fmt "G") 0) → "Thu,◦01◦Jan◦1970◦01:00:00◦+0100"

((fmt "^'0' G")) Same as: ((fmt "G") 0)

((fmt "G") (sub1 (expt 2 31))) → "Tue,◦19◦Jan◦2038◦04:14:07◦+0100"

((fmt "G") #f) Same as: ((fmt "G") (current-seconds))

((fmt "^'#f' G")) Same as: ((fmt "G") #f)

6.12 Unfolding

U

Unfolds the next datum. If the datum is a vector or list, the elements will be treated as separate components of data. These data are preceded by the number of elements. A structure is first converted to a vector and the latter is unfolded. If the datum is not a vector, list or structure it remains in the list of data as it is and the exact number one is consed to the data as the first next datum. Improper lists are not unfolded.

V

Recursively unfolds the next datum. The elements will be treated as separate components of data. These data are preceded by the number of elements.

Z

Recursively unfolds all remaining data. The elements will be treated as separate components of data. These data are preceded by the number of elements.

Y

Consumes a datum, which must be a number. It is decomposed into its real and imaginary part. These are consed as two real numbers to the remaining data, the real part becoming the first next datum, the imaginary part the second one.

%

Consumes a datum, which must be a real number. In Racket all real numbers are rational too. The number is decomposed into its numerator and denominator. These are consed as two exact integer numbers to the remaining data, the numerator becoming the first next datum, the denominator the second one. The sign is associated with the numerator, the denominator always being positive.

Warning: V and Z are not protected against circular structures such as a vector containing itself as an element. This warning does not apply to lists, because improper lists are not unfolded.

((fmt "U#(DX)") '(a b c d)) → "a◦b◦c◦d◦"

((fmt "U*(DX)") '(a b c d)) → "4◦a◦b◦c◦d◦"

((fmt "YF.3+F.2'i'") -12.34+56.78i) → "-12.340+56.78i"

((fmt 'current "*(%R20DN'/'L20D/)") 110/333 -1/3 0.75 -0.75 (/ 1.0 3)) displays:

6.13 Procedure calls

λ

Consumes the next datum, which must be a procedure. The procedure must accept one argument, for which it receives the list of remaining data. It must return a list. This list replaces the list of remaining data. The procedure call is wrapped in a continuation barrier in order to prohibit re-entry by means of a continuation in the body of the procedure. Allowing re-entrance could lead to unexpected results when the called procedure returns a second time after the state of the format-procedure has been altered or the format-procedure already has finished.

K

Consumes the next datum, which must be a format-procedure or a format-string. If a format-string is given, it is checked and translated. If a format-procedure is given, its port is ignored. The instructions are executed as part of the calling format-procedure. The called format-procedure inherits the padding mode, tabulator and sign mode from the caller. If it alters the state, the alterations remain effective after return. Instructions A, @, $ and M can be used to preserve the padding mode, tabulator offset and sign mode.

6.14 Reading from an input port

=

Consumes one datum, which must be an input port. One datum is read from that port. If a datum has successfully been read, #t and the datum are prefixed to the list of remaining data. If an end of file was found, #f is prefixed to the list of remaining data.

J

Consumes one datum, which must be an input port. All data are read from that port starting from its current position up to an end of file mark. The read data are prefixed to the list of remaining data. The prefixed data are preceded by an exact integer number specifying the number of read data. The end of file mark is not included in the data.

(define kopy

(let ((fmt (fmt "JS~" 'port)))

(lambda (p q) (fmt q p))))

(kopy (open-input-string "◦◦Copied◦◦with◦\n◦single◦◦spaces◦◦") 'string)

→ "Copied◦with◦single◦spaces\n"

7 Reuse of format-procedures

When format-procedure c is constructed, format-procedures a and b are inserted. The result is the same as with "*((X'billy'XD)!(X'minny'XD))", but without parsing the inserted parts again. Notice that the compound instruction in the definition of c is distributed over more than one argument. Left parentheses may be balanced by format-string arguments yet to follow.

8 Elaborated examples

8.1 Printing a bill

Procedure print-bill accepts a list of entries, each entry being a list of three arguments: the name of an article, how many pieces of this article are bought and the price per piece. The purpose of the procedure is to display a detailed bill.

(define print-bill

(let

((line "N40('-')/")

(headers "R10'article','number','price pp','total'/")

(data "R10U#(USUS2D2F10.2/)")

; "US" means: unfold and skip element count

(grand-total "R30'grand total'F10.2/"))

(let

((fmt-proc

(fmt "/" line headers line data line grand-total line 'current)))

(lambda (table)

(let*

((totals (map (λ (x) (* (cadr x) (caddr x))) table))

(grand-total (apply + totals)))

(fmt-proc (map list table totals) grand-total))))))

(print-bill '((chair 4 50) (table 1 100) (pillow 4 10)))

→ void, and displays:

8.2 Triangle of Pascal

In this example padding C is used in order to form a triangle of Pascal with its base at the bottom and all other lines centred above the bottom line.

(define binomials

(let

((fmt-row (fmt "R5 D US C4 [*D] C45 D"))

(fmt-table (fmt "/U#(D/)" 'current)))

(define (make-next-row order prev-row)

(list->vector

(cons 1

(let loop ((j 1))

(if (> j order) '(1)

(cons

(+ (vector-ref prev-row (sub1 j)) (vector-ref prev-row j))

(loop (add1 j))))))))

(lambda (n)

(fmt-table

(let loop ((order 0) (row #(1)))

(cons (fmt-row order row)

(if (>= order n)  '()

(loop (add1 order) (make-next-row order row)))))))))

(binomials 9)

→ void, and displays:

9 Synopsis