xdg Rust Library

To use rust-xdg in your Rust project, add the xdg crate to your Cargo.toml dependencies. This library provides implementations for the XDG Base Directory specification.

[dependencies]
xdg = "^2.6"

You can iterate over files within the XDG directories using list_* methods.

• list_config_files(prefix: &str) -> Vec<PathBuf>: Lists all configuration files found in all configuration directories (including system-wide XDG_CONFIG_DIRS).
• list_config_files_once(prefix: &str) -> Vec<PathBuf>: Lists configuration files but only from the primary XDG_CONFIG_HOME (ignoring system-wide directories).
• list_data_files(prefix: &str) -> Vec<PathBuf>: Lists data files across all data directories.

// Example: listing all config files
let files = xd.list_config_files(".");

To locate files that already exist on the system, use the find_* methods. These methods search through user-specific directories and system-wide directories (defined by XDG_CONFIG_DIRS or XDG_DATA_DIRS) in order of priority.

• find_config_file(path): Searches XDG_CONFIG_HOME and XDG_CONFIG_DIRS.
• find_data_file(path): Searches XDG_DATA_HOME and XDG_DATA_DIRS.
• find_cache_file(path): Searches XDG_CACHE_HOME.
• find_state_file(path): Searches XDG_STATE_HOME.
• find_runtime_file(path): Searches XDG_RUNTIME_DIR.

// Example: Finding a data file like a logo
let logo_path = xdg_dirs
    .find_data_file("logo.png")
    .expect("application data not present");

The runtime directory (set by XDG_RUNTIME_DIR) is used for non-persistent files like sockets or named pipes.

• get_runtime_directory(): Returns the path if XDG_RUNTIME_DIR is set and is secure (permissions must be 0700). Returns an Error if the directory is missing or insecure.
• has_runtime_directory(): A boolean check to see if a valid runtime directory is available.
• place_runtime_file(path): Places a file in the runtime directory.
• find_runtime_file(path): Finds an existing file in the runtime directory.

Use the get_* methods to retrieve the path for a specific file within the application's dedicated directory. Unlike find_*, these methods target the specific directory assigned to your application (using the prefix provided during BaseDirectories initialization) and do not search system-wide directories.

Available methods:

• get_config_file(name: &str) -> Result<PathBuf, Error>
• get_data_file(name: &str) -> Result<PathBuf, Error>
• get_cache_file(name: &str) -> Result<PathBuf, Error>

// Example: getting the path for a specific app config file
let file = xd.get_config_file("myapp/user_config.file").unwrap();

Use the create_*_directory methods to ensure a specific subdirectory exists within the appropriate XDG home. These methods create the directory and all necessary parent components.

• create_config_directory(path)
• create_data_directory(path)
• create_cache_directory(path)
• create_state_directory(path)
• create_runtime_directory(path)

Use BaseDirectories to look up paths for configuration, data, cache, state, and runtime files according to the XDG Base Directory specification.

There are three main ways to initialize it:

1. new(): Uses standard environment variables (e.g., HOME, XDG_CONFIG_HOME).
2. with_prefix(prefix): Automatically prepends a prefix (usually your application name) to all looked-up paths.
3. with_profile(prefix, profile): Prepends both a prefix and a profile name to user-specific directories, allowing multiple user profiles for the same application.

// Standard initialization
let xdg_dirs = xdg::BaseDirectories::new();

// Initialization with an application prefix (e.g., "myapp")
let xdg_dirs = xdg::BaseDirectories::with_prefix("myapp");

// Initialization with prefix and profile (e.g., "myapp" and "user1")
let dirs = xdg::BaseDirectories::with_profile("myapp", "user1");

You can list files within specific XDG paths using list_*_files.

• list_config_files(path) / list_data_files(path): Returns all files in directories matching the path, searching both user and system directories.
• list_config_files_once(path) / list_data_files_once(path): Similar to the above, but returns only the first occurrence of any distinct filename (useful if the same config exists in both /etc/xdg and ~/.config).
• list_cache_files(path) / list_state_files(path): Lists files in the user-specific cache or state directories.

The BaseDirectories struct provides access to standard XDG base directories (like CONFIG, DATA, CACHE, STATE, XDG_CONFIG_HOME, etc.) on Unix-like systems and Redox. It allows you to locate and interact with standard filesystem locations used by desktop environments.

Key components:

• BaseDirectories: The main entry point for accessing directory paths.
• FileFindIterator: An iterator used for finding files within these directories.
• Error: A specialized error type for base directory operations.

use xdg::BaseDirectories;

// Example usage (conceptual based on exported types):
// let base_dirs = BaseDirectories::new(...);
// let config_dir = base_dirs.config_dir();