2017-08-27

(sph filesystem)

part of sph-lib

highlights are: directory-tree-paths, ensure-directory-structure, ensure-trailing-slash, remove-filename-extension, path-append

bindings

import name

(sph filesystem)

exports

call-with-directory

procedure

signature

path proc ->

string procedure:{directory-port -> any} -> any

copy-file-recursive

procedure

signature

source destination #:stop-on-error #:display-errors #:copy-file #:ensure-directory ->

description

copy source to become destination.

if source is a directory, copy the whole directory structure to destination

directory-fold

procedure

signature

path proc init ->

directory-list

procedure

signature

name [select? entry<?] ->

description

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.

directory-list-full

procedure

signature

path [select?] ->

string procedure ... -> (string ...)

directory-prefix-tree

procedure

signature

start [directory-tree] ->

-> (string/list ...)

description

example

(directory-prefix-tree (list "/usr/local/bin" "/usr/local/lib"))

-> ("/usr" ("local" ("bin" "lib")))

directory-reference?

procedure

signature

file-path ->

string -> boolean

description

test if given string designates a directory reference, either "." or ".."

can be used as a filter to directory-listing procedures.

directory-tree

procedure

signature

path #:select? #:enter? #:stat ->

string [procedure:{any -> boolean}] -> (string:path ...)

string procedure -> (string ...)

description

results in a list of all paths under path, excluding path and the directory references "." and ".."

directory-tree-each

procedure

signature

proc path [max-depth] ->

procedure:{string stat-object -> unspecified} string [integer] -> unspecified

directory-tree-leaf-directories

procedure

signature

start #:select? #:enter? #:stat ->

string:path -> (string ...)

directory?

procedure

signature

path ->

description

test if path exists and is a directory

dotfile?

procedure

signature

name ->

string -> boolean

description

checks if name is non-empty and begins with a dot

ensure-directory-structure

procedure

signature

path ->

string -> boolean:exists

description

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

ensure-directory-structure-and-new-mode

procedure

signature

path mode ->

string -> boolean

description

like ensure-directory-structure but also sets the file mode/permissions for new directories.

the mode is influenced by the umask

ensure-trailing-slash

procedure

signature

str ->

string -> string

filename-extension

procedure

signature

a ->

string -> string

description

results in the last dot-separated part of string or the empty-string if no such part exists

fold-directory-tree

procedure

signature

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

description

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)

last

procedure

signature

pair ->

description

Return the last element of the non-empty, finite list PAIR.

list->path

procedure

signature

a ->

(string ...) -> string

for a full path prepend an empty string to the input. this is analogous to the output of path ->

description

list

make-path-unique

procedure

signature

path [suffix] ->

string [string] -> string

description

if the given path with suffix already exists, insert a string between path and the suffix

so that file name is unique in its directory. suffix is empty by default.

eventually inserts a period and a base32 number.

examples

"/tmp/abc" -> "/tmp/abc.1"

"/tmp/abc" ".scm" -> "/tmp/abc.1.scm"

mtime-difference

procedure

signature

paths ... ->

string ... -> integer

description

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

path->full-path

procedure

signature

path [realpath?] ->

string -> string

description

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 automatically updated when the process changes directory

path->list

procedure

signature

path ->

string -> list

description

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

path-append

procedure

signature

first-arg args ... ->

string ... -> string

description

combine string representations of filesystem paths.

the arguments don't need to have leading or trailing slashes.

use this if redundant slashes in the middle of parts are irrelevant or

don't occur, otherwise use path-append*.

the complexity of joining strings to paths is easily underestimated.

path-append*

procedure

signature

first-arg args ... ->

description

like path-append, but also removes redundant slashes in the middle of the parts to append.

path-directories

procedure

signature

a ->

string -> (string:parent-path ...)

description

creates a list of the full paths of all directories above the given path

poll-watch

procedure

signature

paths events proc min-interval [max-interval] ->

(string ...) (symbol ...) {diff file-descriptors stat-info ->} milliseconds [milliseconds] ->

description

observe stat information of multiple files (which may be directories)

by checking for events of change (which are the name of stat-record 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 need.

readlink*

procedure

signature

path ->

string -> string

description

like readlink but also resolves symlinks to symlinks until a non-symlink is found or a target does not exist

realpath*

procedure

signature

path ->

string -> false/string

description

resolves the directory references "." and ".." as well as symlinks 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

remove-filename-extension

procedure

signature

name [fn-extensions all?] ->

string [(string)] [boolean] -> string

description

remove specific, all or the last filename-extension from a string.

filename-extension: period characters-except-period ...

remove-trailing-slash

procedure

signature

a ->

description

remove trailing slashes if existant, otherwise result in a

search-load-path

procedure

signature

path [load-paths] ->

description

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

stat-accessor->stat-field-name

procedure

signature

a ->

description

utility for functions working with file change events and stat-records

stat-diff

procedure

signature

stat-info-1 stat-info-2 accessors ->

-> ((vector accessor field-value-1 field-value-2)/#f ...)

description

find the difference between two stat-records.

map accessors (stat:mtime for example) to vectors for fields which differ between two stat-records.

stat-diff->accessors

procedure

signature

stat-info-1 stat-info-2 accessors ->

-> (stat-accessor ...)

description

find the difference between two stat-records.

filter accessors (stat:mtime for example) for fields which do not differ between two stat-records.

stat-field-name->stat-accessor

procedure

signature

a ->

symbol -> guile-stat-accessor

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.

utility for functions working with file change events and stat-records


tags: programming guile documentation library scheme sph-lib filesystem sph-filesystem