The cl-fad Reference Manual

This is the cl-fad Reference Manual, version 0.7.6, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 15:10:48 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 cl-fad

Portable pathname library

License

BSD-2-Clause

Version

0.7.6

Dependencies
  • sb-posix (system).
  • bordeaux-threads (system).
  • alexandria (system).
Source

cl-fad.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 cl-fad/cl-fad.asd

Source

cl-fad.asd.

Parent Component

cl-fad (system).

ASDF Systems

cl-fad.


3.1.2 cl-fad/packages.lisp

Source

cl-fad.asd.

Parent Component

cl-fad (system).

Packages

3.1.3 cl-fad/fad.lisp

Dependency

packages.lisp (file).

Source

cl-fad.asd.

Parent Component

cl-fad (system).

Public Interface
Internals

3.1.4 cl-fad/path.lisp

Dependency

fad.lisp (file).

Source

cl-fad.asd.

Parent Component

cl-fad (system).

Public Interface
Internals

defalias (macro).


3.1.5 cl-fad/temporary-files.lisp

Dependencies
Source

cl-fad.asd.

Parent Component

cl-fad (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 path

Rexporting certain functions from the cl-fad package with shorter names.

This package provides no functionality, it serves only to make file system intensive code easier to read (for unix people at least).

Source

packages.lisp.

Public Interface

4.2 cl-fad

Source

packages.lisp.

Nickname

fad

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *default-template*
Package

cl-fad.

Source

temporary-files.lisp.


5.1.2 Macros

Macro: with-open-temporary-file ((stream &rest args &key keep &allow-other-keys) &body body)

Create a temporary file using OPEN-TEMPORARY with ARGS and run BODY with STREAM bound to the temporary file stream. Returns the values returned by BODY. By default, the file is deleted when BODY is exited. If a true value is passed in KEEP, the file is not deleted when the body is exited. See OPEN-TEMPORARY for more permitted options.

Package

cl-fad.

Source

temporary-files.lisp.

Macro: with-output-to-temporary-file ((stream &rest args) &body body)

Create a temporary file using OPEN-TEMPORARY with ARGS and run BODY with STREAM bound to the temporary file stream. Returns the pathname of the file that has been created. See OPEN-TEMPORARY for permitted options.

Package

cl-fad.

Source

temporary-files.lisp.


5.1.3 Compiler macros

Compiler Macro: -d (&rest args)
Package

path.

Source

path.lisp.

Compiler Macro: -e (&rest args)
Package

path.

Source

path.lisp.

Compiler Macro: = (&rest args)
Package

path.

Source

path.lisp.

Compiler Macro: absolute-p (&rest args)
Package

path.

Source

path.lisp.

Compiler Macro: catdir (&rest args)
Package

path.

Source

path.lisp.

Compiler Macro: catfile (&rest args)
Package

path.

Source

path.lisp.

Compiler Macro: dirname (&rest args)
Package

path.

Source

path.lisp.

Compiler Macro: relative-p (&rest args)
Package

path.

Source

path.lisp.

Compiler Macro: rm-r (&rest args)
Package

path.

Source

path.lisp.

Compiler Macro: root-p (&rest args)
Package

path.

Source

path.lisp.


5.1.4 Ordinary functions

Function: -d (directory)
Package

path.

Source

path.lisp.

Function: -e (pathname)
Package

path.

Source

path.lisp.

Function: = (a b)
Package

path.

Source

path.lisp.

Function: absolute-p (pathname)
Package

path.

Source

path.lisp.

Function: basename (pathname)
Package

path.

Source

path.lisp.

Function: canonical-pathname (pathname)

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 :BACK elements from the path (not :UP elements). Since some lisps, ccl/sbcl/clisp convert ".." in pathnames to :UP, and
not :BACK, the actual utility of the function is limited.

Package

cl-fad.

Source

fad.lisp.

Function: catdir (&rest pathnames)
Package

path.

Source

path.lisp.

Function: catfile (&rest pathnames)
Package

path.

Source

path.lisp.

Function: copy-file (from to &key overwrite)

Copies the file designated by the non-wild pathname designator FROM to the file designated by the non-wild pathname designator TO. If OVERWRITE is true overwrites the file designated by TO if it exists.

Package

cl-fad.

Source

fad.lisp.

Function: copy-stream (from to &optional checkp)

Copies into TO (a stream) from FROM (also a stream) until the end of FROM is reached, in blocks of *stream-buffer-size*. The streams should have the same element type. If CHECKP is true, the streams are checked for compatibility of their types.

Package

cl-fad.

Source

fad.lisp.

Function: delete-directory-and-files (dirname &key if-does-not-exist)

Recursively deletes all files and directories within the directory designated by the non-wild pathname designator DIRNAME including DIRNAME itself. IF-DOES-NOT-EXIST must be one of :ERROR or :IGNORE where :ERROR means that an error will be signaled if the directory DIRNAME does not exist.

NOTE: this function is dangerous if the directory that you are removing contains symlinks to files outside of it - the target files might be removed instead! This is currently fixed for SBCL and CCL.

Package

cl-fad.

Source

fad.lisp.

Function: directory-exists-p (pathspec)

Checks whether the file named by the pathname designator PATHSPEC exists and if it is a directory. Returns its truename if this is the case, NIL otherwise. The truename is returned in directory form as if by PATHNAME-AS-DIRECTORY.

Package

cl-fad.

Source

fad.lisp.

Function: directory-pathname-p (pathspec)

Returns NIL if PATHSPEC (a pathname designator) does not designate a directory, PATHSPEC otherwise. It is irrelevant whether file or directory designated by PATHSPEC does actually exist.

Package

cl-fad.

Source

fad.lisp.

Function: dirname (pathname)
Package

path.

Source

path.lisp.

Function: file-exists-p (pathspec)

Checks whether the file named by the pathname designator PATHSPEC exists and returns its truename if this is the case, NIL otherwise. The truename is returned in ‘canonical’ form, i.e. the truename of a directory is returned as if by PATHNAME-AS-DIRECTORY.

Package

cl-fad.

Source

fad.lisp.

Function: list-directory (dirname &key follow-symlinks)

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 - see PATHNAME-AS-DIRECTORY.

If FOLLOW-SYMLINKS is true, 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-SYMLINKS is NIL, it should return the actual directory contents, which might include symlinks. Currently this works on SBCL and CCL.

Package

cl-fad.

Source

fad.lisp.

Function: merge-pathnames-as-directory (&rest pathnames)

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 PATHNAMES in order. For this reason an absolute pathname will,
effectively, cancel the affect 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 PATHNAMES are 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/"

Package

cl-fad.

Source

fad.lisp.

Function: merge-pathnames-as-file (&rest pathnames)

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
PATHNAMES (host, version and device). The returned values’s name, type
and version are taken from the last element of PATHNAMES. The
intervening elements are used only for their pathname-directory
values.

Examples:

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

Package

cl-fad.

Source

fad.lisp.

Function: open-temporary (&rest open-arguments &key template generate-random-string max-tries direction &allow-other-keys)

Create a file with a randomly generated name and return the opened stream. The resulting pathname is generated from TEMPLATE, which is a string representing a pathname template. A percent sign (%) in that string is replaced by a randomly generated string to make the filename unique. The default for TEMPLATE places temporary files in the TEMPORARY-FILES logical pathname host, which is automatically set up in a system specific manner. The file name generated from TEMPLATE is merged with *DEFAULT-PATHNAME-DEFAULTS*, so random pathnames relative to that directory can be generated by not specifying a directory in TEMPLATE.

GENERATE-RANDOM-STRING can be passed to override the default function that generates the random name component. It should return a random string consisting of characters that are permitted in a pathname (logical or physical, depending on TEMPLATE).

The name of the temporary file can be accessed calling the PATHNAME function on STREAM. For convenience, the temporary file is opened on the physical pathname, i.e. if the TEMPLATE designate a logical pathname the translation to a physical pathname is performed before opening the stream.

In order to create a unique file name, OPEN-TEMPORARY may loop internally up to MAX-TRIES times before giving up and signalling a CANNOT-CREATE-TEMPORARY-FILE condition.

Package

cl-fad.

Source

temporary-files.lisp.

Function: pathname-absolute-p (a)

Returns true if A is an absolute pathname.

This simply tests if A’s directory list starts with :ABSOLUTE

Package

cl-fad.

Source

fad.lisp.

Function: pathname-as-directory (pathspec)

Converts the non-wild pathname designator PATHSPEC to directory form.

Package

cl-fad.

Source

fad.lisp.

Function: pathname-as-file (pathspec)

Converts the non-wild pathname designator PATHSPEC to file form.

Package

cl-fad.

Source

fad.lisp.

Function: pathname-directory-pathname (pathname)

Returns a complete pathname representing the directory of PATHNAME. If PATHNAME is already a directory pathname (name NIL, type NIL) returns a pathname equal (as per pathname=) to it.

Package

cl-fad.

Source

fad.lisp.

Function: pathname-equal (a b)

Returns T if A and B represent 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 both A and B to probe-file one can make this function test for file ’sameness’.

Equality is defined as:

- strings that are string equal
- symbol (including nil) or keywords which are eql
- 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
A and B then A and B are 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.

Package

cl-fad.

Source

fad.lisp.

Function: pathname-parent-directory (pathname)

Returns a pathname which would, by name at least, contain PATHNAME as 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 contains PATHNAME.

The root directory, #P"/", is its own parent. The parent directory of a filename is the parent of the filename’s dirname.

Package

cl-fad.

Source

fad.lisp.

Function: pathname-relative-p (a)

Returns true if A is a relative pathname.

This simply tests if A’s directory starts with :RELATIVE.

Package

cl-fad.

Source

fad.lisp.

Function: pathname-root-p (a)
Package

cl-fad.

Source

fad.lisp.

Function: relative-p (pathname)
Package

path.

Source

path.lisp.

Function: rm-r (pathname)
Package

path.

Source

path.lisp.

Function: root-p (pathname)
Package

path.

Source

path.lisp.

Function: walk-directory (dirname fn &key directories if-does-not-exist test follow-symlinks)

Recursively applies the function FN to all files within the directory named by the non-wild pathname designator DIRNAME and all of its sub-directories. FN will only be applied to files for which the function TEST returns a true value. If DIRECTORIES is not NIL, FN and TEST are applied to directories as well. If DIRECTORIES
is :DEPTH-FIRST, FN will be applied to the directory’s contents first. If DIRECTORIES is :BREADTH-FIRST and TEST returns NIL, the directory’s content will be skipped. IF-DOES-NOT-EXIST must be one of :ERROR or :IGNORE where :ERROR means that an error will be signaled if the directory DIRNAME does not exist. If FOLLOW-SYMLINKS is T, 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. See LIST-DIRECTORY.

Package

cl-fad.

Source

fad.lisp.


5.1.5 Conditions

Condition: cannot-create-temporary-file
Package

cl-fad.

Source

temporary-files.lisp.

Direct superclasses

error.

Direct slots
Slot: template
Initargs

:template

Slot: max-tries
Initargs

:max-tries

Condition: invalid-temporary-pathname-template
Package

cl-fad.

Source

temporary-files.lisp.

Direct superclasses

error.

Direct slots
Slot: string
Package

common-lisp.

Initargs

:string


5.2 Internals


5.2.1 Special variables

Special Variable: *create-file-name-lock*
Package

cl-fad.

Source

temporary-files.lisp.

Special Variable: *hyperdoc-base-uri*
Package

cl-fad.

Source

fad.lisp.

Special Variable: *max-tries*
Package

cl-fad.

Source

temporary-files.lisp.

Special Variable: *name-random-state*
Package

cl-fad.

Source

temporary-files.lisp.

Special Variable: *stream-buffer-size*
Package

cl-fad.

Source

fad.lisp.


5.2.2 Macros

Macro: defalias (name args realname)
Package

cl-fad.

Source

path.lisp.

Macro: with-component-testers ((a b key) &body body)
Package

cl-fad.

Source

fad.lisp.

Macro: with-file-name-lock-held (() &body body)
Package

cl-fad.

Source

temporary-files.lisp.


5.2.3 Ordinary functions

Function: component-present-p (value)

Helper function for DIRECTORY-PATHNAME-P which checks whether VALUE is neither NIL nor the keyword :UNSPECIFIC.

Package

cl-fad.

Source

fad.lisp.

Function: directory-from-environment (environment-variable-name)
Package

cl-fad.

Source

temporary-files.lisp.

Function: directory-wildcard (dirname)

Returns a wild pathname designator that designates all files within the directory named by the non-wild pathname designator DIRNAME.

Package

cl-fad.

Source

fad.lisp.

Function: generate-random-pathname (template random-string-generator)
Package

cl-fad.

Source

temporary-files.lisp.

Function: generate-random-string ()
Package

cl-fad.

Source

temporary-files.lisp.

Function: get-default-temporary-directory ()
Package

cl-fad.

Source

temporary-files.lisp.

Function: getenv (x)

Query the libc runtime environment. See getenv(3).

Package

cl-fad.

Source

temporary-files.lisp.

Function: hyperdoc-lookup (symbol type)
Package

cl-fad.

Source

fad.lisp.

Function: pathname-device-equal (a b)
Package

cl-fad.

Source

fad.lisp.

Function: pathname-directory-equal (a b)
Package

cl-fad.

Source

fad.lisp.

Function: pathname-host-equal (a b)
Package

cl-fad.

Source

fad.lisp.

Function: pathname-name-equal (a b)
Package

cl-fad.

Source

fad.lisp.

Function: pathname-type-equal (a b)
Package

cl-fad.

Source

fad.lisp.

Function: pathname-version-equal (a b)
Package

cl-fad.

Source

fad.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   -   =  
A   B   C   D   F   G   H   L   M   O   P   R   W  
Index Entry  Section

-
-d: Public compiler macros
-d: Public ordinary functions
-e: Public compiler macros
-e: Public ordinary functions

=
=: Public compiler macros
=: Public ordinary functions

A
absolute-p: Public compiler macros
absolute-p: Public ordinary functions

B
basename: Public ordinary functions

C
canonical-pathname: Public ordinary functions
catdir: Public compiler macros
catdir: Public ordinary functions
catfile: Public compiler macros
catfile: Public ordinary functions
Compiler Macro, -d: Public compiler macros
Compiler Macro, -e: Public compiler macros
Compiler Macro, =: Public compiler macros
Compiler Macro, absolute-p: Public compiler macros
Compiler Macro, catdir: Public compiler macros
Compiler Macro, catfile: Public compiler macros
Compiler Macro, dirname: Public compiler macros
Compiler Macro, relative-p: Public compiler macros
Compiler Macro, rm-r: Public compiler macros
Compiler Macro, root-p: Public compiler macros
component-present-p: Private ordinary functions
copy-file: Public ordinary functions
copy-stream: Public ordinary functions

D
defalias: Private macros
delete-directory-and-files: Public ordinary functions
directory-exists-p: Public ordinary functions
directory-from-environment: Private ordinary functions
directory-pathname-p: Public ordinary functions
directory-wildcard: Private ordinary functions
dirname: Public compiler macros
dirname: Public ordinary functions

F
file-exists-p: Public ordinary functions
Function, -d: Public ordinary functions
Function, -e: Public ordinary functions
Function, =: Public ordinary functions
Function, absolute-p: Public ordinary functions
Function, basename: Public ordinary functions
Function, canonical-pathname: Public ordinary functions
Function, catdir: Public ordinary functions
Function, catfile: Public ordinary functions
Function, component-present-p: Private ordinary functions
Function, copy-file: Public ordinary functions
Function, copy-stream: Public ordinary functions
Function, delete-directory-and-files: Public ordinary functions
Function, directory-exists-p: Public ordinary functions
Function, directory-from-environment: Private ordinary functions
Function, directory-pathname-p: Public ordinary functions
Function, directory-wildcard: Private ordinary functions
Function, dirname: Public ordinary functions
Function, file-exists-p: Public ordinary functions
Function, generate-random-pathname: Private ordinary functions
Function, generate-random-string: Private ordinary functions
Function, get-default-temporary-directory: Private ordinary functions
Function, getenv: Private ordinary functions
Function, hyperdoc-lookup: Private ordinary functions
Function, list-directory: Public ordinary functions
Function, merge-pathnames-as-directory: Public ordinary functions
Function, merge-pathnames-as-file: Public ordinary functions
Function, open-temporary: Public ordinary functions
Function, pathname-absolute-p: Public ordinary functions
Function, pathname-as-directory: Public ordinary functions
Function, pathname-as-file: Public ordinary functions
Function, pathname-device-equal: Private ordinary functions
Function, pathname-directory-equal: Private ordinary functions
Function, pathname-directory-pathname: Public ordinary functions
Function, pathname-equal: Public ordinary functions
Function, pathname-host-equal: Private ordinary functions
Function, pathname-name-equal: Private ordinary functions
Function, pathname-parent-directory: Public ordinary functions
Function, pathname-relative-p: Public ordinary functions
Function, pathname-root-p: Public ordinary functions
Function, pathname-type-equal: Private ordinary functions
Function, pathname-version-equal: Private ordinary functions
Function, relative-p: Public ordinary functions
Function, rm-r: Public ordinary functions
Function, root-p: Public ordinary functions
Function, walk-directory: Public ordinary functions

G
generate-random-pathname: Private ordinary functions
generate-random-string: Private ordinary functions
get-default-temporary-directory: Private ordinary functions
getenv: Private ordinary functions

H
hyperdoc-lookup: Private ordinary functions

L
list-directory: Public ordinary functions

M
Macro, defalias: Private macros
Macro, with-component-testers: Private macros
Macro, with-file-name-lock-held: Private macros
Macro, with-open-temporary-file: Public macros
Macro, with-output-to-temporary-file: Public macros
merge-pathnames-as-directory: Public ordinary functions
merge-pathnames-as-file: Public ordinary functions

O
open-temporary: Public ordinary functions

P
pathname-absolute-p: Public ordinary functions
pathname-as-directory: Public ordinary functions
pathname-as-file: Public ordinary functions
pathname-device-equal: Private ordinary functions
pathname-directory-equal: Private ordinary functions
pathname-directory-pathname: Public ordinary functions
pathname-equal: Public ordinary functions
pathname-host-equal: Private ordinary functions
pathname-name-equal: Private ordinary functions
pathname-parent-directory: Public ordinary functions
pathname-relative-p: Public ordinary functions
pathname-root-p: Public ordinary functions
pathname-type-equal: Private ordinary functions
pathname-version-equal: Private ordinary functions

R
relative-p: Public compiler macros
relative-p: Public ordinary functions
rm-r: Public compiler macros
rm-r: Public ordinary functions
root-p: Public compiler macros
root-p: Public ordinary functions

W
walk-directory: Public ordinary functions
with-component-testers: Private macros
with-file-name-lock-held: Private macros
with-open-temporary-file: Public macros
with-output-to-temporary-file: Public macros