Merge branch 'master' of git.savannah.gnu.org:/srv/git/emacs into feature/pgtk

1 files changed, 86 insertions, 17 deletions

diff --git a/lisp/xdg.el b/lisp/xdg.el
index 0bdfd114c48..05fc3d711aa 100644
--- a/lisp/xdg.el
+++ b/lisp/xdg.el
@@ -41,39 +41,108 @@
 ;; XDG Base Directory Specification
 ;; https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
 
-(defmacro xdg--dir-home (environ default-path)
-  (declare (debug (stringp stringp)))
-  (let ((env (make-symbol "env")))
-    `(let ((,env (getenv ,environ)))
-       (if (or (null ,env) (not (file-name-absolute-p ,env)))
-           (expand-file-name ,default-path)
-         ,env))))
+(defun xdg--dir-home (environ default-path)
+  (let ((env (getenv environ)))
+    (if (or (null env) (not (file-name-absolute-p env)))
+        (expand-file-name default-path)
+      env)))
 
 (defun xdg-config-home ()
-  "Return the base directory for user specific configuration files."
+  "Return the base directory for user specific configuration files.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+    \"$XDG_CONFIG_HOME defines the base directory relative to
+    which user-specific configuration files should be stored.
+    If $XDG_CONFIG_HOME is either not set or empty, a default
+    equal to $HOME/.config should be used.\""
   (xdg--dir-home "XDG_CONFIG_HOME" "~/.config"))
 
 (defun xdg-cache-home ()
-  "Return the base directory for user specific cache files."
+  "Return the base directory for user specific cache files.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+    \"$XDG_CACHE_HOME defines the base directory relative to
+    which user-specific non-essential data files should be
+    stored.  If $XDG_CACHE_HOME is either not set or empty, a
+    default equal to $HOME/.cache should be used.\""
   (xdg--dir-home "XDG_CACHE_HOME" "~/.cache"))
 
 (defun xdg-data-home ()
-  "Return the base directory for user specific data files."
+  "Return the base directory for user specific data files.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+    \"$XDG_DATA_HOME defines the base directory relative to which
+    user-specific data files should be stored.  If $XDG_DATA_HOME is
+    either not set or empty, a default equal to $HOME/.local/share
+    should be used.\""
   (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."
+  "Return the value of $XDG_RUNTIME_DIR.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+    \"$XDG_RUNTIME_DIR defines the base directory relative to
+    which user-specific non-essential runtime files and other
+    file objects (such as sockets, named pipes, ...) should be
+    stored.\""
   (getenv "XDG_RUNTIME_DIR"))
 
 (defun xdg-config-dirs ()
-  "Return the config directory search path as a list."
+  "Return the config directory search path as a list.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+    \"$XDG_CONFIG_DIRS defines the preference-ordered set of base
+    directories to search for configuration files in addition to
+    the $XDG_CONFIG_HOME base directory.  The directories in
+    $XDG_CONFIG_DIRS should be seperated with a colon ':'.
+
+    \"If $XDG_CONFIG_DIRS is either not set or empty, a value equal to
+    /etc/xdg should be used.\""
   (let ((env (getenv "XDG_CONFIG_DIRS")))
     (if (or (null env) (string= env ""))
         '("/etc/xdg")
       (parse-colon-path env))))
 
 (defun xdg-data-dirs ()
-  "Return the data directory search path as a list."
+  "Return the data directory search path as a list.
+
+According to the XDG Base Directory Specification version
+0.8 (8th May 2021):
+
+    \"$XDG_DATA_DIRS defines the preference-ordered set of base
+    directories to search for data files in addition to the
+    $XDG_DATA_HOME base directory.  The directories in
+    $XDG_DATA_DIRS should be seperated with a colon ':'.
+
+    \"If $XDG_DATA_DIRS is either not set or empty, a value equal
+    to /usr/local/share/:/usr/share/ should be used.\""
   (let ((env (getenv "XDG_DATA_DIRS")))
     (if (or (null env) (string= env ""))
         '("/usr/local/share/" "/usr/share/")
@@ -109,7 +178,7 @@ file:///foo/bar.jpg"
         "_DIR=\""
         (group-n 2 (or "/" "$HOME/") (*? (or (not (any "\"")) "\\\"")))
         "\""))
-  "Regexp matching non-comment lines in xdg-user-dirs config files.")
+  "Regexp matching non-comment lines in `xdg-user-dirs' config files.")
 
 (defvar xdg-user-dirs nil
   "Alist of directory keys and values.")
@@ -131,7 +200,7 @@ This should be called at the beginning of a line."
       (when (and k v) (cons k (xdg--substitute-home-env v))))))
 
 (defun xdg--user-dirs-parse-file (filename)
-  "Return alist of xdg-user-dirs from FILENAME."
+  "Return alist of `xdg-user-dirs' from FILENAME."
   (let (elt res)
     (when (file-readable-p filename)
       (with-temp-buffer
@@ -208,8 +277,8 @@ Optional argument GROUP defaults to the string \"Desktop Entry\"."
   "Partition VALUE into elements delimited by unescaped semicolons."
   (let (res)
     (setq value (string-trim-left value))
-    (dolist (x (split-string (replace-regexp-in-string "\\\\;" "\0" value) ";"))
-      (push (replace-regexp-in-string "\0" ";" x) res))
+    (dolist (x (split-string (string-replace "\\;" "\0" value) ";"))
+      (push (string-replace "\0" ";" x) res))
     (when (null (string-match-p "[^[:blank:]]" (car res))) (pop res))
     (nreverse res)))