Struct Xdg 

pub struct Xdg { /* private fields */ }

This strategy implements the XDG Base Directories Specification. It is the most common on Linux, but is increasingly being adopted elsewhere.

This initial example removes all the XDG environment variables to show the strategy’s use of the XDG default directories.

use etcetera::app_strategy::AppStrategy;
use etcetera::app_strategy::AppStrategyArgs;
use etcetera::app_strategy::Xdg;
use std::path::Path;

// Remove the environment variables that the strategy reads from.
unsafe {
std::env::remove_var("XDG_CONFIG_HOME");
std::env::remove_var("XDG_DATA_HOME");
std::env::remove_var("XDG_CACHE_HOME");
std::env::remove_var("XDG_STATE_HOME");
std::env::remove_var("XDG_RUNTIME_DIR");
}

let app_strategy = Xdg::new(AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
}).unwrap();

let home_dir = etcetera::home_dir().unwrap();

assert_eq!(
    app_strategy.home_dir(),
    &home_dir
);
assert_eq!(
    app_strategy.config_dir().strip_prefix(&home_dir),
    Ok(Path::new(".config/frobnicator-plus/"))
);
assert_eq!(
    app_strategy.data_dir().strip_prefix(&home_dir),
    Ok(Path::new(".local/share/frobnicator-plus/"))
);
assert_eq!(
    app_strategy.cache_dir().strip_prefix(&home_dir),
    Ok(Path::new(".cache/frobnicator-plus/"))
);
assert_eq!(
    app_strategy.state_dir().unwrap().strip_prefix(&home_dir),
    Ok(Path::new(".local/state/frobnicator-plus/"))
);
assert_eq!(
    app_strategy.runtime_dir(),
    None
);

This next example gives the environment variables values:

use etcetera::app_strategy::AppStrategy;
use etcetera::app_strategy::AppStrategyArgs;
use etcetera::app_strategy::Xdg;
use std::path::Path;

// We need to conditionally set these to ensure that they are absolute paths both on Windows and other systems.
let config_path = if cfg!(windows) {
    "C:\\my_config_location\\"
} else {
    "/my_config_location/"
};
let data_path = if cfg!(windows) {
    "C:\\my_data_location\\"
} else {
    "/my_data_location/"
};
let cache_path = if cfg!(windows) {
    "C:\\my_cache_location\\"
} else {
    "/my_cache_location/"
};
let state_path = if cfg!(windows) {
    "C:\\my_state_location\\"
} else {
    "/my_state_location/"
};
let runtime_path = if cfg!(windows) {
    "C:\\my_runtime_location\\"
} else {
    "/my_runtime_location/"
};

unsafe {
std::env::set_var("XDG_CONFIG_HOME", config_path);
std::env::set_var("XDG_DATA_HOME", data_path);
std::env::set_var("XDG_CACHE_HOME", cache_path);
std::env::set_var("XDG_STATE_HOME", state_path);
std::env::set_var("XDG_RUNTIME_DIR", runtime_path);
}

let app_strategy = Xdg::new(AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
}).unwrap();

assert_eq!(
    app_strategy.config_dir(),
    Path::new(&format!("{}/frobnicator-plus/", config_path))
);
assert_eq!(
    app_strategy.data_dir(),
    Path::new(&format!("{}/frobnicator-plus/", data_path))
);
assert_eq!(
    app_strategy.cache_dir(),
    Path::new(&format!("{}/frobnicator-plus/", cache_path))
);
assert_eq!(
    app_strategy.state_dir().unwrap(),
    Path::new(&format!("{}/frobnicator-plus/", state_path))
);
assert_eq!(
    app_strategy.runtime_dir().unwrap(),
    Path::new(&format!("{}/frobnicator-plus/", runtime_path))
);

The XDG spec requires that when the environment variables’ values are not absolute paths, their values should be ignored. This example exemplifies this behaviour:

use etcetera::app_strategy::AppStrategy;
use etcetera::app_strategy::AppStrategyArgs;
use etcetera::app_strategy::Xdg;
use std::path::Path;

// Remove the environment variables that the strategy reads from.
unsafe {
std::env::set_var("XDG_CONFIG_HOME", "relative_path/");
std::env::set_var("XDG_DATA_HOME", "./another_one/");
std::env::set_var("XDG_CACHE_HOME", "yet_another/");
std::env::set_var("XDG_STATE_HOME", "./and_another");
std::env::set_var("XDG_RUNTIME_DIR", "relative_path/");
}

let app_strategy = Xdg::new(AppStrategyArgs {
    top_level_domain: "org".to_string(),
    author: "Acme Corp".to_string(),
    app_name: "Frobnicator Plus".to_string(),
}).unwrap();

let home_dir = etcetera::home_dir().unwrap();

// We still get the default values.
assert_eq!(
    app_strategy.config_dir().strip_prefix(&home_dir),
    Ok(Path::new(".config/frobnicator-plus/"))
);
assert_eq!(
    app_strategy.data_dir().strip_prefix(&home_dir),
    Ok(Path::new(".local/share/frobnicator-plus/"))
);
assert_eq!(
    app_strategy.cache_dir().strip_prefix(&home_dir),
    Ok(Path::new(".cache/frobnicator-plus/"))
);
assert_eq!(
    app_strategy.state_dir().unwrap().strip_prefix(&home_dir),
    Ok(Path::new(".local/state/frobnicator-plus/"))
);
assert_eq!(
    app_strategy.runtime_dir(),
    None
);

Implementations

impl Xdg

pub fn new(args: AppStrategyArgs) -> Result<Self, HomeDirError>

Create a new Xdg AppStrategy

Trait Implementations

impl AppStrategy for Xdg

fn home_dir(&self) -> &Path

Gets the home directory of the current user.

fn config_dir(&self) -> PathBuf

Gets the configuration directory for your application.

fn data_dir(&self) -> PathBuf

Gets the data directory for your application.

fn cache_dir(&self) -> PathBuf

Gets the cache directory for your application.

fn state_dir(&self) -> Option<PathBuf>

Gets the state directory for your application. Currently, only the Xdg & Unix strategies support this.

fn runtime_dir(&self) -> Option<PathBuf>

Gets the runtime directory for your application. Currently, only the Xdg & Unix strategies support this.

fn in_config_dir<P: AsRef<OsStr>>(&self, path: P) -> PathBuf

Constructs a path inside your application’s configuration directory to which a path of your choice has been appended.

fn in_data_dir<P: AsRef<OsStr>>(&self, path: P) -> PathBuf

Constructs a path inside your application’s data directory to which a path of your choice has been appended.

fn in_cache_dir<P: AsRef<OsStr>>(&self, path: P) -> PathBuf

Constructs a path inside your application’s cache directory to which a path of your choice has been appended.

fn in_state_dir<P: AsRef<OsStr>>(&self, path: P) -> Option<PathBuf>

Constructs a path inside your application’s state directory to which a path of your choice has been appended.

fn in_runtime_dir<P: AsRef<OsStr>>(&self, path: P) -> Option<PathBuf>

Constructs a path inside your application’s runtime directory to which a path of your choice has been appended. Currently, only the Xdg & Unix strategies support this.

impl Clone for Xdg

fn clone(&self) -> Xdg

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Xdg

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for Xdg

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Xdg

fn cmp(&self, other: &Xdg) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Xdg

fn eq(&self, other: &Xdg) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Xdg

fn partial_cmp(&self, other: &Xdg) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for Xdg

impl StructuralPartialEq for Xdg