File Output

To write data to a file, you need an output stream, which you obtain by calling **OPEN** with a :direction keyword argument of :output. When opening a file for output, **OPEN** assumes the file shouldn’t already exist and will signal an error if it does. However, you can change that behavior with the :if-exists keyword argument. Passing the value :supersede tells **OPEN** to replace the existing file. Passing :append causes **OPEN** to open the existing file such that new data will be written at the end of the file, while :overwrite returns a stream that will overwrite existing data starting from the beginning of the file. And passing **NIL** will cause **OPEN** to return **NIL** instead of a stream if the file already exists. A typical use of **OPEN** for output looks like this:

(open "/some/file/name.txt" :direction :output :if-exists :supersede)

Common Lisp also provides several functions for writing data: **WRITE-CHAR** writes a single character to the stream. **WRITE-LINE** writes a string followed by a newline, which will be output as the appropriate end-of-line character or characters for the platform. Another function, **WRITE-STRING**, writes a string without adding any end-of-line characters. Two different functions can print just a newline: **TERPRI**--short for “terminate print”—unconditionally prints a newline character, and **FRESH-LINE** prints a newline character unless the stream is at the beginning of a line. **FRESH-LINE** is handy when you want to avoid spurious blank lines in textual output generated by different functions called in sequence. For example, suppose you have one function that generates output that should always be followed by a line break and another that should start on a new line. But assume that if the functions are called one after the other, you don’t want a blank line between the two bits of output. If you use **FRESH-LINE** at the beginning of the second function, its output will always start on a new line, but if it’s called right after the first, it won’t emit an extra line break.

Several functions output Lisp data as s-expressions: **PRINT** prints an s-expression preceded by an end-of-line and followed by a space. **PRIN1** prints just the s-expression. And the function **PPRINT** prints s-expressions like **PRINT** and **PRIN1** but using the “pretty printer,” which tries to print its output in an aesthetically pleasing way.

However, not all objects can be printed in a form that **READ** will understand. The variable ***PRINT-READABLY*** controls what happens if you try to print such an object with **PRINT**, **PRIN1**, or **PPRINT**. When it’s **NIL**, these functions will print the object in a special syntax that’s guaranteed to cause **READ** to signal an error if it tries to read it; otherwise they will signal an error rather than print the object.

Another function, **PRINC**, also prints Lisp objects, but in a way designed for human consumption. For instance, **PRINC** prints strings without quotation marks. You can generate more elaborate text output with the incredibly flexible if somewhat arcane **FORMAT** function. I’ll discuss some of the more important details of **FORMAT**, which essentially defines a mini-language for emitting formatted output, in Chapter 18.

To write binary data to a file, you have to **OPEN** the file with the same :element-type argument as you did to read it: '(unsigned-byte 8). You can then write individual bytes to the stream with **WRITE-BYTE**.

The bulk output function **WRITE-SEQUENCE** accepts both binary and character streams as long as all the elements of the sequence are of an appropriate type for the stream, either characters or bytes. As with **READ-SEQUENCE**, this function is likely to be quite a bit more efficient than writing the elements of the sequence one at a time.