Add support for XDG_STATE_HOME

dirs-dev · Sep 15, 2021 · 8f14dfc · 8f14dfc
1 parent 840acfc
commit 8f14dfc
Show file tree

Hide file tree

Showing 6 changed files with 37 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -114,6 +114,7 @@ use `ProjectDirs` of the [directories](https://github.com/dirs-dev/directories-r
 | `executable_dir` | `Some($XDG_BIN_HOME`/../bin`)`  or `Some($XDG_DATA_HOME`/../bin`)` or `Some($HOME`/.local/bin`)` | `None`                            | `None`                                      |
 | `preference_dir` | `Some($XDG_CONFIG_HOME)`        or `Some($HOME`/.config`)`                                       | `Some({FOLDERID_RoamingAppData})` | `Some($HOME`/Library/Preferences`)`         |
 | `runtime_dir`    | `Some($XDG_RUNTIME_DIR)`        or `None`                                                        | `None`                            | `None`                                      |
+| `state_dir`      | `Some($XDG_STATE_HOME)`         or `Some($HOME`/.local/state`)`                                  | `None`                            | `None`                                      |
 | `audio_dir`      | `Some(XDG_MUSIC_DIR)`           or `None`                                                        | `Some({FOLDERID_Music})`          | `Some($HOME`/Music/`)`                      |
 | `desktop_dir`    | `Some(XDG_DESKTOP_DIR)`         or `None`                                                        | `Some({FOLDERID_Desktop})`        | `Some($HOME`/Desktop/`)`                    |
 | `document_dir`   | `Some(XDG_DOCUMENTS_DIR)`       or `None`                                                        | `Some({FOLDERID_Documents})`      | `Some($HOME`/Documents/`)`                  |
@@ -168,6 +169,9 @@ cargo build --target=x86_64-unknown-redox
 
 ## Changelog
 
+### 4
+- Add support for `XDG_STATE_HOME`.
+
 ### 3
 
 - **BREAKING CHANGE** The behavior of `config_dir` on macOS has been adjusted

diff --git a/src/lib.rs b/src/lib.rs
@@ -1,6 +1,6 @@
 //! The _dirs_ crate is
 //!
-//! - a tiny library with a minimal API (16 functions)
+//! - a tiny library with a minimal API (18 public functions)
 //! - that provides the platform-specific, user-accessible locations
 //! - for finding and storing configuration, cache and other data
 //! - on Linux, Redox, Windows (≥ Vista) and macOS.
@@ -158,6 +158,22 @@ pub fn preference_dir() -> Option<PathBuf> {
 pub fn runtime_dir() -> Option<PathBuf> {
     sys::runtime_dir()
 }
+/// Returns the path to the user's state directory.
+///
+/// The state directory contains data that should be retained between sessions (unlike the runtime
+/// directory), but may not be important/portable enough to be synchronized across machines (unlike
+/// the config/preferences/data directories).
+///
+/// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
+///
+/// |Platform | Value                                     | Example                  |
+/// | ------- | ----------------------------------------- | ------------------------ |
+/// | Linux   | `$XDG_STATE_HOME` or `$HOME`/.local/state | /home/alice/.local/state |
+/// | macOS   | –                                         | –                        |
+/// | Windows | –                                         | –                        |
+pub fn state_dir() -> Option<PathBuf> {
+    sys::state_dir()
+}
 
 /// Returns the path to the user's audio directory.
 ///
@@ -274,15 +290,18 @@ mod tests {
     #[test]
     fn test_dirs() {
         println!("home_dir:       {:?}", ::home_dir());
+        println!();
         println!("cache_dir:      {:?}", ::cache_dir());
         println!("config_dir:     {:?}", ::config_dir());
         println!("data_dir:       {:?}", ::data_dir());
         println!("data_local_dir: {:?}", ::data_local_dir());
         println!("executable_dir: {:?}", ::executable_dir());
         println!("preference_dir: {:?}", ::preference_dir());
         println!("runtime_dir:    {:?}", ::runtime_dir());
+        println!("state_dir:      {:?}", ::state_dir());
+        println!();
         println!("audio_dir:      {:?}", ::audio_dir());
-        println!("home_dir:       {:?}", ::desktop_dir());
+        println!("desktop_dir:    {:?}", ::desktop_dir());
         println!("cache_dir:      {:?}", ::document_dir());
         println!("config_dir:     {:?}", ::download_dir());
         println!("font_dir:       {:?}", ::font_dir());

diff --git a/src/lin.rs b/src/lin.rs
@@ -4,17 +4,20 @@ use std::env;
 use std::path::PathBuf;
 
 pub fn home_dir()       -> Option<PathBuf> { dirs_sys::home_dir() }
+
 pub fn cache_dir()      -> Option<PathBuf> { env::var_os("XDG_CACHE_HOME") .and_then(dirs_sys::is_absolute_path).or_else(|| home_dir().map(|h| h.join(".cache"))) }
 pub fn config_dir()     -> Option<PathBuf> { env::var_os("XDG_CONFIG_HOME").and_then(dirs_sys::is_absolute_path).or_else(|| home_dir().map(|h| h.join(".config"))) }
 pub fn data_dir()       -> Option<PathBuf> { env::var_os("XDG_DATA_HOME")  .and_then(dirs_sys::is_absolute_path).or_else(|| home_dir().map(|h| h.join(".local/share"))) }
 pub fn data_local_dir() -> Option<PathBuf> { data_dir() }
 pub fn preference_dir() -> Option<PathBuf> { config_dir() }
 pub fn runtime_dir()    -> Option<PathBuf> { env::var_os("XDG_RUNTIME_DIR").and_then(dirs_sys::is_absolute_path) }
+pub fn state_dir()      -> Option<PathBuf> { env::var_os("XDG_STATE_HOME") .and_then(dirs_sys::is_absolute_path).or_else(|| home_dir().map(|h| h.join(".local/state"))) }
 pub fn executable_dir() -> Option<PathBuf> {
     env::var_os("XDG_BIN_HOME").and_then(dirs_sys::is_absolute_path).or_else(|| {
         data_dir().map(|mut e| { e.pop(); e.push("bin"); e })
     })
 }
+
 pub fn audio_dir()      -> Option<PathBuf> { dirs_sys::user_dir("MUSIC") }
 pub fn desktop_dir()    -> Option<PathBuf> { dirs_sys::user_dir("DESKTOP") }
 pub fn document_dir()   -> Option<PathBuf> { dirs_sys::user_dir("DOCUMENTS") }

diff --git a/src/mac.rs b/src/mac.rs
@@ -3,13 +3,16 @@ extern crate dirs_sys;
 use std::path::PathBuf;
 
 pub fn home_dir()       -> Option<PathBuf> { dirs_sys::home_dir() }
+
 pub fn cache_dir()      -> Option<PathBuf> { home_dir().map(|h| h.join("Library/Caches")) }
 pub fn config_dir()     -> Option<PathBuf> { home_dir().map(|h| h.join("Library/Application Support")) }
 pub fn data_dir()       -> Option<PathBuf> { home_dir().map(|h| h.join("Library/Application Support")) }
 pub fn data_local_dir() -> Option<PathBuf> { data_dir() }
 pub fn preference_dir() -> Option<PathBuf> { home_dir().map(|h| h.join("Library/Preferences")) }
 pub fn executable_dir() -> Option<PathBuf> { None }
 pub fn runtime_dir()    -> Option<PathBuf> { None }
+pub fn state_dir()      -> Option<PathBuf> { None }
+
 pub fn audio_dir()      -> Option<PathBuf> { home_dir().map(|h| h.join("Music")) }
 pub fn desktop_dir()    -> Option<PathBuf> { home_dir().map(|h| h.join("Desktop")) }
 pub fn document_dir()   -> Option<PathBuf> { home_dir().map(|h| h.join("Documents")) }

diff --git a/src/wasm.rs b/src/wasm.rs
@@ -3,13 +3,16 @@
 use std::path::PathBuf;
 
 pub fn home_dir()       -> Option<PathBuf> { None }
+
 pub fn cache_dir()      -> Option<PathBuf> { None }
 pub fn config_dir()     -> Option<PathBuf> { None }
 pub fn data_dir()       -> Option<PathBuf> { None }
 pub fn data_local_dir() -> Option<PathBuf> { None }
 pub fn preference_dir() -> Option<PathBuf> { None }
 pub fn runtime_dir()    -> Option<PathBuf> { None }
 pub fn executable_dir() -> Option<PathBuf> { None }
+pub fn state_dir()      -> Option<PathBuf> { None }
+
 pub fn audio_dir()      -> Option<PathBuf> { None }
 pub fn desktop_dir()    -> Option<PathBuf> { None }
 pub fn document_dir()   -> Option<PathBuf> { None }

diff --git a/src/win.rs b/src/win.rs
@@ -3,13 +3,16 @@ extern crate dirs_sys;
 use std::path::PathBuf;
 
 pub fn home_dir()       -> Option<PathBuf> { dirs_sys::known_folder_profile() }
+
 pub fn data_dir()       -> Option<PathBuf> { dirs_sys::known_folder_roaming_app_data() }
 pub fn data_local_dir() -> Option<PathBuf> { dirs_sys::known_folder_local_app_data() }
 pub fn cache_dir()      -> Option<PathBuf> { data_local_dir() }
 pub fn config_dir()     -> Option<PathBuf> { data_dir() }
 pub fn executable_dir() -> Option<PathBuf> { None }
 pub fn preference_dir() -> Option<PathBuf> { data_dir() }
 pub fn runtime_dir()    -> Option<PathBuf> { None }
+pub fn state_dir()      -> Option<PathBuf> { None }
+
 pub fn audio_dir()      -> Option<PathBuf> { dirs_sys::known_folder_music() }
 pub fn desktop_dir()    -> Option<PathBuf> { dirs_sys::known_folder_desktop() }
 pub fn document_dir()   -> Option<PathBuf> { dirs_sys::known_folder_documents() }