From eb6ae0447976b076797adf01db9a3806393aec6a Mon Sep 17 00:00:00 2001 From: Michiel Borkent Date: Sat, 13 Apr 2024 11:39:13 +0200 Subject: [PATCH] quickdoc --- API.md | 145 ++++++++++++++++++++++++++++++--------------------------- 1 file changed, 77 insertions(+), 68 deletions(-) diff --git a/API.md b/API.md index 968b5d6..cae4764 100644 --- a/API.md +++ b/API.md @@ -164,7 +164,7 @@ Copies src file to dest dir or file. Copies entire file tree from src to dest. Creates dest if needed using [`create-dirs`](#babashka.fs/create-dirs), passing it the `:posix-file-permissions` option. Supports same options as copy. -

Source

+

Source

## `create-dir` ``` clojure @@ -174,7 +174,7 @@ Copies entire file tree from src to dest. Creates dest if needed ``` Creates dir using `Files#createDirectory`. Does not create parents. -

Source

+

Source

## `create-dirs` ``` clojure @@ -185,7 +185,7 @@ Creates dir using `Files#createDirectory`. Does not create parents. Creates directories using `Files#createDirectories`. Also creates parents if needed. Doesn't throw an exception if the dirs exist already. Similar to `mkdir -p` -

Source

+

Source

## `create-file` ``` clojure @@ -195,7 +195,10 @@ Creates directories using `Files#createDirectories`. Also creates parents if nee ``` Creates empty file using `Files#createFile`. -

Source

+ + File permissions can be specified with an `:posix-file-permissions` option. + String format for posix file permissions is described in the [`str->posix`](#babashka.fs/str->posix) docstring. +

Source

## `create-link` ``` clojure @@ -204,7 +207,7 @@ Creates empty file using `Files#createFile`. ``` Create a hard link from path to target. -

Source

+

Source

## `create-sym-link` ``` clojure @@ -213,7 +216,7 @@ Create a hard link from path to target. ``` Create a soft link from path to target. -

Source

+

Source

## `create-temp-dir` ``` clojure @@ -228,8 +231,10 @@ Creates a temporary directory using Files#createDirectories. `(create-temp-dir {:keys [:prefix :dir :posix-file-permissions]})`: create temp dir in dir path with prefix. If prefix is not provided, a random one - is generated. If path is not provided, the directory is created as if called with `(create-temp-dir)`. The `:posix-file-permissions` option is a string like `"rwx------"`. -

Source

+ is generated. If path is not provided, the directory is created as if called with `(create-temp-dir)`. + File permissions can be specified with an `:posix-file-permissions` option. + String format for posix file permissions is described in the [`str->posix`](#babashka.fs/str->posix) docstring. +

Source

## `create-temp-file` ``` clojure @@ -241,11 +246,13 @@ Creates a temporary directory using Files#createDirectories. Creates an empty temporary file using Files#createTempFile. - `(create-temp-file)`: creates temp file with random prefix and suffix. - - `(create-temp-dir {:keys [:prefix :suffix :path :posix-file-permissions]})`: create - temp file in path with prefix. If prefix and suffix are not - provided, random ones are generated. The `:posix-file-permissions` - option is a string like `"rwx------"`. -

Source

+ + - `(create-temp-dir {:keys [:prefix :suffix :path :posix-file-permissions]})`: + create temp file in path with prefix. If prefix and suffix are not provided, + random ones are generated. + File permissions can be specified with an `:posix-file-permissions` option. + String format for posix file permissions is described in the [`str->posix`](#babashka.fs/str->posix) docstring. +

Source

## `creation-time` ``` clojure @@ -255,7 +262,7 @@ Creates an empty temporary file using Files#createTempFile. ``` Returns creation time as FileTime. -

Source

+

Source

## `cwd` ``` clojure @@ -264,7 +271,7 @@ Returns creation time as FileTime. ``` Returns current working directory as path -

Source

+

Source

## `delete` ``` clojure @@ -274,7 +281,7 @@ Returns current working directory as path Deletes f. Returns nil if the delete was successful, throws otherwise. Does not follow symlinks. -

Source

+

Source

## `delete-if-exists` ``` clojure @@ -284,7 +291,7 @@ Deletes f. Returns nil if the delete was successful, Deletes f if it exists. Returns true if the delete was successful, false if f didn't exist. Does not follow symlinks. -

Source

+

Source

## `delete-on-exit` ``` clojure @@ -293,7 +300,7 @@ Deletes f if it exists. Returns true if the delete was successful, ``` Requests delete on exit via `File#deleteOnExit`. Returns f. -

Source

+

Source

## `delete-tree` ``` clojure @@ -304,7 +311,7 @@ Requests delete on exit via `File#deleteOnExit`. Returns f. Deletes a file tree using [`walk-file-tree`](#babashka.fs/walk-file-tree). Similar to `rm -rf`. Does not follow symlinks. `force` ensures read-only directories/files are deleted. Similar to `chmod -R +wx` + `rm -rf` -

Source

+

Source

## `directory?` ``` clojure @@ -323,7 +330,7 @@ Returns true if f is a directory, using Files/isDirectory. ``` Returns true if path this ends with path other. -

Source

+

Source

## `exec-paths` ``` clojure @@ -333,7 +340,7 @@ Returns true if path this ends with path other. Returns executable paths (using the PATH environment variable). Same as `(split-paths (System/getenv "PATH"))`. -

Source

+

Source

## `executable?` ``` clojure @@ -367,7 +374,7 @@ If [[`path`](#babashka.fs/path)](#babashka.fs/path) begins with a tilde (`~`), e directory. This is (naively) assumed to be a directory with the same name as the user relative to the parent of the current value of `user.home`. -

Source

+

Source

## `extension` ``` clojure @@ -376,7 +383,7 @@ If [[`path`](#babashka.fs/path)](#babashka.fs/path) begins with a tilde (`~`), e ``` Returns the extension of a file via [`split-ext`](#babashka.fs/split-ext). -

Source

+

Source

## `file` ``` clojure @@ -411,7 +418,7 @@ Returns the name of the file or directory. E.g. (file-name "foo/bar/baz") return ``` Converts a java.nio.file.attribute.FileTime to a java.time.Instant. -

Source

+

Source

## `file-time->millis` ``` clojure @@ -420,7 +427,7 @@ Converts a java.nio.file.attribute.FileTime to a java.time.Instant. ``` Converts a java.nio.file.attribute.FileTime to epoch millis (long). -

Source

+

Source

## `get-attribute` ``` clojure @@ -428,7 +435,7 @@ Converts a java.nio.file.attribute.FileTime to epoch millis (long). (get-attribute path attribute) (get-attribute path attribute {:keys [:nofollow-links]}) ``` -

Source

+

Source

## `glob` ``` clojure @@ -466,7 +473,7 @@ Extracts `gz-file` to `dest` directory (default `"."`). Options: * `:replace-existing` - `true` / `false`: overwrite existing files -

Source

+

Source

## `gzip` ``` clojure @@ -479,7 +486,7 @@ Gzips `source-file` and writes the output to `dir/out-file`. If `out-file` is not provided, the `source-file` name with `.gz` appended is used. If `dir` is not provided, the current directory is used. Returns the created gzip file. -

Source

+

Source

## `hidden?` ``` clojure @@ -500,7 +507,7 @@ Returns true if f is hidden. 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. -

Source

+

Source

## `instant->file-time` ``` clojure @@ -509,7 +516,7 @@ With no arguments, returns the current value of the `user.home` ``` Converts a java.time.Instant to a java.nio.file.attribute.FileTime. -

Source

+

Source

## `last-modified-time` ``` clojure @@ -519,7 +526,7 @@ Converts a java.time.Instant to a java.nio.file.attribute.FileTime. ``` Returns last modified time as a java.nio.file.attribute.FileTime. -

Source

+

Source

## `list-dir` ``` clojure @@ -540,7 +547,7 @@ Returns all paths in dir as vector. For descending into subdirectories use `glob Similar to list-dir but accepts multiple roots and returns the concatenated results. - `glob-or-accept` - a glob string such as "*.edn" or a (fn accept [^java.nio.file.Path p]) -> truthy -

Source

+

Source

## `match` ``` clojure @@ -572,7 +579,7 @@ Given a file and match pattern, returns matches as vector of ``` Converts epoch millis (long) to a java.nio.file.attribute.FileTime. -

Source

+

Source

## `modified-since` ``` clojure @@ -586,7 +593,7 @@ Returns seq of regular files (non-directories, non-symlinks) from file-set that to compare with. The file-set may be a regular file, directory or collection of files (e.g. returned by glob). Directories are searched recursively. -

Source

+

Source

## `move` ``` clojure @@ -596,7 +603,7 @@ Returns seq of regular files (non-directories, non-symlinks) from file-set that ``` Move or rename a file to a target dir or file via `Files/move`. -

Source

+

Source

## `normalize` ``` clojure @@ -625,7 +632,7 @@ Returns the owner of a file. Call `str` on it to get the owner name ``` Returns parent of f. Akin to `dirname` in bash. -

Source

+

Source

## `path` ``` clojure @@ -658,7 +665,7 @@ Converts a set of PosixFilePermission to a string. -

Source

+

Source

## `read-all-bytes` ``` clojure @@ -667,7 +674,7 @@ Converts a set of PosixFilePermission to a string. ``` Returns contents of file as byte array. -

Source

+

Source

## `read-all-lines` ``` clojure @@ -677,7 +684,7 @@ Returns contents of file as byte array. ``` Read all lines from a file. -

Source

+

Source

## `read-attributes` ``` clojure @@ -688,7 +695,7 @@ Read all lines from a file. Same as [`read-attributes*`](#babashka.fs/read-attributes*) but turns attributes into a map and keywordizes keys. Keywordizing can be changed by passing a :key-fn in the options map. -

Source

+

Source

## `read-attributes*` ``` clojure @@ -698,7 +705,7 @@ Same as [`read-attributes*`](#babashka.fs/read-attributes*) but turns attributes ``` Reads attributes via Files/readAttributes. -

Source

+

Source

## `readable?` ``` clojure @@ -754,7 +761,7 @@ Returns relative path by comparing this with other. ``` Returns true if this is the same file as other. -

Source

+

Source

## `set-attribute` ``` clojure @@ -762,7 +769,7 @@ Returns true if this is the same file as other. (set-attribute path attribute value) (set-attribute path attribute value {:keys [:nofollow-links]}) ``` -

Source

+

Source

## `set-creation-time` ``` clojure @@ -772,7 +779,7 @@ Returns true if this is the same file as other. ``` Sets creation time of f to time (millis, java.time.Instant or java.nio.file.attribute.FileTime). -

Source

+

Source

## `set-last-modified-time` ``` clojure @@ -782,13 +789,13 @@ Sets creation time of f to time (millis, java.time.Instant or java.nio.file.attr ``` Sets last modified time of f to time (millis, java.time.Instant or java.nio.file.attribute.FileTime). -

Source

+

Source

## `set-posix-file-permissions` -

Source

+

Source

## `size` ``` clojure @@ -797,7 +804,7 @@ Sets last modified time of f to time (millis, java.time.Instant or java.nio.file ``` Returns the size of a file (in bytes). -

Source

+

Source

## `split-ext` ``` clojure @@ -809,7 +816,7 @@ Returns the size of a file (in bytes). Splits path on extension If provided, a specific extension `ext`, the extension (without dot), will be used for splitting. Directories are not processed. -

Source

+

Source

## `split-paths` ``` clojure @@ -819,7 +826,7 @@ Splits path on extension If provided, a specific extension `ext`, the Splits a path list given as a string joined by the OS-specific path-separator into a vec of paths. On UNIX systems, the separator is ':', on Microsoft Windows systems it is ';'. -

Source

+

Source

## `starts-with?` ``` clojure @@ -828,7 +835,7 @@ Splits a path list given as a string joined by the OS-specific path-separator in ``` Returns true if path this starts with path other. -

Source

+

Source

## `str->posix` ``` clojure @@ -837,7 +844,9 @@ Returns true if path this starts with path other. ``` Converts a string to a set of PosixFilePermission. -

Source

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

Source

## `strip-ext` ``` clojure @@ -847,7 +856,7 @@ Converts a string to a set of PosixFilePermission. ``` Strips extension via [`split-ext`](#babashka.fs/split-ext). -

Source

+

Source

## `sym-link?` ``` clojure @@ -856,7 +865,7 @@ Strips extension via [`split-ext`](#babashka.fs/split-ext). ``` Determines if `f` is a symbolic link via `java.nio.file.Files/isSymbolicLink`. -

Source

+

Source

## `temp-dir` ``` clojure @@ -865,7 +874,7 @@ Determines if `f` is a symbolic link via `java.nio.file.Files/isSymbolicLink`. ``` Returns `java.io.tmpdir` property as path. -

Source

+

Source

## `unixify` ``` clojure @@ -874,7 +883,7 @@ Returns `java.io.tmpdir` property as path. ``` Returns path as string with Unix-style file separators (`/`). -

Source

+

Source

## `unzip` ``` clojure @@ -888,7 +897,7 @@ Unzips `zip-file` to `dest` directory (default `"."`). Options: * `:replace-existing` - `true` / `false`: overwrite existing files -

Source

+

Source

## `update-file` ``` clojure @@ -903,7 +912,7 @@ Updates the contents of text file [`path`](#babashka.fs/path) using `f` applied Options: * `:charset` - charset of file, default to "utf-8" -

Source

+

Source

## `walk-file-tree` ``` clojure @@ -935,7 +944,7 @@ Returns Path to first executable `program` found in `:paths` `opt`, similar to t When `program` is a relative or absolute path, `:paths` 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. -

Source

+

Source

## `which-all` ``` clojure @@ -945,7 +954,7 @@ Returns Path to first executable `program` found in `:paths` `opt`, similar to t ``` Returns every Path to `program` found in ([`exec-paths`](#babashka.fs/exec-paths)). See [`which`](#babashka.fs/which). -

Source

+

Source

## `windows?` ``` clojure @@ -954,7 +963,7 @@ Returns every Path to `program` found in ([`exec-paths`](#babashka.fs/exec-paths ``` Returns true if OS is Windows. -

Source

+

Source

## `with-temp-dir` ``` clojure @@ -969,7 +978,7 @@ Evaluate body with binding-name bound to a temporary directory. and will be removed with [`delete-tree`](#babashka.fs/delete-tree) on exit from the scope. `options` is a map with the keys as for create-temp-dir. -

Source

+

Source

## `writable?` ``` clojure @@ -1001,7 +1010,7 @@ Writes `bytes` to [`path`](#babashka.fs/path) via `java.nio.file.Files/write`. (fs/write-bytes f (.getBytes (String. "foo"))) ;; overwrites + truncates or creates new file (fs/write-bytes f (.getBytes (String. "foo")) {:append true}) ``` -

Source

+

Source

## `write-lines` ``` clojure @@ -1021,7 +1030,7 @@ Writes `lines`, a seqable of strings to [`path`](#babashka.fs/path) via `java.ni * `:write` (default `true`) * `:append` (default `false`) * or any `java.nio.file.StandardOption`. -

Source

+

Source

## `xdg-cache-home` ``` clojure @@ -1034,7 +1043,7 @@ Path representing the base directory relative to which user-specific non-essenti Returns path based on the value of env-var `XDG_CACHE_HOME` (if set and representing an absolute path), else `(fs/path (fs/home) ".cache")`. When provided, appends `app` to the path. -

Source

+

Source

## `xdg-config-home` ``` clojure @@ -1047,7 +1056,7 @@ Path representing the base directory relative to which user-specific configurati Returns path based on the value of env-var `XDG_CONFIG_HOME` (if set and representing an absolute path), else `(fs/path (fs/home) ".config")`. When provided, appends `app` to the path. -

Source

+

Source

## `xdg-data-home` ``` clojure @@ -1060,7 +1069,7 @@ Path representing the base directory relative to which user-specific data files Returns path based on the value of 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 path. -

Source

+

Source

## `xdg-state-home` ``` clojure @@ -1073,7 +1082,7 @@ Path representing the base directory relative to which user-specific state files Returns path based on the value of 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 path. -

Source

+

Source

## `zip` ``` clojure @@ -1090,4 +1099,4 @@ Zips entry or entries into zip-file. An entry may be a file or * `:root`: directory which will be elided in zip. E.g.: `(fs/zip ["src"] {:root "src"})` * `:path-fn`: a single-arg function from file system path to zip entry path. -

Source

+

Source