master 709e1e5 3/3: New function xdg-state-home

[Stefan Kangas]

branch: master
commit 709e1e59f0f4db24580566f5ca661e730afbf9a2
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>

    New function xdg-state-home
    
    * lisp/xdg.el (xdg-state-home): New function.  This returns
    $XDG_STATE_HOME according to the XDG Base Directory Specification
    version 0.8 (08th May 2021).
---
 etc/NEWS    |  8 ++++++++
 lisp/xdg.el | 17 +++++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/etc/NEWS b/etc/NEWS
index 73f9b2a..f6d36f1 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -296,6 +296,14 @@ Use 'exif-parse-file' and 'exif-field' instead.
 
 * Lisp Changes in Emacs 29.1
 
+** XDG support
+
+*** New function 'xdg-state-home' returns $XDG_STATE_HOME.
+This new location, introduced in the XDG Base Directory Specification
+version 0.8 (8th May 2021), "contains state data that should persist
+between (application) restarts, but that is not important or portable
+enough to the user that it should be stored in $XDG_DATA_HOME".
+
 +++
 ** New macro 'with-delayed-message'.
 This macro is like 'progn', but will output the specified message if
diff --git a/lisp/xdg.el b/lisp/xdg.el
index 1f9fa67..75c8bce 100644
--- a/lisp/xdg.el
+++ b/lisp/xdg.el
@@ -61,6 +61,23 @@
   "Return the base directory for user specific data files."
   (xdg--dir-home "XDG_DATA_HOME" "~/.local/share"))
 
+(defun xdg-state-home ()
+  "Return the base directory for user-specific state data.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+  \"The $XDG_STATE_HOME contains state data that should persist
+  between (application) restarts, but that is not important or
+  portable enough to the user that it should be stored in
+  $XDG_DATA_HOME.  It may contain:
+
+  * actions history (logs, history, recently used files, …)
+
+  * current state of the application that can be reused on a
+    restart (view, layout, open files, undo history, …)\""
+  (xdg--dir-home "XDG_STATE_HOME" "~/.local/state"))
+
 (defun xdg-runtime-dir ()
   "Return the value of $XDG_RUNTIME_DIR."
   (getenv "XDG_RUNTIME_DIR"))