Merge branch 'next' into datarewrite-structures

1 files changed, 73 insertions, 0 deletions

diff --git a/doc/ref/general/util-path.texi b/doc/ref/general/util-path.texi
new file mode 100644
index 00000000..ba78a828
--- /dev/null
+++ b/doc/ref/general/util-path.texi
@@ -0,0 +1,73 @@
+@node Path Utilities
+@section Path Utilities
+
+An extended path library for Guile. This library builds upon the path
+utilities provided by @xref{File System,,,guile}, but adds
+manipulation procedures. These procedures should work no matter what
+the systems directory delimiter is, even though this documentation
+uses ``/'' for its examples.
+
+Provided by the module @code{(hnh util path)}.
+
+@defun path-absolute? string
+Alias of @code{absolute-file-name?} from Guile.
+@end defun
+
+@defun path-append path paths ...
+Joins all strings into a path, squeezing duplicated delimiters, but
+ensuring that all delimiters that are needed are there.
+
+Note that delimiters embedded inside the string, which aren't first or
+last in a substring (or are the only thing in a string) are
+kept. Meaning that
+@example
+(path-append "/" "hello") ⇒ "/hello"
+(path-append "/usr/local/bin" "cmd") ⇒ "/usr/local/bin/cmd"
+@end example
+@end defun
+
+
+@defun path-join lst
+@lisp
+(apply path-append lst)
+@end lisp
+@end defun
+
+
+@defun path-split path
+Splits path into a list of components.
+The first component will be @code{""} if path is absolute.
+@end defun
+
+
+@defun filename-extension filename
+Returns the extension of the filename without a leading period, or the
+empty string if none exists.
+
+@example
+(filename-extension "file.tar.gz")
+⇒ "gz"
+@end example
+@end defun
+
+@defun realpath path
+Equivalent of realpath(3). Absolute file names are returned as is,
+while relative filenames gets expanded to absolute filenames.
+@end defun
+
+@defun relative-to base path
+Returns @var{path} as a relative path relative to @var{base}.
+
+base must be non-empty
+@example
+(relative-to "/some" "/some/path")
+;; ⇒ "path"
+
+(relative-to "/some" "/other/path/")
+;; ⇒ "../path"
+
+(relative-to "/a/b/c" "/a/b")
+;; ⇒ "/a/b"
+@end example
+
+@end defun