(rontolisp) docs
← cl Package Functions

directory

(directory pathspec &key (resolve-symlinks t))

The truenames of the files matching pathspec, each once, sorted with string< so the same program prints the same answer on every backend whatever order the host hands entries back in. nil when nothing matches -- it never signals.

A wild name component lists the directory and keeps what the pattern matches. * stands for any sequence of characters, ? for exactly one. Each answer is the entry's truename, as truename would answer it, so each is directly openable and a directory carries a trailing /:

A truename is absolute: a relative pathspec is merged with *default-pathname-defaults* and placed below the working directory, as SBCL's is. Run from /w, given a directory d holding a.txt, b.txt and the subdirectories sub/ and empty/:

pathspecanswer
"d/*.*"(#P"/w/d/a.txt" #P"/w/d/b.txt" #P"/w/d/empty/" #P"/w/d/sub/") — everything
"d/*.txt"(#P"/w/d/a.txt" #P"/w/d/b.txt")
"d/?.txt"(#P"/w/d/a.txt" #P"/w/d/b.txt")
"d/*"(#P"/w/d/empty/" #P"/w/d/sub/") — a wild name with NO type, so only untyped entries
"d/a*"NIL — same rule: a.txt has a type

A non-wild pathspec designates itself, as in Common Lisp: "d/a.txt" answers (#P"/w/d/a.txt") when the file exists, and a directory answers itself in directory form -- both "d" and "d/" give (#P"/w/d/"). Listing a directory is "d/*.*", not "d/".

A symbolic link is matched by its own name and answered by its truename, so two names for one file come back once; a link whose target is missing answers itself. :resolve-symlinks nil keeps the matched names instead: a link to a directory still carries the trailing /, and a link whose target is missing is left out. Run from /w, given a directory t/ holding the directory d/ (with a.txt in it), ln a link to d, al a link to d/a.txt and dang a link to nothing:

callanswer
(directory "t/*")(#P"/w/t/d/" #P"/w/t/d/a.txt" #P"/w/t/dang")
(directory "t/*" :resolve-symlinks nil)(#P"/w/t/al" #P"/w/t/d/" #P"/w/t/ln/")

The . and .. of the pathspec are taken out by spelling before anything is listed, in both modes, as SBCL does: (directory "./*.txt") answers #P"/w/a.txt", and (directory "t/ln/../*") lists t/, the directory holding the name ln, wherever ln leads. truename reads a .. after a link from where the link leads instead.

A wild directory component expands the prefix before the name is matched. * walks exactly one level and ** walks the whole subtree -- and, as in Common Lisp, ** matches ZERO levels as well as many, so the base directory's own files come back too:

pathspecanswer
"d/*/*.lisp"the .lisp files one level below d/
"d/**/*.lisp"every .lisp file in d/ and anywhere below it
"d/**/"d/ itself and every directory below it

Every expectation above is the same answer SBCL gives for the same tree.

Backend support

All four backends, through one primitive each: the source-loader abstraction on the interpreter (so a host without a filesystem, such as the browser playground, answers nil rather than failing), java.io.File.list on the JVM, and WASI fd_readdir on both WASM backends -- Preview 1 binds the real host function, --component an adapter over wasi:filesystem's read-directory. A WASM module resolves the path against its preopened directories -- a relative path against the first one, an absolute path against the preopened directory whose name is its longest prefix -- so run it with --dir; without one nothing matches. The answers are absolute only where the module knows its working directory, as for probe-file: under wasmtime run --dir . the table's answers lose their /w/ prefix.

The . and .. self/parent entries are never returned on any backend. On WASM a link is resolved only where the module can read it through a preopened directory, as for probe-file.

uiop:directory-files, uiop:subdirectories and uiop:collect-sub*directories are defined in terms of this one function, with :resolve-symlinks nil as upstream UIOP asks of SBCL.