microxdg

An XDG Base Directory Specification Rust library that aims to be conservative on memory allocation and overall memory footprint.

Usage

Dependency

Add microxdg as a dependency to your Rust project by running the following cargo command in your project directory:

cargo add microxdg

Alternatively, add the following line in the [dependencies] section of your Cargo.toml:

microxdg = "0.2.0"

API

The microxdg API consists in two main structs:

• Xdg, an implementation of the XDG Base Directory Specification;
• XdgApp, an implementation of the XDG Base Directory Specification with extent to application-specific (or project-specific) subdirectories.

Note: the latter's associated functions and methods are a superset of those implemented for Xdg. For this reason, it should be preferred only in case you need access to application-specific subdirectories.

For the complete documentation, consult https://docs.rs/microxdg/latest.

Retrieve user-specific XDG directories

The following example illustrates how to retrieve the user-specific XDG configuration directory:

use microxdg::{Xdg, XdgError};

fn main() -> Result<(), XdgError> {
    let xdg = Xdg::new()?;
    let config_dir = xdg.config()?;

    /* Do something with `config_dir`... */

    Ok(())
}

The Xdg::config method returns the user-specific XDG configuration directory specified by the XDG_CONFIG_HOME environment variable. Falls back to $HOME/.config or /home/$USER/.config if such environment variable is not set, or is set to an empty value.

Returns an error (XdgError) in the following cases:

• the XDG_CONFIG_HOME environment variable is set, but its value represents a relative path;
• the XDG_CONFIG_HOME environment variable is set, but its value represents invalid unicode.

Analogous methods are available for each of the other XDG directories listed in the specification:

• Xdg::cache;
• Xdg::data;
• Xdg::state;
• Xdg::bin;
• Xdg::runtime.

Below a table illustrating the environment variable and corresponding fallbacks for each of the XDG directories:

XDG Base Directory	Environment variable	Fallback - HOME set	Fallback - HOME not set
Cache	XDG_CACHE_HOME	$HOME/.cache	/home/$USER/.cache
Configuration	XDG_CONFIG_HOME	$HOME/.config	/home/$USER/.config
Data	XDG_DATA_HOME	$HOME/.local/share	/home/$USER/.local/share
State	XDG_STATE_HOME	$HOME/.local/state	/home/$USER/.local/state
Bin	XDG_BIN_HOME	$HOME/.local/bin	/home/$USER/.local/bin
Runtime	XDG_RUNTIME_DIR	-	-

Retrieve user-specific XDG application subdirectories

The following example illustrates how to retrieve the user-specific XDG data application subdirectory:

use microxdg::{XdgApp, XdgError};

fn main() -> Result<(), XdgError> {
    let xdg = XdgApp::new("app_name")?;
    let app_data_dir = xdg.app_data()?;

    /* Do something with `app_data_dir`... */

    Ok(())
}

The Xdg::app_data method returns the user-specific XDG data subdirectory for the given application. It uses the XDG directory specified by the XDG_DATA_HOME environment variable, if available. Falls back to $HOME/.local/share/app_name or /home/$USER/.local/share/app_name if such environment variable is not set, or is set to an empty value.

Also, it returns an error (XdgError) in the following cases:

• the XDG_DATA_HOME environment variable is set, but its value represents a relative path;
• the XDG_DATA_HOME environment variable is set, but its value represents invalid unicode.

Analogous methods are available for other XDG application subdirectories:

• Xdg::app_cache;
• Xdg::app_config;
• Xdg::app_state.

Below a table illustrating the environment variable and corresponding fallbacks for each of the XDG directories:

XDG Application Subdirectory	Environment variable	Fallback - HOME set	Fallback - HOME not set
App Cache	XDG_CACHE_HOME	$HOME/.cache/app_name	/home/$USER/.cache/app_name
App Configuration	XDG_CONFIG_HOME	$HOME/.config/app_name	/home/$USER/.config/app_name
App Data	XDG_DATA_HOME	$HOME/.local/share/app_name	/home/$USER/.local/share/app_name
App State	XDG_STATE_HOME	$HOME/.local/state/app_name	/home/$USER/.local/state/app_name

Retrieve user-specific XDG files

The following example illustrates how to retrieve the path to a file contained in the user-specific XDG cache directory:

use microxdg::{XdgApp, XdgError};

fn main() -> Result<(), XdgError> {
    let xdg = Xdg::new()?;
    let cache_file = xdg.cache_file("file_name")?;

    /* Do something with `cache_file`... */

    Ok(())
}

The Xdg::cache_file method returns the path to a user-specific XDG cache file. It uses the XDG directory specified by the XDG_CACHE_HOME environment variable, if available. Falls back to $HOME/.cache/file_name or /home/$USER/.cache/file_name if such environment variable is not set, or is set to an empty value.

Also, it returns an error (XdgError) in the following cases:

• the XDG_CACHE_HOME environment variable is set, but its value represents a relative path;
• the XDG_CACHE_HOME environment variable is set, but its value represents invalid unicode.

Analogous methods are available other XDG directories:

• Xdg::config_file;
• Xdg::data_file;
• Xdg::state_file;
• Xdg::bin_file.

Note: these methods do not guarantee either the path exists or points to a regular file.

Retrieve user-specific XDG application files

The following example illustrates how to retrieve the path to a file contained in the user-specific XDG state application subdirectory:

use microxdg::{XdgApp, XdgError};

fn main() -> Result<(), XdgError> {
    let xdg = XdgApp::new("app_name")?;
    let app_state_file = xdg.app_state_file("file_name")?;

    /* Do something with `app_state_file`... */

    Ok(())
}

The Xdg::app_state_file returns the path to a user-specific XDG application file. It uses the XDG application subdirectory specified by $XDG_STATE_HOME/app_name, if the XDG_STATE_HOME environment variable is available. Falls back to $HOME/.local/state/app_name/file_name or /home/$USER/.local/state/file_name if such environment variable is not set, or is set to an empty value.

Also, it returns an error (XdgError) in the following cases:

• the XDG_STATE_HOME environment variable is set, but its value represents a relative path;
• the XDG_STATE_HOME environment variable is set, but its value represents invalid unicode.

Analogous methods are available for other XDG directories:

• Xdg::app_cache_file;
• Xdg::app_config_file;
• Xdg::app_data_file.

Note: these methods do not guarantee either the path exists or points to a regular file.

Retrieve system-wide, preference-ordered, XDG directories

The following example illustrates how to retireve the system-wide, preference-ordered, XDG data directories:

use microxdg::{Xdg, XdgError};

fn main() -> Result<(), XdgError> {
    let xdg = Xdg::new()?;
    let sys_data_dirs = Xdg::sys_data()?;
  
    /* Do something with `sys_data_dirs`... */
  
    Ok(())
}

The Xdg::sys_data associated function returns the system-wide, preference-ordered, XDG data directories specified by the XDG_DATA_DIRS environment variable. Falls back to /usr/local/share:/usr/share if such environment variable is not set, or is set to an empty value.

Also, it returns an error (XdgError) in the following cases:

• the XDG_DATA_DIRS environment variable is set, but one (or more) path(s) in the colon separated value represents a relative path;
• the XDG_DATA_DIRS environment variable is set, but its value represents invalid unicode.

An analogous method is available for the system-wide XDG configuration directories: Xdg::sys_config.

Below a table illustrating the environment variable and corresponding fallbacks for each of the system-wide, preference-ordered, XDG directories:

XDG Base Directory	Environment variable	Fallback
Configuration	XDG_CONFIG_DIRS	/etc/xdg
Data	XDG_DATA_DIRS	/usr/local/share:/usr/share

Note: the XDG_CONFIG_DIRS and XDG_DATA_DIRS environment variables should be set to a colon separated value, where each entry represents a path to a system XDG directory. The order denotes the importace: the first directory the most important, the last directory the least important.

Retrieve system-wide, preference-ordered, XDG application subdirectories

The following example illustrates how to retrieve the system-wide, preference-ordered, XDG config application subdirectories:

use microxdg::{XdgApp, XdgError};

fn main() -> Result<(), XdgError> {
    let xdg = XdgApp::new("app_name")?;
    let app_sys_config_dirs = xdg.app_sys_config()?;

    /* Do something with `app_sys_config_dirs`... */

    Ok(())
}

The XdgApp::app_sys_config method returns the system-wide, preference-ordered, XDG application configuration subdirectories for the given application. It uses the directories specified by the XDG_CONFIG_DIRS environment variable, if available. Falls back to /etc/xdg/app_name if such environment variable is not set, or is set to an empty value.

Also, it returns an error (XdgError) in the following cases:

• the XDG_CONFIG_DIRS environment variable is set, but one (or more) path(s) in the colon separated value represents a relative path;
• the XDG_CONFIG_DIRS environment variable is set, but its value represents invalid unicode.

An analogous method is available for the system-wide XDG application data subdirectories: XdgApp::app_sys_data.

Below a table illustrating the environment variable and corresponding fallbacks for each of the system-wide, preference-ordered, XDG app subdirectories:

XDG Base Directory	Environment variable	Fallback
Configuration	XDG_CONFIG_DIRS	/etc/xdg/app_name
Data	XDG_DATA_DIRS	/usr/local/share/app_name:/usr/share/app_name

Note: the XDG_CONFIG_DIRS and XDG_DATA_DIRS environment variables should be set to a colon separated value, where each entry represents a path to a system XDG directory. The order denotes the importace: the first directory the most important, the last directory the least important.

Search user-specific XDG files

The following example illustrates how to search a file inside XDG config directories:

use microxdg::{Xdg, XdgError};

fn main() -> Result<(), XdgError> {
    let xdg = Xdg::new()?;
    match xdg.search_config_file("file_name")? {
        Some(config_file) => {
            /* Do something with `config_file`... */
        }
        None => {
            /* Do something else... */
        }
    }

    Ok(())
}

The Xdg::search_config_file method returns an Option<PathBuf>. Its variants are:

• Some(file), in the case the file was found inside one of the XDG configuration directories. The lookup order is:
  • user-specific XDG configuration directory specified by the XDG_CONFIG_HOME environment variable if available, or the corresponding fallbacks if such environment variable is not set or set to an empty value;
  • system-wide XDG configuration directories specified by the XDG_CONFIG_DIRS environment variable if available, or the corresponding fallback if such environment variable is not set or set to an empty value;
• None, in the case the file was not found inside any of the XDG configuration directories (either user-specific or system-wide).

Also, it returns an error (XdgError) in the following cases:

• the XDG_CONFIG_HOME environment variable is set, but its value represents a relative path;
• the XDG_CONFIG_HOME environment variable is set, but its value represents invalid unicode;
• the file was not found inside the user-specific XDG data directory and:
  • the XDG_CONFIG_DIRS environment variable is set, but one (or more) path(s) in the colon separated value represents a relative path;
  • the XDG_CONFIG_DIRS environment variable is set, but its value represents invalid unicode.

Analogous methods are available to search files inside the other XDG directories:

• Xdg::search_cache_file;
• Xdg::search_data_file;
• Xdg::search_state_file;
• Xdg::search_bin_file.

Search user-specific XDG application files

The following example illustrates how to search a file inside XDG data application subdirectories:

use microxdg::{XdgApp, XdgError};

fn main() -> Result<(), XdgError> {
    let xdg = XdgApp::new("app_name");
    match xdg.search_app_data_file("file_name")? {
        Some(app_data_file) => {
            /* Do something with `app_data_file` ... */
        }
        None => {
            /* Do something else... */
        }
    }

    Ok(())
}

The Xdg::search_app_data_file method returns an Option<PathBuf>. Its variants are:

• Some(app_data_file), in the case the file was found inside one of the XDG data subdirectories. The lookup order is:
  • user-specific XDG application data subdirectory specified by the XDG_DATA_HOME environment variable if available, or falls back to $HOME/.local/share/app_name if such environment variable is not set or set to an empty value;
  • system-wide XDG configuration directories specified by the XDG_CONFIG_DIRS environment variable if available, or falls back to /usr/local/share/app_name:/usr/share/app_name if such variable environment is not set or set to an empty value;
• None, in the case the file was not found inside any of the XDG configuration directories (either user-specific or system-wide).

Also, it returns an error (XdgError) in the following cases:

• the XDG_DATA_HOME environment variable is set, but its value represents a relative path;
• the XDG_DATA_HOME environment variable is set, but its value represents invalid unicode;
• the file was not found inside the user-specific XDG data directory and:
  • the XDG_DATA_DIRS environment variable is set, but one (or more) path(s) in the colon separated value represents a relative path;
  • the XDG_DATA_DIRS environment variable is set, but its value represents invalid unicode.

Analogous methods are available to search files inside the other XDG application subdirectories:

• Xdg::search_app_cache_file;
• Xdg::search_app_config_file;
• Xdg::search_app_state_file.