Re: xdg-directories.el

["francisco.colaco@gmail.com" <francisco.colaco@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 1864 bytes --]

Noam,

You were right about the bug.  When I created the user-emacs-<domain>-dir
libraries, which contained by default the subdirectory "emacs", I forgot to
take it from the xdg-get-user-file.  Needless to say, I have only
remembered of creating the user-emacs-<domain>-dir variables right before I
commited.  I have been using the library for months without a flaw.

So the bug is now corrected.  Thanks for the heads up.

About the stability of the specification: according to the XDG Web site,
the last version of the specification dates from 2010.  That is six years
of no modifications.  Seems to be pretty stable now.  Maybe it is time for
Emacs to start the adoption of the XDG Base Dir Spec and separate the files.

A .emacs.d/init.el could be a fallback for user-init-file, as .emacs is
today.  Also, maybe in Windows the xdg-<domain>-dir variables could take
other values and not the defaults I hardwired.  As Windows is really not
what I use, the package is pending suggestions of improvement.

As to the API, should the locate-user-emacs-<domain>-file be renamed?
locate-user-emacs-file has the NEW-NAME OLD-NAME parameters, and creates
unconditionally the directory when OLD-NAME is not passed.

  Francisco Colaço

2016-09-06 22:49 GMT+01:00 Noam Postavsky <npostavs@users.sourceforge.net>:

> Last time this was proposed
> (https://debbugs.gnu.org/cgi/bugreport.cgi?bug=583) there was some
> skepticism about the stability of such standards.
>
> On Tue, Sep 6, 2016 at 11:24 AM, francisco.colaco@gmail.com
> <francisco.colaco@gmail.com> wrote:
> >> (locate-user-emacs-config-file "init.el")
> >> "/home/francisco.colaco/.config/emacs/emacs/init.el"
> [...]
> > ~/.config/emacs/init.el (the result of "(locate-user-emacs-config-file
> > "init.el")
>
> Is the double emacs/emacs/ in the first case a typo?
>

[-- Attachment #1.2: Type: text/html, Size: 2640 bytes --]

[-- Attachment #2: xdg-directories.el --]
[-- Type: text/x-emacs-lisp, Size: 7744 bytes --]

;;; xdg-directories.el --- XDG directory specification

;; Copyright (C) 2016  Francisco Miguel Colaço

;; Author: Francisco Miguel Colaço <francisco.colaco@gmail.com>
;; Keywords: XDG, directory, cache, config

;;; Commentary:
;;;
;;; XDG-DIRECTORIES contains functions to locate user Emacs files, in
;;; accordance to the XDG Base Directory Specification.
;;;
;;; There are different domains to the files, as they are broken into
;;; config, data, cache and runtime.  We advise the users of this
;;; package to look at the aforementioned specification to learn the
;;; differences of the domains.
;;;
;;; The locate-* functions are to be used by package writers.  User
;;; Emacs configuration, data and cache files can then be segregated
;;; into their own directories, making it simple to migrate
;;; configurations among several machines --- since the files that are
;;; unnecessary, being cached files, could easily not be transmitted.
;;;
;;; This package is released under the GNU General Public License,
;;; version 3.0 or, at your choice, above.  One may read the GNU
;;; General Public License at the GNU Web site, at http://www.gnu.org
;;;

;;; Code:

(require 's)


(defgroup xdg-directories
    ()
  "XDG Directory Specification"
  :group 'environment
  :link '(emacs-library-link "xdg-directories"))


(defun xdg-get-path (domain &optional path)
  "Return the directory at DOMAIN, with an optional PATH relative to it."
  (let ((dir (s-chomp (shell-command-to-string (concat "xdg-user-dir " domain)))))
    (if path
        (expand-file-name path dir)
        dir)))


(defcustom xdg-data-home
  (or (getenv "XDG_DATA_HOME") (expand-file-name "~/.local/share"))
  "The base directory relative to which user specific data files
  should be stored."
  :group 'xdg-directories
  :type 'directory)


(defcustom xdg-config-home
  (or (getenv "XDG_CONFIG_HOME") (expand-file-name "~/.config"))
  "The base directory relative to which user specific
  configuration files should be stored."
  :group 'xdg-directories
  :type 'directory)


(defcustom xdg-cache-home
  (or (getenv "XDG_CACHE_HOME") (expand-file-name "~/.cache"))
  "The base directory relative to which user specific
  non-essential data files should be stored."
  :group 'xdg-directories
  :type 'directory)


(defcustom xdg-runtime-dir
  (getenv "XDG_RUNTIME_DIR")
  "The directory where files that pertain only to this session
  are stored.  These files can be erased when the application quits
  or the user logs out."
  :group 'xdg-directories
  :type 'directory)


(defcustom user-emacs-data-home
  (expand-file-name "emacs" xdg-data-home)
  "The base directory relative to which user Emacs specific data
  files should be stored."
  :group 'xdg-directories
  :type 'directory)


(defcustom user-emacs-config-home
  (expand-file-name "emacs" xdg-config-home)
  "The base directory relative to which user Emacs specific
  configuration files should be stored."
  :group 'xdg-directories
  :type 'directory)


(defcustom user-emacs-cache-home
  (expand-file-name "emacs" xdg-cache-home)
  "The base directory relative to which user Emacs specific
  non-essential data files should be stored."
  :group 'xdg-directories
  :type 'directory)


(defcustom user-emacs-runtime-dir
  (expand-file-name "emacs" xdg-runtime-dir)
  "The directory where Emacs files that pertain only to this session
  are stored.  These files can be erased when the application quits
  or the user logs out."
  :group 'xdg-directories
  :type 'directory)


(defcustom user-desktop-directory
  (xdg-get-path "DESKTOP")
  "The desktop directory."
  :group 'xdg-directories
  :type 'directory)


(defcustom user-download-directory
  (xdg-get-path "DOWNLOAD")
  "The directory where the user stores his downloaded files by default."
  :group 'xdg-directories
  :type 'directory)


(defcustom user-templates-directory
  (xdg-get-path "TEMPLATES")
  "The directory where the user stores his templates."
  :group 'xdg-directories
  :type 'directory)


(defcustom user-public-share-directory
  (xdg-get-path "PUBLICSHARE")
  "The directory where the user stores his shared files."
  :group 'xdg-directories
  :type 'directory)


(defcustom user-documents-directory
  (xdg-get-path "DOCUMENTS")
  "The directory where the user stores his documents."
  :group 'xdg-directories
  :type 'directory)


(defcustom user-music-directory
  (xdg-get-path "MUSIC")
  "The directory where the user stores his music."
  :group 'xdg-directories
  :type 'directory)


(defcustom user-pictures-directory
  (xdg-get-path "PICTURES")
  "The directory where the user stores his pictures."
  :group 'xdg-directories
  :type 'directory)


(defcustom user-videos-directory
  (xdg-get-path "VIDEOS")
  "The directory where the user stores his videos."
  :group 'xdg-directories
  :type 'directory)


(defun xdg-get-user-file (filename directory &optional create-parent-dirs)
  "Locate FILENAME under DIRECTORY, wherther it exists or not.

If CREATE-PARENT-DIRS is T, the parent directories are created.

Returns the complete file path, so it can be chained."
  (let ((file (expand-file-name filename directory)))
    ;; Create any parent directories, if so requested.
    (if create-parent-dirs
      (unless (file-exists-p directory)
        (make-directory directory t)))
    ;; Return the name of the file with the given path.
    file))


(defun locate-user-emacs-cache-file (filename &optional create-parent-dirs)
  "Locate a cache file named FILENAME.

The file may exist or not under the user Emacs cache dir (under
XDG-CACHE-HOME/emacs).  The path of the file is returned
regardless of it's existence.

If CREATE-PARENT-DIRS is t, then the directory and its parent
dirs will be created in case they are not found."
  (xdg-get-user-file filename user-emacs-cache-home create-parent-dirs))


(defun locate-user-emacs-config-file (filename &optional create-parent-dirs)
  "Locate a config file named FILENAME.

The file may exist or not under the user Emacs config dir (under
XDG-CONFIG-HOME/emacs).  The path of the file is returned
regardless of it's existence.

If CREATE-PARENT-DIRS is t, then the directory and its parent
dirs will be created in case they are not found."
  (xdg-get-user-file filename user-emacs-config-home create-parent-dirs))


(defun locate-user-emacs-data-file (filename &optional create-parent-dirs)
  "Locate a data file named FILENAME.

The file may exist or not under the user Emacs data dir (under
XDG-DATA-HOME/emacs).  The path of the file is returned
regardless of it's existence.

If CREATE-PARENT-DIRS is t, then the directory and its parent
dirs will be created in case they are not found."
  (xdg-get-user-file filename user-emacs-data-home create-parent-dirs))


(defun locate-user-emacs-runtime-file (filename &optional create-parent-dirs)
  "Locate a runtime file named FILENAME.

The file may exist or not under the user Emacs runtime dir (under
XDG-RUNTIME-DIR/emacs).  The path of the file is returned
regardless of it's existence.

If CREATE-PARENT-DIRS is t, then the directory and its parent
dirs will be created in case they are not found."
  (xdg-get-user-file filename user-emacs-runtime-dir create-parent-dirs))


(defun locate-user-document-file (filename)
  "Locate a document file named FILENAME.

The file may exist or not under the user Emacs documents
dir (which is predetermined by this package using operating
system tools or, if found lacking, sensible defaults).  The path
of the file is returned regardless of it's existence.

If CREATE-PARENT-DIRS is t, then the directory and its parent
dirs will be created in case they are not found."
  (expand-file-name filename user-documents-directory))


(provide 'xdg-directories)
;;; xdg-directories.el ends here