Skip to main content

ensure-directories-exist

ensure-directories-exist Function

Syntax:

ensure-directories-exist pathspec &key verbose → pathspec, created

Arguments and Values:

pathspec—a pathname designator .

verbose—a generalized boolean.

created—a generalized boolean.

Description:

Tests whether the directories containing the specified file actually exist, and attempts to create them if they do not.

If the containing directories do not exist and if verbose is true, then the implementation is permitted (but not required) to perform output to standard output saying what directories were created. If the containing directories exist, or if verbose is false, this function performs no output.

The primary value is the given pathspec so that this operation can be straightforwardly composed with other file manipulation expressions. The secondary value, created, is true if any directories were created.

Affected By:

The host computer’s file system.

Exceptional Situations:

An error of type file-error is signaled if the host, device, or directory part of pathspec is wild.

If the directory creation attempt is not successful, an error of type file-error is signaled; if this occurs, it might be the case that none, some, or all of the requested creations have actually occurred within the file system.

See Also:

probe-file, open, Section 19.1.2 (Pathnames as Filenames)

Expanded Reference: ensure-directories-exist​

Creating directories for a file path​

ensure-directories-exist creates any missing directories in the path. It returns two values: the original pathspec and a boolean indicating whether directories were actually created.

(ensure-directories-exist "/tmp/cl-test-ede/sub/dir/file.txt")
;; => #P"/tmp/cl-test-ede/sub/dir/file.txt"
;; => T

Directories already exist​

If all directories in the path already exist, the second value is nil.

(ensure-directories-exist "/tmp/file.txt")
;; => #P"/tmp/file.txt"
;; => NIL

Composing with file operations​

Because ensure-directories-exist returns the pathspec as its primary value, it can be composed directly with file operations.

(with-open-file (s (ensure-directories-exist
                     "/tmp/cl-test-ede2/output/data.txt")
                   :direction :output
                   :if-exists :supersede)
  (write-string "data" s))
=> "data"

Using the :verbose keyword​

When :verbose is true, the implementation may print information about which directories were created.

(ensure-directories-exist "/tmp/cl-test-ede3/a/b/c/file.txt"
                          :verbose t)
;; May print information about directory creation
;; => #P"/tmp/cl-test-ede3/a/b/c/file.txt"
;; => T