The Common Lisp Cookbook - Files and Directories

Note: In this chapter, we use mainly namestrings to specify filenames. The issue of pathnames will be the topic of separate chapter REAL SOON NOW.

Content

Testing whether a File Exists

Use the function PROBE-FILE which will return a generalized boolean - either NIL if the file doesn't exists, or its truename (which might be different from the argument you supplied).
edi@bird:/tmp> ln -s /etc/passwd foo
edi@bird:/tmp> cmucl
; Loading #p"/home/edi/.cmucl-init".
CMU Common Lisp 18d-pre, level-1 built 2002-01-15 on maftia1, running on bird
Send questions to cmucl-help@cons.org. and bug reports to cmucl-imp@cons.org.
Loaded subsystems:
    Python native code compiler, target Intel x86
    CLOS based on PCL version:  September 16 92 PCL (f)
    Gray Streams Protocol Support
    CLX X Library MIT R5.02
* (probe-file "/etc/passwd")

#p"/etc/passwd"
* (probe-file "foo")

#p"/etc/passwd"
* (probe-file "bar")

NIL

Opening a File

Common Lisp has OPEN and CLOSE functions which resemble the functions of the same denominator from other programming languages you're probably familiar with. However, it is almost always recommendable to use the macro WITH-OPEN-FILE instead. Not only will this macro open the file for you and close it when you're done, it'll also take care of it if your code leaves the body abnormally (such as by a use of THROW). A typical use of WITH-OPEN-FILE looks like this:
(with-open-file (str <file-spec>
                     :direction <direction>
                     :if-exists <if-exists>
                     :if-does-not-exist <if-does-not-exist>)
  <your code here>)
Note that there are a lot more options to WITH-OPEN-FILE. See the CLHS entry for OPEN for all the details. You'll find some examples on how to use WITH-OPEN-FILE below. Also note that you usually don't need to provide any keyword arguments if you just want to open an existing file for reading.

Using Strings instead of Files

Reading a File one Line at a Time

READ-LINE will read one line from a stream (which defaults to standard input) the end of which is determined by either a newline character or the end of the file. It will return this line as a string without the trailing newline character. (Note that READ-LINE has a second return value which is true if there was no trailing newline, i.e. if the line was terminated by the end of the file.) READ-LINE will by default signal an error if the end of the file is reached. You can inhibit this by supplying NIL as the second argument. If you do this, READ-LINE will return NIL if it reaches the end of the file.
* (with-open-file (stream "/etc/passwd")
    (do ((line (read-line stream nil)
               (read-line stream nil)))
        ((null line))
      (print line)))
You can also supply a third argument which will be used instead of NIL to signal the end of the file:
* (with-open-file (stream "/etc/passwd")
    (loop for line = (read-line stream nil 'foo)
          until (eq line 'foo)
          do (print line)))

Reading a File one Character at a Time

READ-CHAR is similar to READ-LINE, but it only reads one character as opposed to one line. Of course, newline characters aren't treated differently from other characters by this function.
* (with-open-file (stream "/etc/passwd")
    (do ((char (read-char stream nil)
               (read-char stream nil)))
        ((null char))
      (print char)))

Looking one Character ahead

You can 'look at' the next character of a stream without actually removing it from there - this is what the function PEEK-CHAR is for. It can be used for three different purposes depending on its first (optional) argument (the second one being the stream it reads from): If the first argument is NIL, PEEK-CHAR will just return the next character that's waiting on the stream:
* (with-input-from-string (stream "I'm not amused")
    (print (read-char stream))
    (print (peek-char nil stream))
    (print (read-char stream))
    (values))

#\I 
#\' 
#\'
If the first argument is T, PEEK-CHAR will skip whitespace characters, i.e. it will return the next non-whitespace character that's waiting on the stream. The whitespace characters will vanish from the stream as if they had been read by READ-CHAR:
* (with-input-from-string (stream "I'm 
                                   not amused")
    (print (read-char stream))
    (print (read-char stream))
    (print (read-char stream))
    (print (peek-char t stream))
    (print (read-char stream))
    (print (read-char stream))
    (values))
#\I 
#\' 
#\m 
#\n 
#\n 
#\o
If the first argument to PEEK-CHAR is a character, the function will skip all characters until that particular character is found:
* (with-input-from-string (stream "I'm not amused")
    (print (read-char stream))
    (print (peek-char #\a stream))
    (print (read-char stream))
    (print (read-char stream))
    (values))
#\I 
#\a 
#\a 
#\m 
Note that PEEK-CHAR has further optional arguments to control its behaviour on end-of-file similar to those for READ-LINE and READ-CHAR (and it will signal an error by default):
* (with-input-from-string (stream "I'm not amused")
    (print (read-char stream))
    (print (peek-char #\d stream))
    (print (read-char stream))
    (print (peek-char nil stream nil 'the-end))
    (values))
#\I 
#\d 
#\d 
THE-END
You can also put one character back onto the stream with the function UNREAD-CHAR. You can use it as if, after you have read a character, you decide that you'd better used PEEK-CHAR instead of READ-CHAR:
* (with-input-from-string (stream "I'm not amused")
    (let ((c (read-char stream)))
      (print c)
      (unread-char c stream)
      (print (read-char stream))
      (values)))
#\I 
#\I
Note that the front of a stream doesn't behave like a stack: You can only put back exactly one character onto the stream. Also, you must put back the same character that has been read previously, and you can't unread a character if none has been read before.

Random Access to a File

Use the function FILE-POSITION for random access to a file. If this function is used with one argument (a stream), it will return the current position within the stream. If it's used with two arguments (see below), it will actually change the file position in the stream.
* (with-input-from-string (stream "I'm not amused")
    (print (file-position stream))
    (print (read-char stream))
    (print (file-position stream))
    (file-position stream 4)
    (print (file-position stream))
    (print (read-char stream))
    (print (file-position stream))
    (values))
0 
#\I 
1 
4
#\n 
5

Copyright © 2002-2007 The Common Lisp Cookbook Project
http://cl-cookbook.sourceforge.net/

$Header: /cvsroot/cl-cookbook/cl-cookbook/files.html,v 1.7 2007/01/16 20:58:32 ozten Exp $