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