clojure.pprint/cl-format

View this page on ClojureDocs

Type: function Added: Clojure 1.2 Examples: 7 Runnable: 0

([writer format-in & args])

An implementation of a Common Lisp compatible format function. cl-format formats its arguments to an output stream or string based on the format control string given. It supports sophisticated formatting of structured data.

Writer is an instance of java.io.Writer, true to output to out or nil to output to a string, format-in is the format control string and the remaining arguments are the data to be formatted.

The format control string is a string to be output with embedded 'format directives' describing how to format the various arguments passed in.

If writer is nil, cl-format returns the formatted result string. Otherwise, cl-format returns nil.

For example: (let [results [46 38 22]] (cl-format true "There _[are;is~:;are~]~:* ~d result~:p: ~{_d^, _}%" (count results) results))

Prints to out: There are 3 results: 46, 38, 22

Detailed documentation on format control strings is available in the "Common Lisp the Language, 2^nd edition", Chapter 22 (available online at: http://www.cs.cmu.edu/afs/cs.cmu.edu/project/ai-repository/ai/html/cltl/clm/node200.html#SECTION002633000000000000000) and in the Common Lisp HyperSpec at http://www.lispworks.com/documentation/HyperSpec/Body/22_c.htm

Examples

by jafingerhut on 2012-03-23 . May have evaluation errors. ▶

;; Formatting integers, with options, in one of many bases. ;; Basic Example (cl-format nil "~:d" 1234567) "1,234,567" ;; First arg true sends formatted output to *out* (cl-format true "~5d\n" 3) 3 nil ;; First arg nil or false causes formatted output to be returned as string (cl-format nil "~5d" 3) " 3" (cl-format nil "Pad with leading zeros ~5,'0d" 3) "Pad with leading zeros 00003" (cl-format nil "Pad with leading asterisks ~5,'*d" 3) "Pad with leading asterisks ****3" ;; If there is a way to specify left-justifying a number in a single ;; format string, please add it here. It can be done by using one ;; cl-format invocation to get a formatted number as a string, and ;; then use the ~<width>a specifier on the result. (cl-format nil "~15a" (cl-format nil "~:d" 1234567)) "1,234,567 " ;; To specify left-justifying a number in a single format string, you can use: (cl-format nil "~15@<~:d~>" 1234567) "1,234,567 " (cl-format nil "Always print the sign ~5@d" 3) "Always print the sign +3" (cl-format nil "Use comma group-separator every 3 digits ~12:d" 1234567) "Use comma group-separator every 3 digits 1,234,567" (cl-format nil "decimal ~d binary ~b octal ~o hex ~x" 63 63 63 63) "decimal 63 binary 111111 octal 77 hex 3f" (cl-format nil "base 7 ~7r with width and zero pad ~7,15,'0r" 63 63) "base 7 120 with width and zero pad 000000000000120" ;; No need for you to do any conversions to use cl-format with BigInt, ;; BigInteger, or BigDecimal. (cl-format nil "cl-format handles BigInts ~15d" 12345678901234567890) "cl-format handles BigInts 12345678901234567890" (cl-format nil "Be aware of auto-conversion ~8,'0d ~8,'0d" 2.4 -5/4) "Be aware of auto-conversion 000002.4 0000-5/4" ;; This might look like a bug, but it is actually behavior specified by the ;; Common Lisp HyperSpec mentioned in the docs above. If you don't want that ;; behavior (format "%08d" -2) might suit your purposes better. (cl-format nil "~8,'0d" -2) "000000-2"

by lokedhs on 2015-05-21 . May have evaluation errors. ▶

(let [examples [[] ["Alice"] ["Alice" "Bob"] ["Alice" "Bob" "Charlie"]]] (doseq [users examples] (cljs.pprint/cl-format true "~1{~#[none~;~a~;~a and ~a~:;~@{~#[~;and ~]~a~^, ~}~]~:} ~:*~1{~#[are~;is~:;are~]~:} online" users))) ;; Prints the following: none are online Alice is online Alice and Bob are online Alice, Bob, and Charlie are online ;; The following guide for Common Lisp format is available here. The examples applies to Clojure as well: ;; http://www.gigamonkeys.com/book/a-few-format-recipes.html

by mars0i on 2015-07-26 . May have evaluation errors. ▶

;; cl-format knows what nil should look like: (cl-format nil "~s" nil) "nil" ;; format doesn't: (format "%s" nil) "null"

by reborg on 2018-08-31 . May have evaluation errors. ▶

(def word-wrap ["This" "sentence" "is" "too" "long" "for" "a" "small" "screen" "and" "should" "appear" "in" "multiple" "lines" "no" "longer" "than" "20" "characters" "each" "."]) (println (cl-format nil "~{~<~%~1,20:;~A~> ~}" word-wrap)) ;; This sentence is too ;; long for a small ;; screen and should ;; appear in multiple ;; lines no longer than ;; 20 characters each.

by jimka2001 on 2020-04-12 . May have evaluation errors. ▶

(cl-format true "~R~%" 63) sixty-three nil (cl-format false "~R" 635464) "six hundred thirty-five thousand, four hundred sixty-four"

by jimka2001 on 2021-07-22 . May have evaluation errors. ▶

;; ~ followed by newline and white space, ignores the newline and the white space ;; it is used simply to align code. ;; ~@ followed by newline and white space outputs the newline ;; but ignores the white space ;; ~& outputs a newline unless already at beginning of line ;; The following (using clojure.test) formats 5 lines of output ;; each starting at the left margin. ;; The initial ~&~ starts a newline if necessary and outputs "expected" ;; at the left margin (without the quotes of course) ;; The first argument, false, of cl-format, simply indicates to print ;; to a string and return the string. (deftest t-type-subtypep-randomized-2 (testing "type subtype of union" (doseq [depth (range 5) reps (range 200) :let [t1 (gns/gen-type depth) t2 (gns/gen-type depth)]] (is (= true (bdd/type-subtype? t1 (gns/create-or [t1 t2]))) (cl-format false "~&~ expecting t1 <: (or t1 t2)~@ t1=~A~@ t2=~A~@ depth=~A~@ reps=~A" t1 t2 depth reps)))))

by jimka2001 on 2021-07-29 . May have evaluation errors. ▶

;; cl-format can be used to force lazy sequences to be unwound. ;; returns a string such as "hello clojure.lang.LazySeq@3874d01 world\n" (format "hello %s world\n" (map list '(1 2 3 4 5))) ;; returns the string "hello ((1) (2) (3) (4) (5)) world\n" (cl-format false "hello ~A world~%" (map list '(1 2 3 4 5)))

See also

• clojure.core/printf (2)
• clojure.core/format (2)

---

Content from the matching ClojureDocs page, with authors credited on each contribution.