Abstract
CL-FAD (for "Files and Directories") is a thin layer atop Common Lisp's standard pathname functions. It is intended to provide some unification between current CL implementations on Windows, OS X, Linux, and Unix. Most of the code was written by Peter Seibel for his book Practical Common Lisp.CL-FAD comes with a BSD-style license so you can basically do with it whatever you want.
Download shortcut: http://weitz.de/files/cl-fad.tar.gz.
open-temporary [function]
with-output-to-temporary-file [macro]
with-open-temporary-file [macro]
*default-template* [variable]
cannot-create-temporary-file [condition]
invalid-temporary-pathname-template [condition]
missing-temp-environment-variable [condition]
temporary-files [logical pathname host]
path [package]
CL-FAD comes with simple system definitions for MK:DEFSYSTEM and asdf so you can either adapt it
to your needs or just unpack the archive and from within the CL-FAD
directory start your Lisp image and evaluate the form
(mk:compile-system "cl-fad") - or (asdf:oos 'asdf:load-op :cl-fad) for asdf - which should compile and load the whole
system.
Installation via asdf-install should as well
be possible. Plus, there are ports
for Gentoo Linux thanks to Matthew Kennedy
and for Debian Linux thanks to René van Bevern.
If for some reason you can't or don't want to use MK:DEFSYSTEM or asdf you
can just LOAD the file load.lisp.
The latest version of the source code lives in the github repository edicl/cl-fad.
If you want to send patches,
please read this first.
Please submit your changes
as GitHub pull
request".
The following Common Lisp implementations are currently supported:
[Function]
directory-exists-p pathspec => generalized-boolean
Checks whether the file named by the pathname designatorpathspecexists and if it is a directory. Returns its truename if this is the case,NILotherwise. The truename is returned in directory form as if byPATHNAME-AS-DIRECTORY.
[Function]
directory-pathname-p pathspec => generalized-boolean
ReturnsNILifpathspec(a pathname designator) does not designate a directory,pathspecotherwise. It is irrelevant whether the file or directory designated bypathspecdoes actually exist.
[Function]
file-exists-p pathspec => generalized-boolean
Checks whether the file named by the pathname designatorpathspecexists and returns its truename if this is the case,NILotherwise. The truename is returned in "canonical" form, i.e. the truename of a directory is returned in directory form as if byPATHNAME-AS-DIRECTORY.
[Function]
pathname-absolute-p a => result
Returns true if
ais an absolute pathname. This simply tests ifa's directory list starts with:ABSOLUTE
[Function]
pathname-equal a b => result
Returns true if
aandbrepresent the same pathname. This function does not access the filesystem, it only looks at the components of the two pathnames to test if they are the same (though by passing bothaandbto probe-file one can make this function test for file 'sameness'.Equality is defined as:
- strings that are
string=- symbols (including
niland keywords) which areeql- lists of the same length with equal (as per these rules) elements.
If any of these tree conditions is false for any of the components in
aandbthenaandbare different, otherwise they are the same.NB: This function does not convert name strings to pathnames. So "foo.txt" and #P"foo.txt" are different pathnames.
[Function]
pathname-relative-p a => result
Returns true if
ais a relative pathname. This simply tests ifa's directory starts with:RELATIVE.
[Function]
pathname-root-p a => result
Returns true if
pathnameis the root directory (in other words, a directory which is its own parent).
[Function]
canonical-pathname pathname => result
Remove redundant information from PATHNAME.
This simply walks down
PATHNAME's pathname-directory and drops "." directories, removes :back and its preceding element.NB: This function does not access the filesystem, it only looks at the values in the pathname and works on their known (or assumed) meanings.
NB: Since this function does not access the filesystem it will only remove
:BACKelements from the path (not:UPelements). Since some lisps, ccl/sbcl/clisp convert ".." in pathnames to:UP, and not:BACK, the actual utility of the function is limited.
[Function]
merge-pathnames-as-directory &rest pathnames => result
Given a list of (probably relative) pathnames, this returns a single directory pathname containing the logical concatenation of them all.
The returned value is the current directory if one were to cd into each of
pathnamesin order. For this reason an absolute pathname will, effectively, cancel the effect of any previous relative pathnames.The returned value's defaults are taken from the first element of
pathnames(host, version and device).NB: Since this function only looks at directory names the name and type of the elements of
pathnamesare ignored. Make sure to properly use either trailing #\/s, or pathname-as-directory, to get the expected results.Examples:
(merge-pathnames-as-directory #P"foo/" #P"bar/") == #P"foo/bar/" (merge-pathnames-as-directory #P"foo/" #P"./bar/") == #P"foo/./bar/" (merge-pathnames-as-directory #P"foo/" #P"/bar/") == #P"/bar/" (merge-pathnames-as-directory #P"foo/" #P"/bar/" #P'quux/file.txt) == #P"/bar/quux/"
[Function]
merge-pathnames-as-file &rest pathnames => result
Given a list of, probably relative, pathnames returns a single filename pathname containing the logical concatenation of them all.
The returned value's defaults are taken from the first element of
Examples:pathnames(host, version and device). The returned values's name, type and version are taken from the last element ofpathnames. The intervening elements are used only for their pathname-directory values.(merge-pathnames-as-file #P"foo/" #P"bar.txt") == #P"foo/bar.txt" (merge-pathnames-as-file #P"foo/" #P"./bar.txt") == #P"foo/./bar.txt" (merge-pathnames-as-file #P"foo/" #P"/bar/README") == #P"/bar/README" (merge-pathnames-as-file #P"/foo/" #P"/bar/" #P'quux/file.txt) == #P"/bar/quux/file.txt"
[Function]
pathname-as-directory pathspec => pathname
Converts the non-wild pathname designatorpathspecto directory form, i.e. it returns a pathname which would return a true value if fed toDIRECTORY-PATHNAME-P.
[Function]
pathname-as-file pathspec => pathname
Converts the non-wild pathname designatorpathspecto file form, i.e. it returns a pathname which would return aNILvalue if fed toDIRECTORY-PATHNAME-P.
[Function]
pathname-directory-pathname pathname => result
Returns a complete pathname representing the directory of
pathname. Ifpathnameis already a directory pathname (namenil,typenil) returns a pathname equal (as per pathname-equal) to it.
[Function]
pathname-parent-directory pathname => result
Returns a pathname which would, by name at least, contain
pathnameas one of its direct children. Symlinks can make the parent/child relationship a like opaque, but generally speaking the value returned by this function is a directory name which containspathname.The root directory, #P"/", is its own parent. The parent directory of a filename is the parent of the filename's dirname.
[Function]
list-directory dirname &key follow-symlinks => list
Returns a fresh list of pathnames corresponding to all files within the directory named by the non-wild pathname designator
dirname. The pathnames of sub-directories are returned in directory form - seePATHNAME-AS-DIRECTORY.If
follow-symlinksis true (which is the default), then the returned list contains truenames (symlinks will be resolved) which essentially means that it might also return files from outside the directory. This works on all platforms.When
follow-symlinksisNIL, it should return the actual directory contents, which might include symlinks. (This is currently implemented only on SBCL and CCL.)
[Function]
walk-directory dirname fn &key directories if-does-not-exist test follow-symlinks => |
Recursively applies the function designated by the function designator
fnto all files within the directory named by the non-wild pathname designatordirnameand all of its sub-directories.fnwill only be applied to files for which the functiontestreturns a true value. (The default value fortestalways returns true.) Ifdirectoriesis notNIL,fnandtestare applied to directories as well. Ifdirectoriesis:DEPTH-FIRST,fnwill be applied to the directory's contents first. Ifdirectoriesis:BREADTH-FIRSTandtestreturnsNIL, the directory's content will be skipped.if-does-not-existmust be one of:ERRORor:IGNOREwhere:ERROR(the default) means that an error will be signaled if the directorydirnamedoes not exist.If
follow-symlinksis true (which is the default), then your callback will receive truenames. Otherwise you should get the actual directory contents, which might include symlinks. This might not be supported on all platforms. SeeLIST-DIRECTORY.
Create a temporary file and return its name:
CL-USER> (temporary-file:with-output-to-temporary-file (foo)
(print "hello" foo))
#P"/var/folders/Yu/YuNMNBNPGoqs9G-1Wmj1dk+++TI/-Tmp-/temp-yjck024x"
Create a temporary file, read and write it, have it be deleted automatically:
CL-USER> (temporary-file:with-open-temporary-file (foo :direction :io)
(print "hello" foo)
(file-position foo 0)
(read foo))
"hello"
The Lisp application can set the default directory in which
temporary files are created by the way of the
temporary-files logical pathname host:
(setf (logical-pathname-translations "temporary-files") '(("*.*.*" "/var/tmp/")))
This would set the directory for temporary files to
/var/tmp/. For more information about logical
pathnames, please refer to Common
Lisp the Language, 2nd Edition and the Common Lisp
HyperSpec.
Physical path names have restrictions regarding the permitted character in file names. If these restrictions conflict with your desired naming scheme, you can pass a physical pathname as TEMPLATE parameter to the temporary file generation function.
Here are a few examples:
CL-USER> (logical-pathname-translations "temporary-files")
(("*.*.*" #P"/var/folders/Yu/YuNMNBNPGoqs9G-1Wmj1dk+++TI/-Tmp-/"))
CL-USER> (temporary-file:with-open-temporary-file (foo)
(pathname foo))
#P"/var/folders/Yu/YuNMNBNPGoqs9G-1Wmj1dk+++TI/-Tmp-/temp-6rdqdkd1"
This used the temporary directory established in the TMPDIR
environment variable, by the way of the definition of the
temporary-files logical host definition.
CL-USER> (temporary-file:with-open-temporary-file (foo :template "/tmp/file.with.dots.in.name.%.txt")
(pathname foo))
#P"/tmp/file.with.dots.in.name.2EF04KUJ.txt"
Here, a physical pathname was used for the
:template keyword argument so that a
filename containing multiple dots could be generated.
CL-USER> (temporary-file:with-open-temporary-file (foo :template "temporary-files:blah-%.txt")
(pathname foo))
#P"/var/folders/Yu/YuNMNBNPGoqs9G-1Wmj1dk+++TI/-Tmp-/blah-72mj450d.txt"
This used the temporary-files logical pathname host, but changed
the filename slightly.
CL-USER> *default-pathname-defaults*
#P"/Users/hans/"
CL-USER> (temporary-file:with-open-temporary-file (foo :template "blah-%.txt")
(pathname foo))
#P"/Users/hans/blah-5OEJELG2.txt"
Here, a relative pathname was used in the template, which
caused the file to be generated in the directory established
by *default-pathname-defaults*.
Alternatively, the *default-template*
special variable can be set to define a custom default template
for generating names.