From a2c3802be5301048fb899bc51b8935943daf73fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Thu, 7 Sep 2023 18:04:27 +0200
Subject: Add documentation and tests for xdg basedir.

---
 doc/ref/guile.texi             |  1 +
 doc/ref/guile/xdg-basedir.texi | 62 ++++++++++++++++++++++++++++++++++++++++++
 tests/test/xdg-basedir.scm     | 58 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 121 insertions(+)
 create mode 100644 doc/ref/guile/xdg-basedir.texi
 create mode 100644 tests/test/xdg-basedir.scm

diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi
index a6c5ebe4..f32dca65 100644
--- a/doc/ref/guile.texi
+++ b/doc/ref/guile.texi
@@ -8,6 +8,7 @@
 @include guile/util-path.texi
 @include guile/util-config.texi
 @include guile/base64.texi
+@include guile/xdg-basedir.texi
 @include guile/web.texi
 @include guile/vcomponent.texi
 
diff --git a/doc/ref/guile/xdg-basedir.texi b/doc/ref/guile/xdg-basedir.texi
new file mode 100644
index 00000000..cdcf179b
--- /dev/null
+++ b/doc/ref/guile/xdg-basedir.texi
@@ -0,0 +1,62 @@
+@node XDG Base Directory
+@section XDG Base Directory
+
+Implementation of the XDG Base Directory Specification
+@url{https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html}, v0.8.
+
+It's recommended to include this module with a symbol prefix:
+
+@example
+(use-modules ((xdg basedir) :prefix xdg-)
+
+(xdg-data-dirs)
+⇒ ("/usr/local/share" "/usr/share")
+@end example
+
+The users home directory is fetched from the environment variable @env{HOME}.
+
+
+@defun data-home
+@findex XDG_DATA_HOME
+@env{XDG_DATA_HOME}, usually @file{~/.local/share}.
+@end defun
+
+@defun config-home
+@findex XDG_CONFIG_HOME
+@env{XDG_CONFIG_HOME}, usually @file{~/.config}.
+@end defun
+
+@defun state-home
+@findex XDG_STATE_HOME
+@env{XDG_STATE_HOME}, usually @file{~/.local/state}.
+@end defun
+
+@defun data-dirs
+@findex XDG_DATA_DIRS
+@env{XDG_DATA_DIRS}, split into a list.
+
+Defaults to @code{("/usr/local/share" "/usr/share")}.
+@end defun
+
+@defun config-dirs
+@findex XDG_CONFIG_DIRS
+@env{XDG_CONFIG_DIRS} as a list, usually @code{("/etc/xdg")}.
+
+Defaults to @file{/etc/xdg}.
+@end defun
+
+@defun cache-home
+@findex XDG_CACHE_HOME
+@env{XDG_CACHE_HOME}, usually @file{~/.cache}.
+@end defun
+
+@defun runtime_dir
+@findex XDG_RUNTIME_DIR
+If @env{XDG_RUNTIME_DIR} is set, than that is used. Otherwise a
+warning message is printed to stderr and @file{/tmp} is returned.
+
+The standard also stipulates a few things about permissons for this
+directory. These are currently not checked.
+
+Systemd usually sets this value to @file{/run/user/$(id -u)}.
+@end defun
diff --git a/tests/test/xdg-basedir.scm b/tests/test/xdg-basedir.scm
new file mode 100644
index 00000000..682c1347
--- /dev/null
+++ b/tests/test/xdg-basedir.scm
@@ -0,0 +1,58 @@
+(define-module (test xdg-basedir)
+  :use-module (srfi srfi-64)
+  :use-module ((xdg basedir) :prefix xdg-)
+  :use-module (srfi srfi-88)
+  :use-module ((hnh util env) :select (let-env))
+  )
+
+
+(let-env ((HOME "/home/user")
+          (XDG_DATA_HOME #f)
+          (XDG_CONFIG_HOME #f)
+          (XDG_STATE_HOME #f)
+          (XDG_DATA_DIRS #f)
+          (XDG_CONFIG_DIRS #f)
+          (XDG_CACHE_HOME #f)
+          (XDG_RUNTIME_DIR #f))
+ (test-group "Defaults"
+   (test-equal "XDG_DATA_HOME" "/home/user/.local/share"
+     (xdg-data-home))
+   (test-equal "XDG_CONFIG_HOME" "/home/user/.config"
+     (xdg-config-home))
+   (test-equal "XDG_STATE_HOME" "/home/user/.local/state"
+     (xdg-state-home))
+   (test-equal "XDG_DATA_DIRS" (xdg-data-dirs)
+     '("/usr/local/share" "/usr/share"))
+   (test-equal "XDG_CONFIG_DIRS" '("/etc/xdg")
+     (xdg-config-dirs))
+   (test-equal "XDG_CACHE_HOME" "/home/user/.cache"
+     (xdg-cache-home))
+   (let ((warning
+          (with-error-to-string
+            (lambda ()
+              (test-equal "XDG_RUNTIME_DIR"
+                "/tmp" (xdg-runtime-dir))))))
+     (test-assert "The warning actually contains something"
+       (< 0 (string-length warning)))))
+
+ (test-group "Custom values"
+   (let-env ((XDG_DATA_HOME "/a"))
+            (test-equal "XDG_DATA_HOME" "/a" (xdg-data-home)))
+   (let-env ((XDG_CONFIG_HOME "/b"))
+            (test-equal "XDG_CONFIG_HOME" "/b" (xdg-config-home)))
+   (let-env ((XDG_STATE_HOME "/c"))
+            (test-equal "XDG_STATE_HOME" "/c" (xdg-state-home)))
+   (let-env ((XDG_DATA_DIRS "/d:/e"))
+            (test-equal "XDG_DATA_DIRS" '("/d" "/e") (xdg-data-dirs)))
+   (let-env ((XDG_CONFIG_DIRS "/f:/g"))
+            (test-equal "XDG_CONFIG_DIRS" '("/f" "/g") (xdg-config-dirs)))
+   (let-env ((XDG_CACHE_HOME "/h"))
+            (test-equal "XDG_CACHE_HOME" "/h" (xdg-cache-home)))
+   (let ((warning
+          (with-error-to-string
+            (lambda ()
+              (let-env ((XDG_RUNTIME_DIR "/i"))
+                       (test-equal "XDG_RUNTIME_DIR" "/i" (xdg-runtime-dir)))))))
+     (test-assert "No error was emitted"
+       (string-null? warning)))))
+
-- 
cgit v1.2.3