SLIB/Common Lisp format for Racket

8.16.0.4

SLIB/Common Lisp format for Racket🔗ℹ

A port of SLIB format 3.1 to Racket. Original code by Dirk Lutzebaeck and Aubrey Jaffer.

SLIB documentation. A few portions have been excerpted below.

1 Format Interface🔗ℹ

procedure
(format destination format-string arg ...)
→ (or/c boolean? string?)
  destination : (or/c output-port? boolean? string? number?)
  format-string : (or/c string? any/c)
  arg : any/c

An almost complete implementation of Common LISP format description according to the CL reference book Common LISP from Guy L. Steele, Digital Press. Backward compatible to most of the available Scheme format implementations.

Returns #t, #f or a string; has side effect of printing according to format-string. If destination is #t, the output is to the current output port and #t is returned. If destination is #f, a formatted string is returned as the result of the call. NEW: If destination is a string, destination is regarded as the format string; format-string is then the first argument and the output is returned as a string. If destination is a number, the output is to the current error port if available by the implementation. Otherwise destination must be an output port and #t is returned.

format-string must be a string. In case of a formatting error format returns #f and prints a message on the current output or error port. Characters are output as if the string were output by the display function with the exception of those prefixed by a tilde (~). For a detailed description of the format-string syntax please consult a Common LISP format reference manual. For a test suite to verify this format implementation (require slib/formatst).

Racket-specific notes:

The pretty print format ~Y uses the standard Racket pretty-print routine, not the version included in SLIB.

The original code fails a few included test cases because it doesn’t preserve the output column between calls that return a string. This version does so and passes all test cases. This affects the behavior of things like ~& across calls.

1.1 Extra functions🔗ℹ

There are also a few functions that are equivalents to the standard Racket formatted output functions, allowing this module to serve as a drop-in replacement in code that uses them:

procedure
(printf format-string arg ...) → void?
format-string : string?
arg : any/c

Always prints to the current output port.

procedure
(eprintf format-string arg ...) → void?
format-string : string?
arg : any/c

Always prints to the current error port.

procedure
(fprintf port format-string arg ...) → void?
  port : output-port?
  format-string : string?
  arg : any/c

Prints to the given output port.

2 Configuration Variables🔗ℹ

What are simple variables in the SLIB version are parameters in this one.

parameter
(format:symbol-case-conv) → (or/c (-> string? string?) #f)
(format:symbol-case-conv converter) → void?
converter : (or/c (-> string? string?) #f)
= #f

Symbols are converted by symbol->string so the case type of the printed symbols is implementation dependent. format:symbol-case-conv is a one arg closure which is either #f (no conversion), string-upcase, string-downcase or string-titlecase.

parameter
(format:iobj-case-conv) → (or/c (-> string? string?) #f)
(format:iobj-case-conv converter) → void?
converter : (or/c (-> string? string?) #f)
= #f

As format:symbol-case-conv but applies for the representation of implementation internal objects.

parameter
(format:expch) → char?
(format:expch ch) → void?
ch : char?
= #\E

The character prefixing the exponent value in ~E printing.

parameter
(format:iteration-bounded) → boolean?
(format:iteration-bounded bounded?) → void?
bounded? : any/c
= #t

When #t, a ~{...~} control will iterate no more than the number of times specified by format:max-iterations regardless of the number of iterations implied by modifiers and arguments. When #f, a ~{...~} control will iterate the number of times implied by modifiers and arguments, unless termination is forced by language or system limitations.

parameter
(format:max-iterations) → exact-nonnegative-integer?
(format:max-iterations iterations) → void?
iterations : exact-nonnegative-integer?
= 100

The maximum number of iterations performed by a ~{...~} control. Has effect only when format:iteration-bounded is #t.

2.1 Racket-specific configuration🔗ℹ

parameter
(format:char-style) → (or/c 'ascii 'racket 'lisp)
(format:char-style style) → void?
style : (or/c 'ascii 'racket 'lisp)
= 'racket

As originally written, format uses ASCII abbreviations and caret notation for rendering control character literals, so that, say, (format "~@C" #\tab) returns "#\\ht", and prints characters with a value greater than 127 in a variable-digit-count octal notation (I believe the code assumes that characters are single bytes). These character literals cannot be read back with Racket’s read.

When this parameter is set to 'racket (The default), it will instead use forms that the Racket reader understands for ~@C, and Unicode symbols or U+XXXX forms for unprintable characters for ~:C.

The 'lisp value is the same as 'racket for ~@C, but uses Common Lisp style names for control characters and semi-standard non-printing characters in ~:C, based on Clozure’s implementation.

Examples:

> (parameterize ([format:char-style 'racket])
    (list (format #f "~@C ~@C ~@C ~@C" #\backspace #\ÿ #\u2028 #\newline)
          (format #f "foo~:Cbar~:Cbaz~:C~:C" #\space #\tab #\u2028 #\newline)))
'("#\\backspace #\\ÿ #\\u2028 #\\newline" "foo␣bar␉bazU+2028␊")
> (parameterize ([format:char-style 'lisp])
    (list (format #f "~@C ~@C ~@C ~@C" #\backspace #\ÿ #\u2028 #\newline)
          (format #f "foo ~:C bar ~:C baz ~:C ~:C" #\space #\tab #\u2028 #\newline)))
'("#\\backspace #\\ÿ #\\u2028 #\\newline" "foo Space bar Tab baz U+2028 Newline")
> (parameterize ([format:char-style 'ascii])
    (list (format #f "~@C ~@C ~@C ~@C" #\backspace #\ÿ #\u2028 #\newline)
          (format #f "foo~:Cbar~:Cbaz~:C~:C" #\space #\tab #\u2028 #\newline)))
'("#\\bs #\\377 #\\20050 #\\newline" "foo bar^Ibaz#\\20050^J")