directory pathname &key test directories flat-file-namestring link-transparency non-existent-link-destinations => pathnames
A pathname, string, or file-stream.
Filtering test (only pathnames matching the test are collected).
A boolean controlling whether non-matching directories are included in the result.
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 UNIX/Linux/Mac OS X. 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 UNIX/Linux/Mac OS X), then symbolic links to nonexistent files do not appear.
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
.
Note: 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.
Note:
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
.
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.
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)
LispWorks User Guide and Reference Manual - 21 Dec 2011