From 232a13b3704bd424b216a63a8d82575f26bd63e4 Mon Sep 17 00:00:00 2001 From: Marco Radocchia Date: Tue, 4 Jul 2023 23:52:58 +0200 Subject: [PATCH] Updated documentation and `README.md`. --- README.md | 106 +++++++++++++++++++++++++++++++++++++++++++++++++++++ src/app.rs | 36 ++++++++++++++---- src/lib.rs | 23 +++++++++--- 3 files changed, 151 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 8a6db90..2714bb4 100644 --- a/README.md +++ b/README.md @@ -296,3 +296,109 @@ for each of the system-wide, preference-ordered, XDG app subdirectories: > 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. + +## Search user-specific XDG files + +The following example illustrates how to search a file inside XDG **config** +directories: +```rust +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`. Its variants +are: +- `Some(file)`, in the case the file was found inside one of the XDG + configuration directories. The lookup order is: + - _user-specific_ XDG configuration directory specified by the + `XDG_CONFIG_HOME` environment variable if available, or the corresponding + fallbacks if such environment variable is not set or set to an empty value; + - _system-wide_ XDG configuration directories specified by the + `XDG_CONFIG_DIRS` environment variable if available, or the corresponding + fallback if such environment variable is not set or set to an empty value; +- `None`, in the case the file was **not** found inside any of the XDG + configuration directories (either _user-specific_ or _system-wide_). + +Also, it returns an error (`XdgError`) in the following cases: +- the `XDG_CONFIG_HOME` environment variable is set, but its value represents + a relative path; +- the `XDG_CONFIG_HOME` environment variable is set, but its value represents + invalid unicode; +- the file was **not** found inside the _user-specific_ XDG data directory and: + - the `XDG_CONFIG_DIRS` environment variable is set, but one (or more) path(s) + in the colon separated value represents a relative path; + - the `XDG_CONFIG_DIRS` environment variable is set, but its value represents + invalid unicode. + +Analogous methods are available to search files inside the other XDG +directories: +- `Xdg::search_cache_file`; +- `Xdg::search_data_file`; +- `Xdg::search_state_file`. + +## Search user-specific XDG application files + +The following example illustrates how to search a file inside XDG **data** +application subdirectories: +```rust +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`. Its +variants are: +- `Some(app_data_file)`, in the case the file was found inside one of the XDG + data subdirectories. The lookup order is: + - _user-specific_ XDG application data subdirectory specified by the + `XDG_DATA_HOME` environment variable if available, or falls back to + `$HOME/.local/share/app_name` if such environment variable is not set or + set to an empty value; + - _system-wide_ XDG configuration directories specified by the + `XDG_CONFIG_DIRS` environment variable if available, or falls back to + `/usr/local/share/app_name:/usr/share/app_name` if such variable + environment is not set or set to an empty value; +- `None`, in the case the file was **not** found inside any of the XDG + configuration directories (either _user-specific_ or _system-wide_). + +Also, it returns an error (`XdgError`) in the following cases: +- the `XDG_DATA_HOME` environment variable is set, but its value represents + a relative path; +- the `XDG_DATA_HOME` environment variable is set, but its value represents + invalid unicode; +- the file was **not** found inside the _user-specific_ XDG data directory and: + - the `XDG_DATA_DIRS` environment variable is set, but one (or more) path(s) + in the colon separated value represents a relative path; + - the `XDG_DATA_DIRS` environment variable is set, but its value represents + invalid unicode. + +Analogous 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`. diff --git a/src/app.rs b/src/app.rs index 7007c15..fc186e9 100644 --- a/src/app.rs +++ b/src/app.rs @@ -298,8 +298,8 @@ impl XdgApp { /// # Errors /// /// This method returns an error in the following cases: - /// - the `XDG_CONFIG_DIRS` environment variable is set, but its value represents a relative - /// path; + /// - the `XDG_CONFIG_DIRS` environment variable is set, but one (or more) path(s) in the + /// colon separated value represents a relative path; /// - the `XDG_CONFIG_DIRS` environment variable is set, but its value represents invalid /// unicode. /// @@ -331,8 +331,8 @@ impl XdgApp { /// # Errors /// /// This method returns an error in the following cases: - /// - the `XDG_DATA_DIRS` environment variable is set, but its value represents a relative - /// path; + /// - the `XDG_DATA_DIRS` environment variable is set, but one (or more) path(s) in the colon + /// separated value represents a relative path; /// - the `XDG_DATA_DIRS` environment variable is set, but its value represents invalid /// unicode. /// @@ -913,7 +913,12 @@ impl XdgApp { /// This method returns an error in the following cases: /// - the `XDG_CONFIG_HOME` environment variable is set, but its value represents a relative /// path; - /// - the `XDG_CONFIG_HOME` environment variable is set to invalid unicode. + /// - the `XDG_CONFIG_HOME` environment variable is set to invalid unicode; + /// - `file` was **not** found inside the _user-specific_ XDG config directory and: + /// - the `XDG_CONFIG_DIRS` environment variable is set, but one (or more) path(s) in the + /// colon separated value represents a relative path; + /// - the `XDG_CONFIG_DIRS` environment variable is set, but its value represents invalid + /// unicode. /// /// # Examples /// @@ -955,7 +960,12 @@ impl XdgApp { /// This method returns an error in the following cases: /// - the `XDG_DATA_HOME` environment variable is set, but its value represents a relative /// path; - /// - the `XDG_DATA_HOME` environment variable is set to invalid unicode. + /// - the `XDG_DATA_HOME` environment variable is set to invalid unicode; + /// - `file` was **not** found inside the _user-specific_ XDG data directory and: + /// - the `XDG_DATA_DIRS` environment variable is set, but one (or more) path(s) in the + /// colon separated value represents a relative path; + /// - the `XDG_DATA_DIRS` environment variable is set, but its value represents invalid + /// unicode. /// /// # Examples /// @@ -1168,7 +1178,12 @@ impl XdgApp { /// - the `XDG_CONFIG_HOME` environment variable is set, but its value represents a relative /// path; /// - the `XDG_CACHE_HOME` environment variable is set, but its value represents invalid - /// unicode. + /// unicode; + /// - `file` was **not** found inside the _user-specific_ XDG config directory and: + /// - the `XDG_CONFIG_DIRS` environment variable is set, but one (or more) path(s) in the + /// colon separated value represents a relative path; + /// - the `XDG_CONFIG_DIRS` environment variable is set, but its value represents invalid + /// unicode. /// /// # Examples /// @@ -1208,7 +1223,12 @@ impl XdgApp { /// - the `XDG_DATA_HOME` environment variable is set, but its value represents a relative /// path; /// - the `XDG_CACHE_HOME` environment variable is set, but its value represents invalid - /// unicode. + /// unicode; + /// - `file` was **not** found inside the _user-specific_ XDG data directory and: + /// - the `XDG_DATA_DIRS` environment variable is set, but one (or more) path(s) in the + /// colon separated value represents a relative path; + /// - the `XDG_DATA_DIRS` environment variable is set, but its value represents invalid + /// unicode. /// /// # Examples /// diff --git a/src/lib.rs b/src/lib.rs index a5fec85..56ff809 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -536,8 +536,8 @@ impl Xdg { /// # Errors /// /// This method returns an error in the following cases: - /// - the `XDG_CONFIG_DIRS` environment variable is set, but its value represents a relative - /// path; + /// - the `XDG_CONFIG_DIRS` environment variable is set, but one (or more) path(s) in the + /// colon separated value represents a relative path; /// - the `XDG_CONFIG_DIRS` environment variable is set, but its value represents invalid /// unicode. /// @@ -570,8 +570,8 @@ impl Xdg { /// # Errors /// /// This method returns an error in the following cases: - /// - the `XDG_DATA_DIRS` environment variable is set, but its value represents a relative - /// path; + /// - the `XDG_DATA_DIRS` environment variable is set, but one (or more) path(s) in the colon + /// separated value represents a relative path; /// - the `XDG_DATA_DIRS` environment variable is set, but its value represents invalid /// unicode. /// @@ -884,7 +884,13 @@ impl Xdg { /// - the `XDG_CONFIG_HOME` environment variable is set, but its value represents a relative /// path; /// - the `XDG_CONFIG_HOME` environment variable is set, but its value represents invalid - /// unicode. + /// unicode; + /// - `file` was **not** found inside the _user-specific_ XDG config directory and: + /// - the `XDG_CONFIG_DIRS` environment variable is set, but one (or more) path(s) in the + /// colon separated value represents a relative path; + /// - the `XDG_CONFIG_DIRS` environment variable is set, but its value represents invalid + /// unicode. + /// /// /// # Examples /// @@ -928,7 +934,12 @@ impl Xdg { /// - the `XDG_DATA_HOME` environment variable is set, but its value represents a relative /// path; /// - the `XDG_DATA_HOME` environment variable is set, but its value represents invalid - /// unicode. + /// unicode; + /// - `file` was **not** found inside the _user-specific_ XDG data directory and: + /// - the `XDG_DATA_DIRS` environment variable is set, but one (or more) path(s) in the + /// colon separated value represents a relative path; + /// - the `XDG_DATA_DIRS` environment variable is set, but its value represents invalid + /// unicode. /// /// # Examples ///