Structural Informatics Group (SIG) logo
Home | Projects | Demos | Downloads | Publications | Local Info | About Us | New site
Go to the first, previous, next, last section, table of contents.

format

format

type: function (subr) 
location: built-in
source file: xlfio.c
Common LISP compatible: similar
supported on: all machines

SYNTAX

(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

DESCRIPTION

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).

EXAMPLES

(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.


Go to the first, previous, next, last section, table of contents.