📝Common Lisp: Format

tags

Common Lisp

Directives basics

• All directives start with a tilde (~) and end with a single char identifying the directive.

• Some directives take prefix parameters written immediately after the tilde

  • parameters can be separated with comma

  • if parameter is a number, it is written as is

  • if parameter is a char, it is prefixed with single quote

  • v means parameter should be taken from the next format argument ((format t "~v$" 3 pi) prints 3.142)

  • # evaluates to the number of remaining format arguments

  • first parameters can be omitted, but you need to specify the comma

• : and/or @ modifiers can be placed after parameters to modify the behavior of the directive

  • modifier can be combined

List of directives

~a

“aesthetics.” "Hello" → Hello, :hello → HELLO.

• : — emit nil as () rather than NIL

~s

tries to convert to string that is read‘able

• : — emit nil as () rather than NIL

~%

newline

• first parameter: number of newlines to emit

~&

fresh line (emit a newline if not already at the beginning of a line)

• first parameter: number of newlines to emit (will emit either n - 1 or n newlines)

~~

literal tilde

• first parameter: how many tildes to emit

~$ ~n$

floating point

• 1st parameter: print with up to n (default 2) decimal points

~c

character

• : output non-printing chars as names. e.g., Space

• @ output char in Lisp’s literal syntax. e.g., #\a

• :@ also output additional information how to input the char ^@ (Control @)

  (format nil "~:@c" (code-char 32)) ; may output => "^@ (Control @)"
  

  This combination is not reliable though.

~d

decimal integer

• : add commas between thousands

• @ always print number sign

• 1st parameter: minimum width for the output

• 2nd parameter: padding character to use (default is space)

• 3rd parameter: char to use as a separator for : (default ,)

• 4th parameter: number of digits per group for : (default 3)

~x, ~o, ~b

work like ~d but in hexadecimal, octal, and binary

~r

(radix) same as ~d but allows to specify the base to use as an additional first parameter

• without base, spell out as English words

• no base + : — spell out as an ordinal (xth)

• no base + @ — print out as a Roman numeral

• no base + :@ — old-style Roman numeral (IIII instead of IV)

~f

floating pointer in decimal format but allowed to use computerized scientific notation

• 2nd parameter: number of decimal digits after the decimal point

• @ always print the sign

~e

same as ~f but is required to use computerized scientific notation

~$

(monetary)

• 1st parameter: number of decimal digits after the decimal point (default 2)

• 2nd parameter: minimum number of digits to print before the decimal point (padded with zeros)

• @ always print the sign

~p

(pluralize) emits an s unless the argument is 1

• : use previous argument instead of the current one

  (format nil "~r file~:p" 1)  ; => "one file"
  (format nil "~r file~:p" 10) ; => "ten files"
  (format nil "~r file~:p" 0)  ; => "zero files"
  

• @ emit either y or ies

  (format nil "~r famil~:@p" 1)  ; => "one family"
  (format nil "~r famil~:@p" 10) ; => "ten families"
  (format nil "~r famil~:@p" 0)  ; => "zero families"
  

~( ~)

output in lowercase

• @ — capitalize the first word and make the rest lowercase

• : — capitalize all words

• :@ — make uppercase

(format nil "~(~a~)" "tHe Quick BROWN foX")   ; => "the quick brown fox"
(format nil "~@(~a~)" "tHe Quick BROWN foX")  ; => "The quick brown fox"
(format nil "~:(~a~)" "tHe Quick BROWN foX")  ; => "The Quick Brown Fox"
(format nil "~:@(~a~)" "tHe Quick BROWN foX") ; => "THE QUICK BROWN FOX"

~10t

“tabulation.” Add spaces to move to N-th column.

~[ 0-case ~; 1-case … ~]

(conditional directive) use different format depending on value of the argument

• if the last separator is ~:; it serves as a default value

• : treat boolean as 0/1

• 1st parameter of ~[ can specify the case to select (useful with #)

• @ — the directive can only have one option that is printed if argument is non-nil. Backs up, so that argument can be consumed by the clause

  (format nil "~@[x = ~a ~]~@[y = ~a~]" 10 20)   ; => "x = 10 y = 20"
  (format nil "~@[x = ~a ~]~@[y = ~a~]" 10 nil)  ; => "x = 10 "
  (format nil "~@[x = ~a ~]~@[y = ~a~]" nil 20)  ; => "y = 20"
  (format nil "~@[x = ~a ~]~@[y = ~a~]" nil nil) ; => ""
  

~{ ~}

loop over the list, consuming as many elements as necessary

~^

within the list, stops processing the rest of control string when no elements remain in the list

(format nil "~{~a~^, ~}" (list 1 2 3)) ; => "1, 2, 3"

@ process the remaining format arguments as a list

(format nil "~@{~a~^, ~}" 1 2 3) ; => "1, 2, 3"

~*

move to the next argument

• : — move to the previous argument

• 1st argument:

  • number of argument to move forward or backwards (depending on :)

  • with @ — absolute index of argument to jump to (default to 0)

Backlinks

• 📝 Common Lisp