Struct xdg::BaseDirectories

#[non_exhaustive]
pub struct BaseDirectories {
    pub shared_prefix: PathBuf,
    pub user_prefix: PathBuf,
    pub data_home: Option<PathBuf>,
    pub config_home: Option<PathBuf>,
    pub cache_home: Option<PathBuf>,
    pub state_home: Option<PathBuf>,
    pub data_dirs: Vec<PathBuf>,
    pub config_dirs: Vec<PathBuf>,
    pub runtime_dir: Option<PathBuf>,
}

BaseDirectories allows to look up paths to configuration, data, cache and runtime files in well-known locations according to the X Desktop Group Base Directory specification.

The Base Directory specification defines five kinds of files:

• Configuration files store the application’s settings and are often modified during runtime;
• Data files store supplementary data, such as graphic assets, precomputed tables, documentation, or architecture-independent source code;
• Cache files store non-essential, transient data that provides a runtime speedup;
• State files store logs, history, recently used files and application state (window size, open files, unsaved changes, …);
• Runtime files include filesystem objects such are sockets or named pipes that are used for communication internal to the application. Runtime files must not be accessible to anyone except current user.

Examples

To configure paths for application myapp:

let xdg_dirs = xdg::BaseDirectories::with_prefix("myapp");

To store configuration:

let config_path = xdg_dirs
    .place_config_file("config.ini")
    .expect("cannot create configuration directory");
let mut config_file = File::create(config_path)?;
write!(&mut config_file, "configured = 1")?;

The config.ini file will appear in the proper location for desktop configuration files, most likely ~/.config/myapp/config.ini. The leading directories will be automatically created.

To retrieve supplementary data:

let logo_path = xdg_dirs
    .find_data_file("logo.png")
    .expect("application data not present");
let mut logo_file = File::open(logo_path)?;
let mut logo = Vec::new();
logo_file.read_to_end(&mut logo)?;

The logo.png will be searched in the proper locations for supplementary data files, most likely ~/.local/share/myapp/logo.png, then /usr/local/share/myapp/logo.png and /usr/share/myapp/logo.png.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

shared_prefix: PathBuf

Prefix path appended to all path lookups in system directories as described in BaseDirectories::with_prefix. May be the empty path.

user_prefix: PathBuf

Prefix path appended to all path lookups in user directories as described in BaseDirectories::with_profile. Note that this value already contains shared_prefix as prefix, and is identical to it when constructed with BaseDirectories::with_prefix. May be the empty path.

data_home: Option<PathBuf>

Like BaseDirectories::get_data_home, but without any prefixes applied. Is guaranteed to not be None unless no HOME could be found.

config_home: Option<PathBuf>

Like BaseDirectories::get_config_home, but without any prefixes applied. Is guaranteed to not be None unless no HOME could be found.

cache_home: Option<PathBuf>

Like BaseDirectories::get_cache_home, but without any prefixes applied. Is guaranteed to not be None unless no HOME could be found.

state_home: Option<PathBuf>

Like BaseDirectories::get_state_home, but without any prefixes applied. Is guaranteed to not be None unless no HOME could be found.

data_dirs: Vec<PathBuf>

Like BaseDirectories::get_data_dirs, but without any prefixes applied.

config_dirs: Vec<PathBuf>

Like BaseDirectories::get_config_dirs, but without any prefixes applied.

runtime_dir: Option<PathBuf>

Like BaseDirectories::get_runtime_directory, but without any of the sanity checks on the directory (like permissions).

Implementations

impl BaseDirectories

pub fn new() -> BaseDirectories

Reads the process environment, determines the XDG base directories, and returns a value that can be used for lookup. The following environment variables are examined:

• HOME; if not set: use the same fallback as std::env::home_dir();
• XDG_DATA_HOME; if not set: assumed to be $HOME/.local/share.
• XDG_CONFIG_HOME; if not set: assumed to be $HOME/.config.
• XDG_CACHE_HOME; if not set: assumed to be $HOME/.cache.
• XDG_STATE_HOME; if not set: assumed to be $HOME/.local/state.
• XDG_DATA_DIRS; if not set: assumed to be /usr/local/share:/usr/share.
• XDG_CONFIG_DIRS; if not set: assumed to be /etc/xdg.
• XDG_RUNTIME_DIR; if not accessible or permissions are not 0700: record as inaccessible (can be queried with has_runtime_directory).

As per specification, if an environment variable contains a relative path, the behavior is the same as if it was not set.

pub fn with_prefix<P: AsRef<Path>>(prefix: P) -> BaseDirectories

Same as new(), but prefix is implicitly prepended to every path that is looked up. This is usually the application’s name, preferably in Reverse domain name notation (The spec does not mandate this though, it’s just a convention).

pub fn with_profile<P1, P2>(prefix: P1, profile: P2) -> BaseDirectories

where P1: AsRef<Path>, P2: AsRef<Path>,

Same as with_prefix(), with profile also implicitly prepended to every path that is looked up, but only for user-specific directories.

This allows each user to have mutliple “profiles” with different user-specific data.

For example:

let dirs = BaseDirectories::with_profile("program-name", "profile-name");
dirs.find_data_file("bar.jpg");
dirs.find_config_file("foo.conf");

will find /usr/share/program-name/bar.jpg (without profile-name) and ~/.config/program-name/profile-name/foo.conf.

pub fn get_runtime_directory(&self) -> Result<&PathBuf, Error>

Returns the user-specific runtime directory (set by XDG_RUNTIME_DIR).

pub fn has_runtime_directory(&self) -> bool

Returns true if XDG_RUNTIME_DIR is available, false otherwise.

pub fn get_config_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>

Like place_config_file(), but does not create any directories.

pub fn get_data_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>

Like place_data_file(), but does not create any directories.

pub fn get_cache_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>

Like place_cache_file(), but does not create any directories.

pub fn get_state_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>

Like place_state_file(), but does not create any directories.

pub fn get_runtime_file<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Like place_runtime_file(), but does not create any directories. If XDG_RUNTIME_DIR is not available, returns an error.

pub fn place_config_file<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Given a relative path path, returns an absolute path in XDG_CONFIG_HOME where a configuration file may be stored. Leading directories in the returned path are pre-created; if that is not possible, an error is returned.

pub fn place_data_file<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Like place_config_file(), but for a data file in XDG_DATA_HOME.

pub fn place_cache_file<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Like place_config_file(), but for a cache file in XDG_CACHE_HOME.

pub fn place_state_file<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Like place_config_file(), but for an application state file in XDG_STATE_HOME.

pub fn place_runtime_file<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Like place_config_file(), but for a runtime file in XDG_RUNTIME_DIR. If XDG_RUNTIME_DIR is not available, returns an error.

pub fn find_config_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>

Given a relative path path, returns an absolute path to an existing configuration file, or None. Searches XDG_CONFIG_HOME and then XDG_CONFIG_DIRS.

pub fn find_config_files<P: AsRef<Path>>(&self, path: P) -> FileFindIterator

Given a relative path path, returns an iterator yielding absolute paths to existing configuration files, in XDG_CONFIG_DIRS and XDG_CONFIG_HOME. Paths are produced in order from lowest priority to highest.

pub fn find_data_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>

Given a relative path path, returns an absolute path to an existing data file, or None. Searches XDG_DATA_HOME and then XDG_DATA_DIRS.

pub fn find_data_files<P: AsRef<Path>>(&self, path: P) -> FileFindIterator

Given a relative path path, returns an iterator yielding absolute paths to existing data files, in XDG_DATA_DIRS and XDG_DATA_HOME. Paths are produced in order from lowest priority to highest.

pub fn find_cache_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>

Given a relative path path, returns an absolute path to an existing cache file, or None. Searches XDG_CACHE_HOME.

pub fn find_state_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>

Given a relative path path, returns an absolute path to an existing application state file, or None. Searches XDG_STATE_HOME.

pub fn find_runtime_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>

Given a relative path path, returns an absolute path to an existing runtime file, or None. Searches XDG_RUNTIME_DIR. If XDG_RUNTIME_DIR is not available, returns None.

pub fn create_config_directory<P: AsRef<Path>>( &self, path: P ) -> Result<PathBuf>

Given a relative path path, returns an absolute path to a configuration directory in XDG_CONFIG_HOME. The directory and all directories leading to it are created if they did not exist; if that is not possible, an error is returned.

pub fn create_data_directory<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Like create_config_directory(), but for a data directory in XDG_DATA_HOME.

pub fn create_cache_directory<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Like create_config_directory(), but for a cache directory in XDG_CACHE_HOME.

pub fn create_state_directory<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>

Like create_config_directory(), but for an application state directory in XDG_STATE_HOME.

pub fn create_runtime_directory<P: AsRef<Path>>( &self, path: P ) -> Result<PathBuf>

Like create_config_directory(), but for a runtime directory in XDG_RUNTIME_DIR. If XDG_RUNTIME_DIR is not available, returns an error.

pub fn list_config_files<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>

Given a relative path path, list absolute paths to all files in directories with path path in XDG_CONFIG_HOME and XDG_CONFIG_DIRS.

pub fn list_config_files_once<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>

Like list_config_files, but only the first occurence of every distinct filename is returned.

pub fn list_data_files<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>

Given a relative path path, lists absolute paths to all files in directories with path path in XDG_DATA_HOME and XDG_DATA_DIRS.

pub fn list_data_files_once<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>

Like list_data_files, but only the first occurence of every distinct filename is returned.

pub fn list_cache_files<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>

Given a relative path path, lists absolute paths to all files in directories with path path in XDG_CACHE_HOME.

pub fn list_state_files<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>

Given a relative path path, lists absolute paths to all files in directories with path path in XDG_STATE_HOME.

pub fn list_runtime_files<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>

Given a relative path path, lists absolute paths to all files in directories with path path in XDG_RUNTIME_DIR. If XDG_RUNTIME_DIR is not available, returns an empty Vec.

pub fn get_data_home(&self) -> Option<PathBuf>

Returns the user-specific data directory (set by XDG_DATA_HOME). Is guaranteed to not return None unless no HOME could be found.

pub fn get_config_home(&self) -> Option<PathBuf>

Returns the user-specific configuration directory (set by XDG_CONFIG_HOME or default fallback, plus the prefix and profile if configured). Is guaranteed to not return None unless no HOME could be found.

pub fn get_cache_home(&self) -> Option<PathBuf>

Returns the user-specific directory for non-essential (cached) data (set by XDG_CACHE_HOME or default fallback, plus the prefix and profile if configured). Is guaranteed to not return None unless no HOME could be found.

pub fn get_state_home(&self) -> Option<PathBuf>

Returns the user-specific directory for application state data (set by XDG_STATE_HOME or default fallback, plus the prefix and profile if configured). Is guaranteed to not return None unless no HOME could be found.

pub fn get_data_dirs(&self) -> Vec<PathBuf>

Returns a preference ordered (preferred to less preferred) list of supplementary data directories, ordered by preference (set by XDG_DATA_DIRS or default fallback, plus the prefix if configured).

pub fn get_config_dirs(&self) -> Vec<PathBuf>

Returns a preference ordered (preferred to less preferred) list of supplementary configuration directories (set by XDG_CONFIG_DIRS or default fallback, plus the prefix if configured).

Trait Implementations

impl Clone for BaseDirectories

fn clone(&self) -> BaseDirectories

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for BaseDirectories

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

Formats the value using the given formatter.

impl Default for BaseDirectories

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for BaseDirectories

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for BaseDirectories

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.