pub struct BaseDirectories { /* private fields */ }
Expand description
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").unwrap();
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
.
Implementations§
source§impl BaseDirectories
impl BaseDirectories
sourcepub fn new() -> Result<BaseDirectories, Error>
pub fn new() -> Result<BaseDirectories, Error>
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 asstd::env::home_dir()
; if still not available: return an error.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 not0700
: 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.
sourcepub fn with_prefix<P: AsRef<Path>>(prefix: P) -> Result<BaseDirectories, Error>
pub fn with_prefix<P: AsRef<Path>>(prefix: P) -> Result<BaseDirectories, Error>
Same as new()
, but prefix
is implicitly prepended to
every path that is looked up.
sourcepub fn with_profile<P1, P2>(
prefix: P1,
profile: P2,
) -> Result<BaseDirectories, Error>
pub fn with_profile<P1, P2>( prefix: P1, profile: P2, ) -> Result<BaseDirectories, Error>
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").unwrap();
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
.
sourcepub fn get_runtime_directory(&self) -> Result<&PathBuf, Error>
pub fn get_runtime_directory(&self) -> Result<&PathBuf, Error>
Returns the user-specific runtime directory (set by XDG_RUNTIME_DIR
).
sourcepub fn has_runtime_directory(&self) -> bool
pub fn has_runtime_directory(&self) -> bool
Returns true
if XDG_RUNTIME_DIR
is available, false
otherwise.
sourcepub fn get_config_file<P: AsRef<Path>>(&self, path: P) -> PathBuf
pub fn get_config_file<P: AsRef<Path>>(&self, path: P) -> PathBuf
Like place_config_file()
, but does
not create any directories.
sourcepub fn get_data_file<P: AsRef<Path>>(&self, path: P) -> PathBuf
pub fn get_data_file<P: AsRef<Path>>(&self, path: P) -> PathBuf
Like place_data_file()
, but does
not create any directories.
sourcepub fn get_cache_file<P: AsRef<Path>>(&self, path: P) -> PathBuf
pub fn get_cache_file<P: AsRef<Path>>(&self, path: P) -> PathBuf
Like place_cache_file()
, but does
not create any directories.
sourcepub fn get_state_file<P: AsRef<Path>>(&self, path: P) -> PathBuf
pub fn get_state_file<P: AsRef<Path>>(&self, path: P) -> PathBuf
Like place_state_file()
, but does
not create any directories.
sourcepub fn get_runtime_file<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>
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.
sourcepub fn place_config_file<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>
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.
sourcepub fn place_data_file<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>
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
.
sourcepub fn place_cache_file<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>
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
.
sourcepub fn place_state_file<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>
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
.
sourcepub fn place_runtime_file<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>
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.
sourcepub fn find_config_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>
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
.
sourcepub fn find_config_files<P: AsRef<Path>>(&self, path: P) -> FileFindIterator ⓘ
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.
sourcepub fn find_data_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>
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
.
sourcepub fn find_data_files<P: AsRef<Path>>(&self, path: P) -> FileFindIterator ⓘ
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.
sourcepub fn find_cache_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>
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
.
sourcepub fn find_state_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>
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
.
sourcepub fn find_runtime_file<P: AsRef<Path>>(&self, path: P) -> Option<PathBuf>
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
.
sourcepub fn create_config_directory<P: AsRef<Path>>(
&self,
path: P,
) -> Result<PathBuf>
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.
sourcepub fn create_data_directory<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>
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
.
sourcepub fn create_cache_directory<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>
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
.
sourcepub fn create_state_directory<P: AsRef<Path>>(&self, path: P) -> Result<PathBuf>
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
.
sourcepub fn create_runtime_directory<P: AsRef<Path>>(
&self,
path: P,
) -> Result<PathBuf>
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.
sourcepub fn list_config_files<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>
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
.
sourcepub fn list_config_files_once<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>
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.
sourcepub fn list_data_files<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>
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
.
sourcepub fn list_data_files_once<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>
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.
sourcepub fn list_cache_files<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>
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
.
sourcepub fn list_state_files<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>
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
.
sourcepub fn list_runtime_files<P: AsRef<Path>>(&self, path: P) -> Vec<PathBuf>
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
.
sourcepub fn get_data_home(&self) -> PathBuf
pub fn get_data_home(&self) -> PathBuf
Returns the user-specific data directory (set by XDG_DATA_HOME
).
sourcepub fn get_config_home(&self) -> PathBuf
pub fn get_config_home(&self) -> PathBuf
Returns the user-specific configuration directory (set by
XDG_CONFIG_HOME
).
sourcepub fn get_cache_home(&self) -> PathBuf
pub fn get_cache_home(&self) -> PathBuf
Returns the user-specific directory for non-essential (cached) data
(set by XDG_CACHE_HOME
).
sourcepub fn get_state_home(&self) -> PathBuf
pub fn get_state_home(&self) -> PathBuf
Returns the user-specific directory for application state data
(set by XDG_STATE_HOME
).
sourcepub fn get_data_dirs(&self) -> Vec<PathBuf>
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
).
sourcepub fn get_config_dirs(&self) -> Vec<PathBuf>
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
).
Trait Implementations§
source§impl Clone for BaseDirectories
impl Clone for BaseDirectories
source§fn clone(&self) -> BaseDirectories
fn clone(&self) -> BaseDirectories
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moreAuto Trait Implementations§
impl Freeze for BaseDirectories
impl RefUnwindSafe for BaseDirectories
impl Send for BaseDirectories
impl Sync for BaseDirectories
impl Unpin for BaseDirectories
impl UnwindSafe for BaseDirectories
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)