Struct xdg::BaseDirectories [−] [src]

pub struct BaseDirectories {
    // some fields omitted
}

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 four 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;
  • 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:

extern crate xdg;
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 = try!(File::create(config_path));
try!(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 = try!(File::open(logo_path));
let mut logo = Vec::new();
try!(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.

Methods

impl BaseDirectories
[src]

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(); if still not available: panic.
  • 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_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: panic.

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

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

Same as new(), but prefix is implicitly prepended to every path that is looked up.

fn has_runtime_directory(&self) -> bool

Returns true if XDG_RUNTIME_DIR is available, false otherwise.

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

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.

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

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

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

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

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

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

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

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.

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

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

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

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

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

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, panics.

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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, panics.