一个 XDG 基目录规范 的 Rust 库，旨在在内存分配和整体内存占用方面保持保守。

用法

依赖项

通过在项目目录中运行以下 cargo 命令将 microxdg 添加为 Rust 项目的依赖项：

cargo add microxdg

或者，在 Cargo.toml 的 [dependencies] 部分添加以下行：

microxdg = "0.1.2"

API

microxdg API 由两个主要的 struct 构成：

• Xdg，实现了 XDG 基目录规范；
• XdgApp，实现了 XDG 基目录规范，并扩展到应用程序特定的（或项目特定的）子目录。

注意：后者的相关函数和方法是 Xdg 实现的子集。因此，仅在需要访问应用程序特定子目录的情况下才应优先选择。

检索用户特定的 XDG 目录

以下示例说明如何检索用户特定的 XDG 配置 目录

use microxdg::{Xdg, XdgError};

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

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

    Ok(())
}

Xdg::config 方法返回由环境变量 XDG_CONFIG_HOME 指定的用户特定的 XDG 配置目录。如果没有设置该环境变量或设置为空值，则回退到 $HOME/.config 或 /home/$USER/.config。

在以下情况下返回错误（XdgError）：

• XDG_CONFIG_HOME 环境变量已设置，但其值代表相对路径；
• XDG_CONFIG_HOME 环境变量已设置，但其值代表无效的 Unicode。

规范中列出的其他 XDG 目录均有类似的方法。

• Xdg::缓存;
• Xdg::数据;
• Xdg::状态;
• Xdg::运行时;
• Xdg::执行.

以下表格展示了每个Xdg目录的环境变量及其回退值

获取用户特定的Xdg应用子目录

以下示例说明了如何获取特定用户的Xdg 数据 应用子目录

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(())
}

Xdg::app_data方法返回指定应用的特定用户Xdg数据子目录。如果设置了环境变量XDG_DATA_HOME，它将使用Xdg目录。如果该环境变量未设置或设置为空值，则回退到$HOME/.local/share/app_name或/home/$USER/.local/share/app_name。

在以下情况下，它将返回错误（XdgError）：

• XDG_DATA_HOME环境变量已设置，但其值表示相对路径；
• XDG_DATA_HOME环境变量已设置，但其值表示无效的Unicode。

对于其他Xdg应用子目录也有类似的方法。

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

以下表格展示了每个Xdg目录的环境变量及其回退值

获取用户特定的Xdg文件

以下示例说明了如何获取包含在特定用户Xdg 缓存 目录中的文件的路径

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(())
}

Xdg::cache_file方法返回特定用户Xdg缓存文件的路径。如果设置了环境变量XDG_CACHE_HOME，它将使用Xdg目录。如果该环境变量未设置或设置为空值，则回退到$HOME/.cache/file_name或/home/$USER/.cache/file_name。

在以下情况下，它将返回错误（XdgError）：

• XDG_CACHE_HOME环境变量已设置，但其值表示相对路径；
• XDG_CACHE_HOME环境变量已设置，但其值表示无效的Unicode。

对于其他Xdg目录也有类似的方法。

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

注意：这些方法不能保证路径存在或指向一个常规文件。

获取用户特定的Xdg应用文件

以下示例说明了如何获取包含在特定用户Xdg 状态 应用子目录中的文件的路径

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(())
}

Xdg::app_state_file 函数返回一个 用户特定 的 XDG 应用程序文件的路径。如果设置了环境变量 XDG_STATE_HOME，它将使用由 $XDG_STATE_HOME/app_name 指定的 XDG 应用程序子目录。如果没有设置该环境变量，或者其值为空，将回退到 $HOME/.local/state/app_name/file_name 或 /home/$USER/.local/state/file_name。

在以下情况下，它将返回错误（XdgError）：

• 环境变量 XDG_STATE_HOME 已设置，但其值代表一个相对路径；
• 环境变量 XDG_STATE_HOME 已设置，但其值表示无效的 Unicode。

对于其他 XDG 目录也提供了类似的方法。

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

注意：这些方法不能保证路径存在或指向一个常规文件。

检索系统范围内的、按偏好排序的 XDG 目录

以下示例说明了如何检索系统范围内的、按偏好排序的 XDG 数据 目录

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(())
}

与 Xdg::sys_data 相关联的函数返回由环境变量 XDG_DATA_DIRS 指定的系统范围内的、按偏好排序的 XDG 数据目录。如果没有设置该环境变量，或者其值为空，将回退到 /usr/local/share:/usr/share。

在以下情况下，它将返回错误（XdgError）：

• 环境变量 XDG_DATA_DIRS 已设置，但冒号分隔的值中的一个（或多个）路径表示一个相对路径；
• 环境变量 XDG_DATA_DIRS 已设置，但其值表示无效的 Unicode。

对于系统范围内的 XDG 配置目录也有类似的方法：Xdg::sys_config。

以下表格说明了系统范围内的、按偏好排序的每个 XDG 目录的环境变量及其回退值

注意：环境变量 XDG_CONFIG_DIRS 和 XDG_DATA_DIRS 应设置为一个冒号分隔的值，其中每个条目代表一个系统 XDG 目录的路径。顺序表示重要性：第一个目录最重要，最后一个目录最不重要。

检索系统范围内的、按偏好排序的 XDG 应用程序子目录

以下示例说明了如何检索系统范围内的、按偏好排序的 XDG 配置 应用程序子目录

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(())
}

XdgApp::app_sys_config 方法返回给定应用程序的系统范围内的、按偏好排序的 XDG 应用程序配置子目录。如果可用，它将使用环境变量 XDG_CONFIG_DIRS 指定的目录。如果没有设置该环境变量，或者其值为空，将回退到 /etc/xdg/app_name。

在以下情况下，它将返回错误（XdgError）：

• 环境变量 XDG_CONFIG_DIRS 已设置，但冒号分隔的值中的一个（或多个）路径表示一个相对路径；
• 环境变量 XDG_CONFIG_DIRS 已设置，但其值表示无效的 Unicode。

对于系统范围内的 XDG 应用程序数据子目录也有类似的方法：XdgApp::app_sys_data。

以下表格说明了系统范围内的、按偏好排序的每个 XDG 应用程序子目录的环境变量及其回退值

注意：环境变量 XDG_CONFIG_DIRS 和 XDG_DATA_DIRS 应设置为一个冒号分隔的值，其中每个条目代表一个系统 XDG 目录的路径。顺序表示重要性：第一个目录最重要，最后一个目录最不重要。

搜索用户特定的 XDG 文件

以下示例说明了如何在 XDG 配置 目录中搜索文件

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(())
}

方法 Xdg::search_config_file 返回一个 Option<PathBuf>。其变体有

• Some(file)，如果文件在某个 XDG 配置目录中找到。查找顺序是
  • 用户特定 XDG 配置目录，由环境变量 XDG_CONFIG_HOME 指定，如果存在，否则使用相应的回退值；
  • 系统范围 XDG 配置目录，由环境变量 XDG_CONFIG_DIRS 指定，如果存在，否则使用相应的回退值；
• None，如果文件在任何一个 XDG 配置目录（无论是 用户特定 还是 系统范围）中均未找到。

在以下情况下，它将返回错误（XdgError）：

• XDG_CONFIG_HOME 环境变量已设置，但其值代表相对路径；
• 环境变量 XDG_CONFIG_HOME 已设置，但其值表示无效的 Unicode；
• 文件在 用户特定 XDG 数据目录中未找到；
  • 环境变量 XDG_CONFIG_DIRS 已设置，但冒号分隔的值中的一个（或多个）路径表示一个相对路径；
  • 环境变量 XDG_CONFIG_DIRS 已设置，但其值表示无效的 Unicode。

还有类似的方法可以用于在其他的 XDG 目录中搜索文件

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

搜索用户特定的 XDG 应用程序文件

以下示例说明如何在 XDG 数据 应用程序子目录中搜索文件

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(())
}

方法 Xdg::search_app_data_file 返回一个 Option<PathBuf>。其变体有

• Some(app_data_file)，如果文件在某个 XDG 数据子目录中找到。查找顺序是
  • 用户特定 XDG 应用程序数据子目录，由环境变量 XDG_DATA_HOME 指定，如果存在，否则回退到 $HOME/.local/share/app_name；
  • 系统范围 XDG 配置目录，由环境变量 XDG_CONFIG_DIRS 指定，如果存在，否则回退到 /usr/local/share/app_name:/usr/share/app_name；
• None，如果文件在任何一个 XDG 配置目录（无论是 用户特定 还是 系统范围）中均未找到。

在以下情况下，它将返回错误（XdgError）：

• XDG_DATA_HOME环境变量已设置，但其值表示相对路径；
• 环境变量 XDG_DATA_HOME 已设置，但其值表示无效的 Unicode；
• 文件在 用户特定 XDG 数据目录中未找到；
  • 环境变量 XDG_DATA_DIRS 已设置，但冒号分隔的值中的一个（或多个）路径表示一个相对路径；
  • 环境变量 XDG_DATA_DIRS 已设置，但其值表示无效的 Unicode。

还有类似的方法可以用于在其他的 XDG 应用程序子目录中搜索文件

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