xdg-basedir

Repository

https://github.com/mario-goulart/xdg-basedir

Description

Implementation of the XDG Base Directory Specification.

Implementation notes:

The directory represented by the path returned by the xdg-*-home procedures is created by default if it does not exist (this behavior can be disabled by binding the create-directory? keyword parameter of the procedures to #f).
The xdg-* procedures by default set their corresponding environment variables with their return value in case they are not set. This behavior can be disabled by binding the set-environment? keyword parameter of the procedures to #f).

API

[parameter] (xdg-home [default=(get-environment-variable "HOME")])

The xdg-*-home procedures will use the value of this parameter to determine the user home directory to use.

This parameter can be changed to deploy XDG directories under the home directory of a different user without changing the HOME environment variable. Example:

(parameterize ((xdg-home "/home/another-user"))
  (do-something-with (xdg-config-home)))

[procedure] (xdg-cache-home #!key (create-directory? #t) (set-environment? #t))

Return the value of the XDG_CACHE_HOME environment variable if it is set and is not empty. Otherwise return the path to .cache/ under the user home directory.

By default, the directory represented by the path returned by this procedure is created if it does not exist. This behavior can be disabled by binding the create-directory? keyword parameter of this procedure to #f).

By default, this procedure sets the XDG_CACHE_HOME environment variable with its return value in case the environment variable is not set. This behavior can be disabled by binding the set-environment? keyword parameter to #f).

[procedure] (xdg-config-home #!key (create-directory? #t) (set-environment? #t))

Return the value of the XDG_CONFIG_HOME environment variable if it is set and is not empty. Otherwise return the path to .config/ under the user home directory.

By default, this procedure sets the XDG_CONFIG_HOME environment variable with its return value in case the environment variable is not set. This behavior can be disabled by binding the set-environment? keyword parameter to #f).

[procedure] (xdg-data-home #!key (create-directory? #t) (set-environment? #t))

Return the value of the XDG_DATA_HOME environment variable if it is set and is not empty. Otherwise return the path to .local/share/ under the user home directory.

By default, this procedure sets the XDG_DATA_HOME environment variable with its return value in case the environment variable is not set. This behavior can be disabled by binding the set-environment? keyword parameter to #f).

[procedure] (xdg-state-home #!key (create-directory? #t) (set-environment? #t))

Return the value of the XDG_STATE_HOME environment variable if it is set and is not empty. Otherwise return the path to .local/state/ under the user home directory.

By default, this procedure sets the XDG_STATE_HOME environment variable with its return value in case the environment variable is not set. This behavior can be disabled by binding the set-environment? keyword parameter to #f).

[procedure] (xdg-data-dirs #!key (set-environment? #t))

Return the value of the XDG_DATA_DIRS environment variable if it is set and is not empty. Otherwise return "/usr/local/share/:/usr/share/".

By default, this procedure sets the XDG_DATA_DIRS environment variable with its return value in case the environment variable is not set. This behavior can be disabled by binding the set-environment? keyword parameter to #f).

[procedure] (xdg-config-dirs #!key (set-environment? #t))

Return the value of the XDG_CONFIG_DIRS environment variable if it is set and is not empty. Otherwise return "/etc/xdg/".

By default, this procedure sets the XDG_CONFIG_DIRS environment variable with its return value in case the environment variable is not set. This behavior can be disabled by binding the set-environment? keyword parameter to #f).

[procedure] (xdg-runtime-dir #!key (set-environment? #t))

Return the value of the XDG_RUNTIME_DIR environment variable if it is set and is not empty. Otherwise return #f.

By default, this procedure sets the XDG_RUNTIME_DIR environment variable with its return value in case the environment variable is not set. This behavior can be disabled by binding the set-environment? keyword parameter to #f).

License

 Copyright (c) 2025, Mario Domenech Goulart
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
 3. The name of the authors may not be used to endorse or promote products
    derived from this software without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
 IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Version history

1.0.0 (2025-02-16)

Initial release.