<div align="center"> <h1 align="center"><code>microxdg</code></h1>

</div>

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 ea