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

pathname

A pathname, string, or file-stream.

test

Filtering test (only pathnames matching the test are collected).

directories

A boolean controlling whether non-matching directories are included in the result.

flat-file-namestring

A generalized boolean.

link-transparency

If nil, then symbolic links are not followed. This means that returned names are not necessarily truenames, but has the useful feature that the pathname-directory of each pathname returned is the directory supplied as argument.

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.

non-existent-link-destinations

If this 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.

Values

pathnames

A list of physical pathnames.

Description

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.

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.

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

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.

Example

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 the directories argument:

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

fast-directory-files
truename