FMT

FMT is an extensible text formatting facility for Common Lisp. It is meant to do the same things Common Lisp FORMAT function does, but instead of using a control-string for formatting directives, it uses s-expressions.

Invocation

with-fmt

A macro that expands its body to formatting commands.

destination can be:

NIL: formatting is done on a new string that is returned as result
T: formatting is printed to *standard-output*
a stream: formatting is written to the stream

If no destination is given, then *fmt-destination* is the default destination.

Body forms are either some lisp object, like strings, numbers, characters, etc; or some formatting operation. A formatting operation has the form of a list beggining with the operation keyword, like (:aesthetic message), (:join "," list), etc. Forms appearing in body are formatted one after the other.

Example:

(with-fmt ()
   "Hello world"
   #\newline
   (:join "," (list 1 2 3)))

prints:

Hello world
1,2,3

fmt

This macro is almost exactly to with-fmt, but with a different syntax, with makes it look very similar to Common Lisp format function.

Example:

(fmt nil "Hello" \#space "world")
(fmt t (:s (list 1 2 3)))

fmt*

Both fmt and with-fmt are macros and compile formatting directives to code that writes on the destination stream at compile-time. fmt* is a function, and interprets the formatting clauses given to it at run-time. This can be useful if you need a function to pass around, or you need extra flexibility in the formatting spec form.

Example:

(fmt* nil "Hello" #\space "world")
(fmt* nil (if t `(:d ,22) `(:f ,23.44)))

Note that some control flow operations (like :do and :if are not available in interpreted mode).

Printer operations

Aesthetic (:a, :aesthetic)

The aesthetic operation is the equivalent of Common Lisp FORMAT's ~A directive.

Example:

(fmt nil (:a (list :foo :bar :baz)))

returns "(FOO BAR BAZ)"

Standard (:s, :std, :standard)

The standard operation is the equivalent of Common Lisp FORMAT's ~S directive.

Example:

(fmt nil (:s (list :foo :bar :baz)))

returns "(:FOO :BAR :BAZ)"

Special operations

Escaping (:esc and :fmt)

Use the :esc directive for disabling formatting in a particular place.

For instance:

(fmt nil "Hello" #\space (:esc "beautiful" #\space) "world")

returns "hello world"

It's important to note that the code inside :esc is not removed completly, it is executed, but its result is not formatted. You can see that in the macroexpansion of the above code:

(WITH-FMT-DESTINATION (#:STREAM925 NIL)
  (MACROLET ((:FMT (&REST CLAUSES)
            `(FMT ,'#:STREAM925 ,@CLAUSES)))
  (WRITE-STRING "Hello" #:STREAM925)
  (WRITE-CHAR #\  #:STREAM925)
  (PROGN "beautiful" #\ )
  (WRITE-STRING "world" #:STREAM925)))

This is useful in combination with the :fmt directive, that reenables formatting inside escaped forms:

(fmt nil 
     (:a "start")
 #\newline
 (:esc 
   (loop for x in (list 1 2 3)
   do (:fmt (:s x))))
 #\newline
 (:a "end"))

In the above example the output of the loop is not formatted as it is enclosed in an :esc; but the :fmt operation inside the loops makes sure each of the elements of the list is formatted.

Control flow operations

Conditional (:when and :if)

Conditional control flow can be controlled via :when and :if operations.

:when is the simplest of the two and executes its body when the condition given is true.

Syntax:

(:when condition &body body)

Example:

(let ((cond t))
    (fmt nil (:when cond "yes"))) ;=> "yes"

(let ((cond nil))
 (fmt nil (:when cond "yes"))) ;=> ""

:if has an else branch.

Syntax:

(:if condition &body body)

The else branch is indicated with the :else keyword.

Example:

(let ((list (list 1 2 3)))
  (fmt nil (:if (not list)
                 "none"
         :else
         (:join "," list)))) ;=> "1,2,3"

 (let ((list (list)))
   (fmt nil (:if (not list)
          "none"
          :else
          (:join "," list)))) ;=> "none"

Note: :if is not implemented in interpreter mode, so it cannot be used in fmt* function.

Iteration (:do)

To iterate a list formatting its elements, there's the :do operation.

Syntax:

(:do (var list) &body body)

Example:

(fmt nil (:do (item (list 1 2 3))
              (:s item))) ;=> "123"

Note: :do is not implemented in interpreter mode, so it cannot be used in fmt* function.

Repetition (:times)

Repeat formatting N number of times

Syntax:

(:times clause n)

Example:

(fmt nil (:times #\newline 5))

More complex control flow

Just use lisp with :esc and :fmt for more complex control flow.

Example:

(let ((list (list 1 2 3)))
  (fmt nil (:esc (if (not list)
                   (:fmt "No elements")
                   (loop for x in (butlast list)
                         do (:fmt (:a x) "; ")
                         finally (:fmt (:a (car (last list)))))))))

Other operations

Join (:join)

Joins the elements of its list argument using a separator.

Syntax:

(:join separator list &optional format)

separator can be either be a character or a string. list is of course the list of elements to join. format, if present, is a command for formatting the list elements. If it is not present :s is used. _ is bound to the list element.

Example:

(fmt nil (:join ", " (list "foo" "bar" "baz"))) ;=> "foo, bar, baz"
(fmt nil (:join #\, (list "foo" "bar"))) ;=> "foo,bar"
(fmt nil (:join (", " " and ")
             (list "foo" "bar" "baz"))) ;=> "foo, bar and baz"
(fmt nil (:join ", " (list "a" "b" "c") (:a _ :up))) ;=> "A, B, C"

Common Lisp format (:format)

It is possible to just invoke Common Lisp format function to write on the current destination.

Syntax:

(:format control-string &rest args)

Example:

(let ((list (list "foo" "bar" "baz")))
 (fmt nil (:format "~{~A~^, ~}" list))) ;=> "foo, bar, baz"

(let ((list (list :foo :bar :baz)))
 (fmt nil (:format "~{~S~^, ~}" list))) ;=> ":FOO, :BAR, :BAZ"

Filters

Filters are particular operations or functions that modify the input before it gets formatted.

aesthetic and standard operations support filters.

Filters appear at the end of the :a or :s operations:

(:a arg &rest filters)
(:s arg &rest filters)

Filters can be either a function reference or some previously defined filter.

Example:

(fmt nil (:a "foo" :upcase)) ;=> "FOO"
(fmt nil (:s "foo" #'string-upcase)) ;=> "FOO"
(fmt nil (:a "  foo  " (:trim #\ ) :up)) ;=> "FOO"

Some very common filters are :upcase or :up, :downcase or :down, :trim, etc

Radix control

Radix (:r, :radix)

Prints argument in radix. Equivalent to Common Lisp FORMAT's ~R

Syntax:

(:r n &optional (interpretation :cardinal))

interpretation can be :cardinal, :ordinal, :roman and :old-roman.

Examples:

(fmt nil (:r 4)) ;=> "four"
(fmt nil (:r 4 :cardinal)) ;=> "four"
(fmt nil (:r 4 :ordinal)) ;=> "fourth"
(fmt nil (:r 4 2)) ;=> "100"
(fmt nil (:r 4 :roman)) ;=> "IV"
(fmt nil (:r 4 :old-roman)) ;=> "IIII"

Extending FMT

Custom formatting operations definition

Custom formatting operations can be defined via define-format-operation macro.

It has the following syntax:

(define-format-operation operation-name
   (:keywords keyword-list)
   (:format (destination clause)
         &body body)
   (:compile (destination clause)
         &body body)
   (:documentation docstring))

Where:

keyword-list is a list of keywords with which the formatting operation can be invoked.
format is the function that is run at run-time for formatting with fmt* function. destination is the current formatting destination, and clause is the whole format clause.
compile is the code transformation triggered at compile-time by fmt and with-fmt macros. It is expected to return a piece of code.
documentation is the operation description string.

For example, we can define a time formatting operation

(define-format-operation time
    (:keywords (:time))
    (:format (destination clause)
     (destructuring-bind (_ timestamp &optional (format local-time:+iso-8601-format+)) clause
         (declare (ignore _))
         (let ((local-time (etypecase timestamp
                 (integer
                  (local-time:universal-to-timestamp timestamp))
                 (local-time:timestamp
                  timestamp))))
           (local-time:format-timestring destination 
                         local-time
                         :format format))))
    (:compile (destination clause)
      (destructuring-bind (_ timestamp &optional (format 'local-time:+iso-8601-format+)) clause
          (declare (ignore _))
          (alexandria:with-unique-names (local-time)
            (alexandria:once-only (timestamp)
            `(let ((,local-time (etypecase ,timestamp
                      (integer
                       (local-time:universal-to-timestamp ,timestamp))
                      (local-time:timestamp
                       ,timestamp))))
           (local-time:format-timestring ,destination 
                         ,local-time
                         :format ,format))))))
    (:documentation "Time formatting"))

And then we can use the new operation like this:

(fmt* nil `(:time ,(get-universal-time)))

That goes through the operation's :format code.

(fmt nil (:time (get-universal-time)))

Which transforms code using the operation's :compile code.

Custom filters definition

Filters are defined via define-format-filter macro, very similarly to format operations.

Syntax:

(define-format-filter filter-name
   (:keywords keyword-list)
   (:apply (arg)
         &body body)
   (:compile (arg)
         &body body)
   (:documentation docstring))

Where:

keyword-list is a list of keywords with which the filter can be applied.
apply is the function that is run at run-time for formatting with fmt* function. arg is the argument to which apply the filter.
compile is the code transformation triggered at compile-time by fmt and with-fmt macros. It is expected to return a piece of code.
documentation is the operation description string.

For example, the :trim filter is defined like this:

(define-format-filter trim
   (:keywords (:trim))
   (:apply (arg &rest chars)
       (string-trim (or chars (list #\ )) arg))
   (:compile (arg &rest chars)
     (let ((chars-bag (or chars (list #\ ))))
       `(string-trim ',chars-bag ,arg)))
   (:documentation "String trim filter"))

Filters can be used in :a and :s operations afterwards:

(fmt nil (:a "  hello  " :trim)) ;=> "hello"
(fmt nil (:a "//hello" (:trim #\/))) ;=> "hello"

mmontone/fmt

FMT

Invocation

with-fmt

fmt

fmt*

Printer operations

Aesthetic (:a, :aesthetic)

Standard (:s, :std, :standard)

Special operations

Escaping (:esc and :fmt)

Control flow operations

Conditional (:when and :if)

Iteration (:do)

Repetition (:times)

More complex control flow

Other operations

Join (:join)

Common Lisp format (:format)

Filters

Radix control

Radix (:r, :radix)

Extending FMT

Custom formatting operations definition

Custom filters definition