directory Function

Summary

Determines which files on the system have names matching a given pathname.

Package

common-lisp

Signature

directory pathname &key test directories flat-file-namestring link-transparency non-existent-link-destinations => pathnames

Arguments

Values

Description

The function directory collects all the pathnames matching the given pathname.

directory returns truenames, conforming to the ANSI specification for Common Lisp. Some programs may depend on the old behavior, however (and directory is slower if it has to find the truename for every file in the directory), and so two keyword arguments are available so that the old behavior can still be used: link-transparency and non-existent-link-destinations.

Because truenames are now returned, the entries . and .. no longer show up in the output of directory. This means, for instance, that:

(directory #P"/usr/users/") 

does not include #P"/usr", which is the truename of #P"/usr/users/..".

The specification is unclear as to the appropriate behavior of directory in the presence of links to non-existent files or directories. For example, if the directory contains foo, which is a symbolic link to bar, and there is no file named bar, should bar show up in the directory listing? A keyword argument has been added which lets you control this behavior.

directory returns a single pathname if called with a non-wild (fully-specified) pathname. LispWorks truenames are fully-specified, so this affects recursive calls to directory.

If test is non-nil, then it is called with each pathname and only pathnames when it returns true are collected.

directories, if non-nil, causes paths of directories that are sub-directories of the directory of the argument pathname to be included in the result, even if they do not match pathname in the name, type or version components. The default value of directories is nil.

When flat-file-namestring is non-nil, directory matches the file-namestring of pathname as a flat string, rather than a pathname name and pathname type. The default value of flat-file-namestring is nil.

If link-transparency is t, then symbolic links in the result are resolved. If link-transparency is nil, then symbolic links are not resolved, but they are still followed in the pathname-directory of pathname. This means that returned names are not necessarily truenames, but has the useful feature that the pathname-directory of each pathname returned matches the directory of pathname. The default value of link-transparency is given by the special variable *directory-link-transparency*, which has initial value t on non-Windows platforms. By setting this variable to nil, you can get the old behavior of directory. On Windows, where the file system does not normally support symbolic links, this variable is initially nil.

If non-existent-link-destinations is non-nil, then the pathname pointed to by a symbolic link appears in the output whether or not this file actually exists. If link-transparency is non-nil and non-existent-link-destinations is nil (this is the default on non-Windows platforms), then symbolic links to nonexistent files do not appear. The default value is nil.

Notes

1. The Search files tool in the LispWorks IDE uses this option when the Match flat file-namestring option is selected. See the LispWorks IDE User Guide for more information about the Search Files tool.
2. File names containing the character * cannot be handled by LispWorks. This is because LispWorks uses * as a wildcard, so there can be confusion if a file name containing * is created, for example in the value of pathnames returned by directory.
3. The function fast-directory-files can be used for faster operations when operating on directories with large number of files.

Compatibility notes

In LispWorks 8.0 and newer, if the file-namestring of pathname is a symbolic link pointing to a directory and link-transparency is nil, then directory returns it as a file. In previous versions of LispWorks, it was returned as a directory. Calling file-directory-p on such a link still returns true, so if you neeed to check if it is a directory or not, then you need to check first. The simplest way is to check that file-namestring returns nil. In LispWorks 8.0, there is also function file-link-p that may be useful in this situation.

The :check-for-subs argument, implemented in LispWorks 4.0.1 and previous versions, has been removed. This argument controlled whether directories in the result have null name components. This option is no longer valid since ANSI Common Lisp specifies that directory returns truenames.

Examples

CL-USER 1 > (pprint (directory "."))
 
(#P"C:/Program Files/LispWorks/readme-6-1.txt"
 #P"C:/Program Files/LispWorks/lispworks-6-1-0-x86-win32.exe"
 #P"C:/Program Files/LispWorks/license-6-1.txt"
 #P"C:/Program Files/LispWorks/lib/")

This session illustrates the effect of directories:

CL-USER 5 > (pprint (directory "/tmp/t*"))
 
(#P"/tmp/test.lisp" #P"/tmp/test2/" #P"/tmp/test1/")
 
CL-USER 6 > (pprint (directory "/tmp/t*" :directories t))
 
(#P"/tmp/patches/"
 #P"/tmp/test.lisp"
 #P"/tmp/test2/"
 #P"/tmp/opengl/"
 #P"/tmp/test1/"
 #P"/tmp/mnt/")

This example illustrates directory returning a single pathname in its result when given a full-specified pathname:

CL-USER 1 > (directory 
             (make-pathname :host "H" 
                            :device :unspecific 
                            :directory (list :absolute 
                                             "tmp") 
                            :name :unspecific 
                            :type :unspecific 
                            :version :unspecific))
(#P"H:/tmp/")

The next two examples illustrate the effect of flat-file-namestring. Suppose the directory dir contains files interp.exe and file.lisp.

This call matches interp.exe, where the name interp ends with p, but does not match file.lisp, where the name file ends with e:

(directory "dir/*p")

The next call matches file.lisp, where the namestring file.lisp ends with p, but does not match interp.exe, where the namestring interp.exe ends with e:

(directory "dir/*p" :flat-file-namestring t)

See also

directory in the Common Lisp HyperSpec
fast-directory-files
truename