type: function (subr) location: built-in source file: xlfio.c Common LISP compatible: similar supported on: all machines
(format <destination> <format> [ <expr1> ... ] ) <destination> - a required destination - must be a file pointer, a stream, NIL (to create a string) or T (to print to *standard-output*) <format> - a format string <exprN> - an expression
The FORMAT function prints the specified expressions (if any) to the specified <destination> using the <format> string to control the print format. If the <destination> is NIL, a string is created and returned with the contents of the FORMAT. If the <destination> is T, the printing occurs to *STANDARD-OUTPUT*. FORMAT returns a NIL, if the <destination> was non-NIL. The <format> string is a string (surrounded by double-quote characters). This string contains ASCII text to be printed along with formatting directives (identified by a preceeding tilde ~ character). The character following the tilde character is not case sensitive (~a and ~A will function equivalently).
(format T "Now is the time for") ; prints Now is the time for (format T "all ~A ~S to" 'good 'men) ; prints all GOOD MEN to (format T "come to the") ; prints come to the (format T "~A of their ~S" ; prints aid of their "party" "aid" "party") ; (format *standard-ouput* "Hello there") ; prints Hello there (format nil "ho ho ~S" 'ho) ; returns "ho ho HO" (format T "this is ~%a break") ; prints this is ; a break (format T "this is a long ~ string") ; prints this is a long string
SUPPORTED FORMAT DIRECTIVES: The <format> string in XLISP supports the following format directives:
directive name action ---------------------------------------------------------------- ~A ASCII Print the <expr>. If it is a string print it without quotes. This is like the PRINC function. ~S S-EXPR Print the <expr>. If it is a string print it with quotes. This is like the PRIN1 function. ~% NEW-LINE Print a new line. ~~ TILDE Print a single tilde ~ character. ~<new-line> CONTINUE Continue the <format> string on the next line. This signals a line break in the format. The FORMAT will ignore all white-space (blanks, tabs, newlines). This is useful when the <format> string is longer than a program line. Note that the new-line character must immediately follow the tilde character.
COMMON LISP COMPATIBILITY: The FORMAT function in Common LISP is quite impressive. It includes 26 different formatting directives. XLISP, as shown above, does not include most of these. The more difficult ones that you might encounter are the Decimal, Octal, heXidecimal, Fixed-format floating-point and Exponential floating-point. It is possible to print in octal and hexadecimal notation by setting *INTEGER-FORMAT*. It is possible to print in fixed format and exponential by setting *FLOAT-FORMAT*. However, neither of these system variables are supported in Common LISP and neither gives control over field size.