babashka.fs — babashka/fs 0.5.33

absolute? clj

(absolute? path)

Returns true if path is absolute via Path#isAbsolute.

absolutize clj

(absolutize path)

Converts path into an absolute path via Path#toAbsolutePath.

canonicalize clj

(canonicalize path)

(canonicalize path {:keys [:nofollow-links]})

Returns the canonical path for path via File#getCanonicalPath.

Options:

• :nofollow-links - when set, falls back on absolutize + normalize.

This function can be used as an alternative to real-path which requires files to exist.

components clj

(components path)

Returns a seq of paths for all components of path. i.e.: split on the file-separator.

copy clj

(copy source-file target-path)

(copy source-file
      target-path
      {:keys [replace-existing copy-attributes nofollow-links]})

Copies source-file to target-path dir or file via Files/copy.

Options:

• :replace-existing
• :copy-attributes
• :nofollow-links - used to determine to copy symbolic link itself or not.

Returns target-path.

copy-tree clj

(copy-tree source-dir target-dir)

(copy-tree source-dir
           target-dir
           {:keys [:replace-existing :copy-attributes :nofollow-links]
            :as opts})

Copies entire file tree from source-dir to target-dir. Creates target-dir if needed.

Options:

• same as copy
• :posix-file-permissions - string format unix-like system permissions passed to create-dirs when creating target-dir.

create-dir clj

(create-dir dir)

(create-dir dir {:keys [:posix-file-permissions]})

Creates dir via Files/createDirectory. Does not create parents.

Returns dir.

Options:

• :posix-file-permissions - string format for unix-like system permissions for dir, as described in str->posix. Affected by umask.

create-dirs clj

(create-dirs dir)

(create-dirs dir {:keys [:posix-file-permissions]})

Creates dir via Files/createDirectories. Also creates parents if needed. Does not throw an exception if the dirs exist already. Similar to mkdir -p shell command.

Returns dir.

Options:

• :posix-file-permissions - string format for unix-like system permissions for dir, as described in str->posix. Affected by umask.

create-file clj

(create-file file)

(create-file file {:keys [:posix-file-permissions]})

Creates empty file via Files/createFile.

Returns file.

Options:

• :posix-file-permissions - string format for unix-like system permissions for file, as described in str->posix. Affected by umask.

create-link clj

(create-link link existing-file)

Creates a new hard link (directory entry) for an existing-file via Files/createLink.

Returns link.

create-sym-link clj

(create-sym-link link target-path)

Creates a symbolic link to target-path via Files/createSymbolicLink.

Returns link.

As of this writing, JDKs do not recognize empty-string target-path "" as the cwd. Consider instead using a target-path of "." to link to the cwd.

create-temp-dir clj

(create-temp-dir)

(create-temp-dir {:keys [:dir :prefix :posix-file-permissions] :as opts})

Returns path to directory created via Files/createTempDirectory.

This function does not set up any automatic deletion of the directories it creates. See with-temp-dir for that functionality.

Options:

• :dir - directory in which to create the new directory. Defaults to default system temp dir (e.g. /tmp); see temp-dir. Must already exist.
• :prefix - provided as a hint to the process that generates the name of the new directory. In most cases, this will be the beginning of the new directory name. Defaults to a random (v4) UUID.
• :posix-file-permissions - string format unix-like system permissions as described in str->posix for new directory. If not specified, uses the file system default permissions for new directories. Affected by umask.
• :warning: :path - [DEPRECATED] previous name for :dir, kept for backwards compatibility. If both :path and :dir are given (don't do that!), :dir is used.

Examples:

• (create-temp-dir)
• (create-temp-dir {:posix-file-permissions "rwx------"})
• (create-temp-dir {:dir (path (cwd) "_workdir") :prefix "process-1-"})

create-temp-file clj

(create-temp-file)

(create-temp-file {:keys [:dir :prefix :suffix :posix-file-permissions]
                   :as opts})

Returns path to empty file created via Files/createTempFile.

This function does not set up any automatic deletion of the files it creates. Create the file in a with-temp-dir for that functionality.

Options:

• :dir - directory in which to create the new file. Defaults to default system temp dir (e.g. /tmp); see temp-dir. Must already exist.
• :prefix - provided as a hint to the process that generates the name of the new file. In most cases, this will be the beginning of the new file name. Defaults to a random (v4) UUID.
• :suffix - provided as a hint to the process that generates the name of the new file. In most cases, this will be the end of the new file name. Defaults to a random (v4) UUID.
• :posix-file-permissions - string format unix-like system permissions for new file, as described in str->posix. If not specified, uses the file system default permissions for new files. Affected by umask.
• :warning: :path - [DEPRECATED] Previous name for :dir, kept for backwards compatibility. If both :path and :dir are given (don't do that!), :dir is used.

Examples:

• (create-temp-file)
• (create-temp-file {:posix-file-permissions "rw-------"})
• (create-temp-file {:dir (path (cwd) "_workdir") :prefix "process-1-" :suffix "-queue"})

creation-time clj

(creation-time path)

(creation-time path {:keys [nofollow-links] :as opts})

Returns creation time of path as FileTime.

See README notes for some details on behaviour.

See also: set-creation-time, last-modified-time, file-time->instant, file-time->millis

cwd clj

(cwd)

Returns current working directory path.

delete clj

(delete path)

Deletes path via Files/delete. Returns nil if the delete was successful, throws otherwise. Does not follow symlinks.

delete-if-exists clj

(delete-if-exists path)

Deletes path if it exists via Files/deleteIfExists. Returns true if the delete was successful, false if path didn't exist. Does not follow symlinks.

delete-on-exit clj

(delete-on-exit path)

Requests delete of path on exit via File#deleteOnExit. Returns path.

delete-tree clj

(delete-tree root-path)

(delete-tree root-path {:keys [force]})

Deletes the file tree at root-path using walk-file-tree. Similar to rm -rf shell command. Does not follow symlinks.

Options:

• :force - if true forces deletion of read-only files/directories. Similar to chmod -R +wx + rm -rf shell commands.

directory? clj

(directory? path)

(directory? path {:keys [:nofollow-links]})

Returns true if path is a directory via Files/isDirectory.

Options:

• :nofollow-links

ends-with? clj

(ends-with? this-path other-path)

Returns true if this-path ends with other-path via Path#endsWith.

See also: starts-with?

exec-paths clj

(exec-paths)

Returns a vector of command search paths (from the PATH environment variable). Same as (split-paths (System/getenv "PATH")).

executable? clj

(executable? path)

Returns true if path is executable via Files/isExecutable.

exists? clj

(exists? path)

(exists? path {:keys [:nofollow-links]})

Returns true if path exists via Files/exists.

Options:

• :nofollow-links

expand-home clj

(expand-home path)

Returns path replacing ~ (tilde) with home dir.

If path:

• does not start with ~, returns path.
• starts with ~ then file-separator, ~ is replaced with (home). e.g., ~/foo -> /home/myuser/foo
• starts with ~ then some other chars, those other chars are assumed to be a username, then naively expanded to (home username). e.g., ~someuser/foo -> /home/someuser/foo

See also: home

extension clj

(extension path)

Returns the extension of path via split-ext.

file clj

(file path)

(file path & paths)

Coerces path(s) into a File, combining multiple paths into one. Multiple-arg versions treat the first argument as parent and subsequent args as children relative to the parent.

file-name clj

(file-name path)

Returns the name of the file or directory for path via File#getName. E.g. (file-name "foo/bar/baz") returns "baz".

file-separator clj

The system-dependent default path component separator character (as string).

file-time->instant clj

(file-time->instant ft)

Converts ft FileTime to an Instant.

file-time->millis clj

(file-time->millis ft)

Converts ft FileTime to epoch milliseconds (long).

get-attribute clj

(get-attribute path attribute)

(get-attribute path attribute {:keys [:nofollow-links]})

Returns value of attribute for path via Files/getAttribute.

Options:

• :nofollow-links

glob clj

(glob root-dir pattern)

(glob root-dir pattern opts)

Returns a vector of paths matching glob pattern (on path and filename) relative to root-dir. Patterns containing ** or / will cause a recursive walk under root-dir, unless overriden with :recursive false. Similarly, :hidden will be automatically enabled when pattern starts with a dot. Glob interpretation is done using the rules described in FileSystem#getPathMatcher

Options:

• :hidden - match hidden paths. Implied true when pattern starts with a dot; otherwise, defaults to false. Note: on Windows files starting with a dot are not hidden, unless their hidden attribute is set.
• :follow-links - follow symlinks. Defaults to false.
• :recursive - implied true when pattern contains ** or /; otherwise, defaults to false.
  • true - pattern is matched against all descendant files and directories under root-dir
  • false - pattern is matched only against immediate children under root-dir
• :max-depth - max depth to descend into directory structure, when recursing. Defaults to Integer/MAX_VALUE.

Examples:

• (fs/glob "." "**.clj") - finds .clj files and dirs under . dir and its subdirs
• (fs/glob "." "**.clj" {:recursive false}) - finds .clj files and dirs immediately under . dir only
• (fs/glob "." "*.clj" {:recursive true}) - finds .clj files and dirs immediately under . only (pattern lacks directory wildcards)

If on macOS, see note on glob

See also: match

gunzip clj

(gunzip gz-file)

(gunzip gz-file target-dir)

(gunzip gz-file target-dir {:keys [replace-existing]})

Extracts gz-file to target-dir.

If target-dir not specified (or nil) defaults to gz-file dir.

File is extracted to target-dir with gz-file file-name without .gz extension.

Creates target-dir dir(s) if necessary. The gz-file is not deleted.

Options:

• :replace-existing - when true overwrites existing file

See also: gzip

gzip clj

(gzip source-file)

(gzip source-file {:keys [dir out-file]})

Gzips source-file to :dir/:out-file.

Does not store the source-file name in the .gz file. The source-file is not deleted.

Options:

• :dir(s) - created if necessary. If not specified, defaults to source-file dir.
• :out-file - if not specified, defaults to source-file file-name with .gz extension.

Returns the created gzip file.

See also: gunzip

hidden? clj

(hidden? path)

Returns true if path is hidden via Files/isHidden.

TIP: some older JDKs can throw on empty-string path (hidden ""). Consider instead checking cwd via (hidden ".").

home clj

(home)

(home user)

Returns home dir path.

With no arguments, returns the current value of the user.home system property. If a user is passed, returns that user's home directory as found in the parent of home with no args.

instant->file-time clj

(instant->file-time instant)

Converts instant Instant to a FileTime.

last-modified-time clj

(last-modified-time path)

(last-modified-time path {:keys [nofollow-links] :as opts})

Returns last modified time of path as FileTime.

See also: set-last-modified-time, creation-time, file-time->instant, file-time->millis

list-dir clj

(list-dir dir)

(list-dir dir glob-or-accept)

Returns a vector of all paths in dir. For descending into subdirectories use glob.

• glob-or-accept - a glob string such as "*.edn" or a (fn accept [^java.nio.file.Path p]) -> truthy

list-dirs clj

(list-dirs dirs glob-or-accept)

Similar to list-dir but accepts multiple roots in dirs and returns the concatenated results.

• glob-or-accept - a glob string such as "*.edn" or a (fn accept [^java.nio.file.Path p]) -> truthy

match clj

(match root-dir pattern)

(match root-dir pattern {:keys [hidden follow-links max-depth recursive]})

Returns a vector of paths matching pattern (on path and filename) relative to root-dir. Pattern interpretation is done using the rules described in FileSystem#getPathMatcher

Options:

• :hidden - match hidden paths - note: on Windows paths starting with a dot are not hidden, unless their hidden attribute is set. Defaults to false, i.e. skip hidden files and folders.
• :follow-links - follow symlinks. Defaults to false.
• :recursive
  • true - pattern is matched against all descendant files and directories under root-dir
  • false (default) - pattern is matched only against immediate children under root-dir
• :max-depth - max depth to descend into directory structure, when matching recursively. Defaults to Integer/MAX_VALUE.

Examples:

• (fs/match "." "regex:.*\\.clj" {:recursive true})

See also: glob

millis->file-time clj

(millis->file-time millis)

Converts epoch milliseconds (long) to a FileTime.

modified-since clj

(modified-since anchor-path path-set)

Returns seq of regular files (non-directories, non-symlinks) from path-set that were modified since the anchor-path. The anchor-path can be a regular file or directory, in which case the recursive max last modified time stamp is used as the timestamp to compare with. The path-set may be a regular file, directory or collection of paths (e.g. as returned by glob). Directories are searched recursively.

move clj

(move source-path target-path)

(move source-path target-path {:keys [:replace-existing :atomic-move]})

Moves or renames dir or file at source-path to target-path dir or file via Files/move. If target-path is a directory, moves source-path under target-path. Never follows symbolic links.

Returns target-path.

Options:

• replace-existing - overwrite existing target-path, default false
• atomic-move - watchers will only see complete target-path file, default false

normalize clj

(normalize path)

Returns normalized path for path via Path#normalize.

owner clj

(owner path)

(owner path {:keys [:nofollow-links]})

Returns the owner of path via Files/getOwner. Call str on return value to get the owner name as a string.

Options:

• :nofollow-links

parent clj

(parent path)

Returns parent path of path via Path#getParent. Akin to dirname in bash.

path clj

(path path)

(path parent child)

(path parent child & more)

Coerces path(s) into a Path, combining multiple paths into one. Multiple-arg versions treat the first argument as parent and subsequent args as children relative to the parent.

path-separator clj

The system-dependent path-separator character (as string).

posix->str clj

(posix->str p)

Converts a set of PosixFilePermission p to a string, like "rwx------".

See also: str->posix

posix-file-permissions clj

(posix-file-permissions path)

(posix-file-permissions path {:keys [:nofollow-links]})

Returns a set of PosixFilePermission for path via Files/getPosixFilePermissions. Use posix->str to convert to a string.

Options:

• :nofollow-links

See also: set-posix-file-permissions

read-all-bytes clj

(read-all-bytes file)

Returns contents of file as byte array via Files/readAllBytes.

read-all-lines clj

(read-all-lines file)

(read-all-lines file {:keys [charset] :or {charset "utf-8"}})

Returns contents of file as a vector of lines via Files/readAllLines.

Options:

• :charset - defaults to "utf-8"

read-attributes clj

(read-attributes path attributes)

(read-attributes path attributes {:keys [:nofollow-links :key-fn] :as opts})

Same as read-attributes* but returns requested attributes for path as a map with keywordized attribute keys.

Options:

• :key-fn - optionally override keywordizing function with your own.
• :nofollow-links

read-attributes* clj

(read-attributes* path attributes)

(read-attributes* path attributes {:keys [:nofollow-links]})

Returns requested attributes for path via Files/readAttributes.

Options:

• :nofollow-links

read-link clj

(read-link sym-link-path)

Returns the immediate target of sym-link-path via Files/readSymbolicLink. The target need not exist.

readable? clj

(readable? path)

Returns true if path is readable via Files/isReadable

real-path clj

(real-path path)

(real-path path {:keys [:nofollow-links]})

Converts path into real path via Path#toRealPath.

Options:

• :nofollow-links

regular-file? clj

(regular-file? path)

(regular-file? path {:keys [:nofollow-links]})

Returns true if path is a regular file via Files/isRegularFile.

Options:

• :nofollow-links

relative? clj

(relative? path)

Returns true if path is relative (in other words, is not absolute?).

relativize clj

(relativize base-path other-path)

Returns other-path relative to base-path via Path#relativize.

Examples:

• (fs/relativize "a/b" "a/b/c/d") => c/d
• (fs/relativize "a/b/c/d" "a/b") => ../..

root clj

(root path)

Returns root path for path, or nil, via Path#getRoot.

The return value depends upon the runtime platform.

On Windows, returns Windows specific roots, ex: (replace forward slash with backslash):

• C:/ for C:/foo/bar
• C: for C:foo/bar
• //server/share for //server/share/foo/bar

On Linux and macOS, returns the leading / for anything that looks like an absolute path.

same-file? clj

(same-file? this-path other-path)

Returns true if this-path is the same file as other-path via Files/isSamefile.

set-attribute clj

(set-attribute path attribute value)

(set-attribute path attribute value {:keys [:nofollow-links]})

Sets attribute for path to value via Files/setAttribute.

set-creation-time clj

(set-creation-time path time)

(set-creation-time path time {:keys [nofollow-links] :as opts})

Sets creation time of path. time can be epoch milliseconds, FileTime, or Instant.

Options:

• :nofollow-links

See README notes for some details on behaviour.

See also: creation-time

set-last-modified-time clj

(set-last-modified-time path time)

(set-last-modified-time path time {:keys [nofollow-links] :as opts})

Sets last modified time of path. time can be epoch milliseconds, FileTime, or Instant.

See also: last-modified-time

set-posix-file-permissions clj

(set-posix-file-permissions path posix-file-permissions)

Sets posix-file-permissions on path via Files/setPosixFilePermissions. Accepts a string like "rwx------" or a set of PosixFilePermission.

See also: posix-file-permissions

size clj

(size path)

Returns the size of path in bytes.

split-ext clj

(split-ext path)

(split-ext path {:keys [ext]})

Splits path on extension. Returns [name ext]. Leading directories in path are not processed.

Options:

• :ext - split on specified extension (do not include a leading dot)

Examples:

• (fs/split-ext "foo.bar.baz") => ["foo.bar" "baz"]
• (fs/split-ext "foo.bar.baz" {:ext "bar.baz"}) => ["foo" "bar.baz"]
• (fs/split-ext "foo.bar.baz" {:ext "png"}) => ["foo.bar.baz" nil]

split-paths clj

(split-paths joined-paths)

Splits joined-paths string into a vector of paths by OS-specific path-separator. On UNIX systems, the separator is :, on Microsoft Windows systems it is ;.

starts-with? clj

(starts-with? this-path other-path)

Returns true if this-path starts with other-path via Path#startsWith.

See also: ends-with?

str->posix clj

(str->posix s)

Converts a string s to a set of PosixFilePermission.

s is a string like "rwx------".

See also: posix->str

strip-ext clj

(strip-ext path)

(strip-ext path {:keys [ext] :as opts})

Strips extension from path via split-ext.

sym-link? clj

(sym-link? path)

Returns true if path is a symbolic link via Files/isSymbolicLink.

temp-dir clj

(temp-dir)

Returns java.io.tmpdir property as path.

touch clj

(touch path)

(touch path {:keys [time nofollow-links] :as opts})

Updates last modified time of path to :time, creating path as a file if it does not exist.

If path is deleted by some other process/thread before :time is set, a NoSuchFileException will be thrown. Callers can, if their use case requires it, implement their own retry loop.

Options:

• :time - last modified time (epoch milliseconds, Instant, or FileTime), defaults to current time
• :nofollow-links

unixify clj

(unixify path)

Returns path as string with Unix-style file separators (/).

unzip clj

(unzip zip-file)

(unzip zip-file target-dir)

(unzip zip-file target-dir {:keys [replace-existing extract-fn]})

Unzips zip-file to target-dir (default ".").

Options:

• :replace-existing - true / false: overwrite existing files
• :extract-fn - function that decides if the current ZipEntry should be extracted. Extraction only occurs if a truthy value is returned (i.e. not nil/false). The function is only called for files (not directories) with a single map arg:
  • :entry - the current ZipEntry
  • :name - the name of the ZipEntry (result of calling getName)

See also: zip.

update-file clj

(update-file file f & xs)

(update-file file opts f & xs)

Updates the contents of text file with result of applying function f with old contents and args xs. Returns the new contents.

Options:

• :charset - charset of file, default to "utf-8"

walk-file-tree clj

(walk-file-tree path
                {:keys [:pre-visit-dir :post-visit-dir :visit-file
                        :visit-file-failed :follow-links :max-depth]})

Walks path via Files/walkFileTree.

Options:

• :follow-links
• :max-depth - maximum directory depth to walk, defaults is unlimited
• Override default visitor functions via:
  • :pre-visit-dir - args [dir attrs]
  • :post-visit-dir - args [dir ex]
  • :visit-file - args [file attrs]
  • :visit-file-failed - args [file ex]

All visitor functions must return one of :continue, :skip-subtree, :skip-siblings or :terminate. A different return value will throw. When not supplied, visitor functions default to (constantly :continue).

Returns path.

which clj

(which program)

(which program opts)

Returns path to first executable program found in :paths, similar to the which Unix command.

When program is a relative or absolute path, :paths option is not consulted. On Windows, the :win-exts variants are still searched. On other OSes, the path for program will be returned if executable, else nil.

Options:

• :paths - paths to search, default is return of (exec-paths)
• :win-exts - active on Windows only. Searches for program with filename extensions specified in :win-exts option. If program already includes an extension from :win-exts, it will be searched as-is first. Default is ["com" "exe" "bat" "cmd"].

which-all clj

(which-all program)

(which-all program opts)

Returns a vector of every path to program found in (exec-paths). See which.

windows? clj

(windows?)

Returns true if OS is Windows.

with-temp-dir clj macro

(with-temp-dir [temp-dir] & body)

(with-temp-dir [temp-dir opts] & body)

Evaluates body with temp-dir bound to the result of (create-temp-dir opts).

By default, the temp-dir will be removed with delete-tree on exit from the scope.

Options:

• see create-temp-dir for options that control directory creation
• :keep - if true does not delete the directory on exit from macro scope.

Example:

(with-temp-dir [d]
  (let [t (path d "extract")
    (create-dir t)
    (gunzip path-to-zip t)
    (copy (path t "the-one-file-I-wanted.txt") (path permanent-dir "file-I-extracted.txt"))))
;; d no longer exists here

writable? clj

(writable? path)

Returns true if path is writable via Files/isWritable

write-bytes clj

(write-bytes file bytes)

(write-bytes file
             bytes
             {:keys [append create truncate-existing write] :as opts})

Writes bytes to file via Files/write.

Options:

• :create - (default true)
• :truncate-existing - (default true)
• :write - (default true)
• :append - (default false)
• or any java.nio.file.StandardOption.

Examples:

(fs/write-bytes f (.getBytes (String. "foo"))) ;; overwrites + truncates or creates new file
(fs/write-bytes f (.getBytes (String. "foo")) {:append true})

write-lines clj

(write-lines file lines)

(write-lines file lines {:keys [charset] :or {charset "utf-8"} :as opts})

Writes lines, a seqable of strings, to file via Files/write.

Options:

• :charset - (default "utf-8")

Open options:

• :create - (default true)
• :truncate-existing - (default true)
• :write - (default true)
• :append - (default false)
• or any java.nio.file.StandardOption.

xdg-cache-home clj

(xdg-cache-home)

(xdg-cache-home app)

Returns path to user-specific non-essential data as described in the XDG Base Directory Specification.

Uses env-var XDG_CACHE_HOME (if set and representing an absolute path), else (fs/path (fs/home) ".cache"). When provided, appends app to the returned path.

xdg-config-home clj

(xdg-config-home)

(xdg-config-home app)

Returns path to user-specific configuration files as described in the XDG Base Directory Specification.

Uses env-var XDG_CONFIG_HOME (if set and representing an absolute path), else (fs/path (fs/home) ".config"). When provided, appends app to the returned path.

xdg-data-home clj

(xdg-data-home)

(xdg-data-home app)

Returns path to user-specific data files as described in the XDG Base Directory Specification.

Uses env-var XDG_DATA_HOME (if set and representing an absolute path), else (fs/path (fs/home) ".local" "share"). When provided, appends app to the returned path.

xdg-state-home clj

(xdg-state-home)

(xdg-state-home app)

Returns path to user-specific state files as described in the XDG Base Directory Specification.

Uses env-var XDG_STATE_HOME (if set and representing an absolute path), else (fs/path (fs/home) ".local" "state"). When provided, appends app to the returned path.

zip clj

(zip zip-file path-or-paths)

(zip zip-file path-or-paths opts)

Zips path-or-paths into zip-file. A path may be a file or directory. Directories are included recursively and their names are preserved in the zip file. Currently only accepts relative paths.

Options:

• :root - optional directory to be elided in zip-file entries. E.g.: (fs/zip ["src"] {:root "src"})
• :path-fn - an optional custom path conversion function. A single-arg function called for each file system path returning the path to be used for the corresponding zip entry.

See also: unzip.