The filesystem-utils Reference Manual

This is the filesystem-utils Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sat Dec 03 21:26:56 2022 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 filesystem-utils

A collection of utilities for filesystem interaction.

Maintainer

Nicolas Hafner <>

Author

Nicolas Hafner <>

Home Page

https://Shinmera.github.io/filesystem-utils/

Source Control

(GIT https://github.com/Shinmera/filesystem-utils.git)

Bug Tracker

https://github.com/Shinmera/filesystem-utils/issues

License

zlib

Version

1.0.0

Dependencies
  • trivial-features (system).
  • pathname-utils (system).
  • documentation-utils (system).
  • sb-posix (system)., for feature :sbcl
Source

filesystem-utils.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 filesystem-utils/filesystem-utils.asd

Source

filesystem-utils.asd.

Parent Component

filesystem-utils (system).

ASDF Systems

filesystem-utils.


3.1.2 filesystem-utils/package.lisp

Source

filesystem-utils.asd.

Parent Component

filesystem-utils (system).

Packages

org.shirakumo.filesystem-utils.


3.1.3 filesystem-utils/toolkit.lisp

Dependency

package.lisp (file).

Source

filesystem-utils.asd.

Parent Component

filesystem-utils (system).

Public Interface
Internals

3.1.4 filesystem-utils/documentation.lisp

Dependency

toolkit.lisp (file).

Source

filesystem-utils.asd.

Parent Component

filesystem-utils (system).


4 Packages

Packages are listed by definition order.


4.1 org.shirakumo.filesystem-utils

Source

package.lisp.

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 Macros

Macro: with-current-directory ((directory) &body body)

Execute body while the current working directory is changed.

This guarantees the following invariant: the value of CURRENT-DIRECTORY is the same before entering BODY as it is after BODY exits for any reason. the value of CURRENT-DIRECTORY is equivalent to the passed DIRECTORY when BODY begins execution.

See CURRENT-DIRECTORY

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Macro: with-temporary-file ((path &rest args) &body body)

Execute BODY with a temporary file pathname bound to PATH.

ARGS are passed on to MAKE-TEMPORARY-FILE.
The file is automatically deleted when BODY exits for any reason.

See MAKE-TEMPORARY-FILE
See ENSURE-DELETED

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.


5.1.2 Ordinary functions

Function: copy-file (file to &key replace skip-root)

Copies the file from FILE to TO.

REPLACE may be one of:
- NIL Never replaces the destination, and instead skips it. - T Always replaces the destination.
- :IF-NEWER Only replaces the destination if the source has a more recent FILE-WRITE-DATE.

When FILE is a directory, all children are copied to the target. If SKIP-ROOT is NIL, then the directory-name of FILE is replicated as the root of all contents within TO. Otherwise, the contents of FILE are copied directly to TO.

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Attempts to create a symbolic link file at LINK-FILE, pointing to DESTINATION-FILE.

This may signal an error for a variety of reasons:
- The filesystem does not support symbolic links
- The implementation does not support creating symbolic links
- The implementation is not permitted to create symbolic links
- The target filesystem cannot be pointed to

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: current-directory ()

Accesses the "current working directory".

Note that setting this directory is not multithreading safe, as the directory is global to the process.

See WITH-CURRENT-DIRECTORY

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: (setf current-directory) ()
Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: directory* (directory &rest args &key &allow-other-keys)

Lists files matching the wild DIRECTORY pathname.

Like CL:DIRECTORY, but tries *not* to resolve any symlinks of the listing, returning direct descendants of the directory root.

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: directory-p (file)

Returns T if the given pathname points to a directory.

This differs from PATHNAME-UTILS:DIRECTORY-P in the following way: If the pathname is not a directory pathname and instead points to a file, but the file is actually a directory file, this function still returns T.

See PATHNAME-UTILS:DIRECTORY-P

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: ensure-deleted (pathname)

Deletes the given file if it still exists.

See FILE-EXISTS-P

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: file-exists-p (pathname)

Returns the truename of the file if it exists.

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: file-p (file)

Returns T if the given pathname points to a regular file.

This differs from PATHNAME-UTILS:FILE-P in the following way:
If the pathname is a file pathname, but points to a file that is not a regular file (and thus a directory, device, symlink, or other type of file node), then this function returns NIL.

See PATHNAME-UTILS:FILE-P

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: list-contents (directory)

Lists all files and directories within DIRECTORY.

See DIRECTORY*

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: list-devices (&optional host)

Lists all known pathname devices.

The HOST may be given as a hint for devices to list under the given host. The implementation may disregard this hint, however.

This may return NIL if the implementation cannot enumerate the devices.

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: list-directories (directory)

Lists all directories within DIRECTORY.

This excludes any files that don’t denote directories, and specifically returns them as directory pathnames.

See DIRECTORY*
See DIRECTORY-P

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: list-files (directory)

Lists all files within DIRECTORY.

This excludes any subdirectories.
Note that non-regular files are still included in this listing, meaning that not all returned files are necessarily FILE-P.

See DIRECTORY*
See DIRECTORY-P

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: list-hosts ()

List all known pathname hosts.

This may return NIL if the implementation cannot enumerate the hosts.

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: make-temporary-file (&key name type)

Create a path to a temporary file.

If you pass NAME, it is up to you to ensure that the path can be re-used if it exists already. Otherwise, the file is guaranteed to not exist yet.

The file will always be in the system’s temporary directory.

See TEMPORARY-DIRECTORY
See WITH-TEMPORARY-FILE

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: rename-file* (file to)

Renames FILE to TO, overwriting TO if it exists.

Like RENAME-FILE on most implementations, but ensures the destination is overwritten if it exists.

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Resolve symbolic links in the pathname as much as possible.

This does nothing for paths that are not absolute, physical pathnames. For absolute, physical pathnames it attempts to resolve all symbolic links or relative components in the pathname to arrive at a canonical pathname for the file.

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: runtime-directory ()

Returns the directory the executable was spawned from.

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Returns T if the given pathname points to a symbolic link file.

See FILE-P
See DIRECTORY-P
See CREATE-SYMBOLIC-LINK

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: temporary-directory ()

Returns the directory for temporary files.

Note: This makes no guarantee about the "temporary-ness" of the files. They may be cleared out after a reboot, after the lisp process terminates, or only at the user’s discretion. If you crate temporary files within this directory, you should delete them after they’re no longer needed.

See MAKE-TEMPORARY-FILE

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: truename* (pathname)

Like TRUENAME but ensures that it works on directory files as well on every implementation.

Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.


5.2 Internals


5.2.1 Ordinary functions

Function: call-with-current-directory (function directory)
Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.

Function: call-with-temporary-file (function &rest args)
Package

org.shirakumo.filesystem-utils.

Source

toolkit.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   D   E   F   L   M   R   S   T   W  
Index Entry  Section

(
(setf current-directory): Public ordinary functions

C
call-with-current-directory: Private ordinary functions
call-with-temporary-file: Private ordinary functions
copy-file: Public ordinary functions
create-symbolic-link: Public ordinary functions
current-directory: Public ordinary functions

D
directory*: Public ordinary functions
directory-p: Public ordinary functions

E
ensure-deleted: Public ordinary functions

F
file-exists-p: Public ordinary functions
file-p: Public ordinary functions
Function, (setf current-directory): Public ordinary functions
Function, call-with-current-directory: Private ordinary functions
Function, call-with-temporary-file: Private ordinary functions
Function, copy-file: Public ordinary functions
Function, create-symbolic-link: Public ordinary functions
Function, current-directory: Public ordinary functions
Function, directory*: Public ordinary functions
Function, directory-p: Public ordinary functions
Function, ensure-deleted: Public ordinary functions
Function, file-exists-p: Public ordinary functions
Function, file-p: Public ordinary functions
Function, list-contents: Public ordinary functions
Function, list-devices: Public ordinary functions
Function, list-directories: Public ordinary functions
Function, list-files: Public ordinary functions
Function, list-hosts: Public ordinary functions
Function, make-temporary-file: Public ordinary functions
Function, rename-file*: Public ordinary functions
Function, resolve-symbolic-links: Public ordinary functions
Function, runtime-directory: Public ordinary functions
Function, symbolic-link-p: Public ordinary functions
Function, temporary-directory: Public ordinary functions
Function, truename*: Public ordinary functions

L
list-contents: Public ordinary functions
list-devices: Public ordinary functions
list-directories: Public ordinary functions
list-files: Public ordinary functions
list-hosts: Public ordinary functions

M
Macro, with-current-directory: Public macros
Macro, with-temporary-file: Public macros
make-temporary-file: Public ordinary functions

R
rename-file*: Public ordinary functions
resolve-symbolic-links: Public ordinary functions
runtime-directory: Public ordinary functions

S
symbolic-link-p: Public ordinary functions

T
temporary-directory: Public ordinary functions
truename*: Public ordinary functions

W
with-current-directory: Public macros
with-temporary-file: Public macros


A.3 Variables