An XDG Base Directory Specification Rust library that aims to be conservative on memory allocation and overall memory footprint.
GPL-3.0 License
An XDG Base Directory Specification Rust library that aims to be conservative on memory allocation and overall memory footprint.
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.1.2"
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 withNote: 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.
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:
XDG_CONFIG_HOME
environment variable is set, but its value representsXDG_CONFIG_HOME
environment variable is set, but its value representsAnalogous methods are available for each of the other XDG directories listed in the specification:
Xdg::cache
;Xdg::data
;Xdg::state
;Xdg::runtime
;Xdg::exec
.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 |
Runtime | XDG_RUNTIME_DIR |
- | - |
Executable | - | $HOME/.local/bin |
/home/$USER/.local/bin |
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:
XDG_DATA_HOME
environment variable is set, but its value representsXDG_DATA_HOME
environment variable is set, but its value representsAnalogous 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 |
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:
XDG_CACHE_HOME
environment variable is set, but its value representsXDG_CACHE_HOME
environment variable is set, but its value representsAnalogous methods are available other XDG directories:
Xdg::config_file
;Xdg::data_file
;Xdg::state_file
.Note: these methods do not guarantee either the path exists or points to a regular file.
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:
XDG_STATE_HOME
environment variable is set, but its value representsXDG_STATE_HOME
environment variable is set, but its value representsAnalogous 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.
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:
XDG_DATA_DIRS
environment variable is set, but one (or more) path(s)XDG_DATA_DIRS
environment variable is set, but its value representsAn 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
andXDG_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.
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:
XDG_CONFIG_DIRS
environment variable is set, but one (or more) path(s)XDG_CONFIG_DIRS
environment variable is set, but its value representsAn 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
andXDG_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.
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 XDGXDG_CONFIG_HOME
environment variable if available, or the correspondingXDG_CONFIG_DIRS
environment variable if available, or the correspondingNone
, in the case the file was not found inside any of the XDGAlso, it returns an error (XdgError
) in the following cases:
XDG_CONFIG_HOME
environment variable is set, but its value representsXDG_CONFIG_HOME
environment variable is set, but its value representsXDG_CONFIG_DIRS
environment variable is set, but one (or more) path(s)XDG_CONFIG_DIRS
environment variable is set, but its value representsAnalogous methods are available to search files inside the other XDG directories:
Xdg::search_cache_file
;Xdg::search_data_file
;Xdg::search_state_file
.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 XDGXDG_DATA_HOME
environment variable if available, or falls back to$HOME/.local/share/app_name
if such environment variable is not set orXDG_CONFIG_DIRS
environment variable if available, or falls back to/usr/local/share/app_name:/usr/share/app_name
if such variableNone
, in the case the file was not found inside any of the XDGAlso, it returns an error (XdgError
) in the following cases:
XDG_DATA_HOME
environment variable is set, but its value representsXDG_DATA_HOME
environment variable is set, but its value representsXDG_DATA_DIRS
environment variable is set, but one (or more) path(s)XDG_DATA_DIRS
environment variable is set, but its value representsAnalogous 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
.