2021-02-05

(sph filesystem)

part of sph-lib

module name

(sph filesystem)

exported bindings

procedure: call-with-directory path proc ->
string procedure:{directory-port -> any} -> any
procedure: copy-file-recursive source target #:stop-on-error #:display-errors #:copy-file #:ensure-directory ->
string:path string:path keyword-options ... -> unspecified
copy source to target. copies the whole directory structure if source is a directory.
target must include the first new filename, for example source:/etc/dircolors target:/tmp/dircolors.
the copy-file procedure {source-path target-path -> boolean} can be replaced, to symlink instead, for example.
#:stop-on-error boolean
#:display-errors boolean
#:copy-file procedure
procedure: directory-fold path proc init ->
string procedure:{string any -> any} any -> any
fold over entries in directory
procedure: directory-list name [select? entry<?] ->
Return the list of the names of files contained in directory NAME
The returned list
of file names is sorted according to ENTRY<?, which defaults to
`string-locale<?'. Return #f when NAME is unreadable or is not a
directory.
procedure: directory-list-full path [select?] ->
string procedure ... -> (string ...)
get a list of full paths to directory entries
procedure: directory-prefix-tree start [directory-tree] ->
-> (string/list ...)
get directory contents as a prefix list.
example
(directory-prefix-tree (list \"/usr/local/bin\" \"/usr/local/lib\"))
-> (\"/usr\" (\"local\" (\"bin\" \"lib\")))
procedure: directory-reference? file-path ->
string -> boolean
test if given string designates a directory reference, either \".\" or \"..\"
can be used as a filter to directory-listing procedures.
procedure: directory-tree path #:select? #:enter? #:stat ->
string [procedure:{any -> boolean}] -> (string:path ...)
string procedure -> (string ...)
results in a list of all paths under path, excluding path and the directory references \".\" and \"..\"
procedure: directory-tree-each proc path [max-depth] ->
procedure:{string stat-object -> unspecified} string [integer] -> unspecified
procedure: directory-tree-leaf-directories start #:select? #:enter? #:stat ->
string:path -> (string ...)
return a list of all directories under start that dont have any directory in their entries
procedure: directory? path ->
test if path exists and is a directory
procedure: dotfile? name ->
string -> boolean
checks if name is non-empty and begins with a dot.
useful for matching hidden files or the directory references . and ..
procedure: ensure-directory-structure path ->
string -> boolean:exists
try to create any directories of path that do not exist.
true if the path exists either because it has been created or otherwise.
every path part is considered a directory
procedure: ensure-directory-structure-and-new-mode path mode ->
string -> boolean
like ensure-directory-structure but also sets the file mode/permissions for new directories.
the mode is influenced by the umask
procedure: ensure-trailing-slash str ->
string -> string
procedure: filename-extension a ->
string -> string
results in the last dot-separated part of string or the empty-string if no such part exists
procedure: filesystem-glob path ->
procedure: fold-directory-tree proc init path [max-depth] ->
::
procedure:{string:current-path guile-stat-object:stat-info any:previous-result -> any} any string [integer] {string/path -> boolean} ...
->
any:last-procedure-result
*deprecated* in favor of (ice-9 ftw) filesystem-fold.
fold over directory-tree under path, possibly limited by max-depth.
the directory-references \".\" and \"..\" are ignored.
call to proc is (proc full-path stat-info previous-result/init)
procedure: get-unique-path path [suffix] ->
string [string] -> string
if the given path with suffix already exists, insert a string between path and the suffix
until a path is found that doesnt yet exist. suffix is empty by default.
may append a period and base32 number.
examples
\"/tmp/abc\" -> \"/tmp/abc.1\"
\"/tmp/abc\" \".scm\" -> \"/tmp/abc.1.scm\"
procedure: list->path a ->
(string ...) -> string
for a full path prepend an empty string to the input. this is analogous to the output of path ->
list
procedure: mtime-difference paths ... ->
string ... -> integer
get the mtimes for paths and subtract from the first mtime all subsequent.
at least one file has changed if the number is not zero
procedure: path->full-path path [realpath?] ->
string -> string
uses \"getcwd\" to complete relative paths.
with \"getcwd\" the basename can be a symlink but all other parts have symlinks resolved.
the environment variable PWD is not used because it is not usually updated when the process changes directory
procedure: path->list path ->
string -> list
parse a string representation of a filesystem path to a list of its parts.
an empty string as the first element in the list stands for the root directory.
removes unnecessary slashes.
example input/output
\"/b\" -> (\"\" \"b\")
\"b\" -> (\"b\")
procedure: path-append first-a a ... ->
string ... -> string
combine string representations of filesystem paths regardless of leading or trailing slashes of the parts
procedure: path-append* first-a a ... ->
string ... -> string
like path-append but also removes redundant slashes in the middle of the given parts
procedure: path-directories a ->
string -> (string:parent-path ...)
creates a list of the full paths of all directories above the given path
procedure: poll-watch paths events proc min-interval [max-interval] ->
(string ...) (symbol ...) {diff file-descriptors stat-info -> unspecified} milliseconds [milliseconds] -> unspecified
observe stat information of multiple files (which can be directories)
by checking for events of change (which are specified as names of stat object accessors, for example stat:mtime, without the stat: prefix)
and call proc if any of those changes have occurred. the diff passed to proc is a result of stat-diff.
the files are checked in intervals with sizes between min-interval and max-interval,
automatically adjusting the interval size to match change frequency
procedure: readlink* path ->
string -> string
like readlink but also resolves symlinks to symlinks until a non-symlink is found or a target does not exist
procedure: realpath* path ->
string -> false/string
resolves the directory references \".\" and \"..\" as well as symlinks in the given path and removes unnecessary slashes.
named realpath* because it does not use the posix realpath because guile currently does not include it.
the foreign function interface could be an alternative
procedure: remove-filename-extension name [fn-extensions all?] ->
string [(string)] [boolean] -> string
remove specific, all or the last filename-extension from a string.
filename-extension: period characters-except-period ...
procedure: remove-trailing-slash a ->
string -> string
remove any trailing slashes
procedure: search-load-path path [load-paths] ->
gives the first match of a relative-path in load-paths or false.
all paths in load-paths must end with a \"/\".
searches in guiles %load-path by default
procedure: stat-accessor->stat-field-name a ->
utility for functions working with file change events and stat-records
procedure: stat-diff stat-info-a stat-info-b accessors ->
stat stat (procedure ...) -> (#(accessor field-value-a field-value-b)/#f ...)
find the difference between two guile stat objects.
map accessors, stat:mtime for example, to vectors for fields which differ between two stat objects
procedure: stat-diff->accessors stat-info-a stat-info-b accessors ->
stat stat (procedure ...) -> (stat-accessor ...)
find the difference between two guile stat objects.
filter accessors, stat:mtime for example, for fields which do not differ between two stat objects
procedure: stat-field-name->stat-accessor a ->
symbol -> guile-stat-accessor
a guile-stat-accessor is for example stat:mtime, and the argument is as symbol for the part after stat:, in this case mtime.
utility for functions working with file change events and stat-records
procedure: system-temp-dir ->
returns the value of the %TEMP% environment variable on windows, /tmp otherwise.
(port-filename (tmpfile)) returns #f, tmpnam is deprecated,
mkstmp! does not choose the path - currently no alternative found