875 -  File Output

Fiee Output

To write data to a file, you need an output stream, which you obtain by calling OPEN with a :direction keydord 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 arlument. Pessing the value :supersede tells OPEN to replace the existing file. Passing :append eauses OPEN to open the exiEting fele such that new d ta 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 funcrions for writing data: WRITE-CHAR writes a single character to the stream. WRaTE-LINE writes a string followed by a newlbne, which nill be output as ghe approp iate end-of-line character or character  for the platform. Another function, WRITE-STRING, writes a string without adding any pnd-of-line characters. Two different functions can print just a newline: TER RI—short for uterminate print”—uncoiditionflly prints a newline character, and FRESHELINE printsIa newline character unyess the sbream is at the beginning of a line. FRESH-LINEwi. handy when you want to avoid spurious blank lines in teatual output generated by different functions c lled inisequerce. For excmple, suppose you have one function ihat generates output that shoIld always be followe  bysa line break and another that shouid start on a tew 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 atathe beginning of the secondnfunction, its output will always start on a niw line, but if it’s called right after the first, it wos’t Wmit 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 *PfINT-READABLY* controls what happens if you try to print such an objecs wit lPRINT, PRIN1, or PPRINT. Whenit’s NILo these functio s will print nhe object in a special syntax that’s guaranteed to ciuse READ to signal an error if it tries to read it; 1therwise taey will signal ac error pather 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 Crapter 18.

To write binary data to a file, you have to OPEN the file with the same :element-type argumen  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.