dirs: add preference_dir, state_dir, & adjust executable_dir

dirs/README.md

@@ -87,24 +87,26 @@ dirs_next::executable_dir();
 **If you want to compute the location of cache, config or data directories for your own application or project,
 use `ProjectDirs` of the [directories-next] project instead.**
 
-| Function name    | Value on Linux/Redox                                                                             | Value on Windows                  | Value on macOS                              |
-| ---------------- | ------------------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------------------- |
-| `home_dir`       | `Some($HOME)`                                                                                    | `Some({FOLDERID_Profile})`        | `Some($HOME)`                               |
-| `cache_dir`      | `Some($XDG_CACHE_HOME)`         or `Some($HOME`/.cache`)`                                        | `Some({FOLDERID_LocalAppData})`   | `Some($HOME`/Library/Caches`)`              |
-| `config_dir`     | `Some($XDG_CONFIG_HOME)`        or `Some($HOME`/.config`)`                                       | `Some({FOLDERID_RoamingAppData})` | `Some($HOME`/Library/Application Support`)` |
-| `data_dir`       | `Some($XDG_DATA_HOME)`          or `Some($HOME`/.local/share`)`                                  | `Some({FOLDERID_RoamingAppData})` | `Some($HOME`/Library/Application Support`)` |
-| `data_local_dir` | `Some($XDG_DATA_HOME)`          or `Some($HOME`/.local/share`)`                                  | `Some({FOLDERID_LocalAppData})`   | `Some($HOME`/Library/Application Support`)` |
-| `executable_dir` | `Some($XDG_BIN_HOME`/../bin`)`  or `Some($XDG_DATA_HOME`/../bin`)` or `Some($HOME`/.local/bin`)` | `None`                            | `None`                                      |
-| `runtime_dir`    | `Some($XDG_RUNTIME_DIR)`        or `None`                                                        | `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/`)`                  |
-| `download_dir`   | `Some(XDG_DOWNLOAD_DIR)`        or `None`                                                        | `Some({FOLDERID_Downloads})`      | `Some($HOME`/Downloads/`)`                  |
-| `font_dir`       | `Some($XDG_DATA_HOME`/fonts/`)` or `Some($HOME`/.local/share/fonts/`)`                           | `None`                            | `Some($HOME`/Library/Fonts/`)`              |
-| `picture_dir`    | `Some(XDG_PICTURES_DIR)`        or `None`                                                        | `Some({FOLDERID_Pictures})`       | `Some($HOME`/Pictures/`)`                   |
-| `public_dir`     | `Some(XDG_PUBLICSHARE_DIR)`     or `None`                                                        | `Some({FOLDERID_Public})`         | `Some($HOME`/Public/`)`                     |
-| `template_dir`   | `Some(XDG_TEMPLATES_DIR)`       or `None`                                                        | `Some({FOLDERID_Templates})`      | `None`                                      |
-| `video_dir`      | `Some(XDG_VIDEOS_DIR)`          or `None`                                                        | `Some({FOLDERID_Videos})`         | `Some($HOME`/Movies/`)`                     |
+| Function name    | Value on Linux/Redox                                                   | Value on Windows                  | Value on macOS                              |
+| ---------------- | ---------------------------------------------------------------------- | --------------------------------- | ------------------------------------------- |
+| `home_dir`       | `Some($HOME)`                                                          | `Some({FOLDERID_Profile})`        | `Some($HOME)`                               |
+| `cache_dir`      | `Some($XDG_CACHE_HOME)`         or `Some($HOME`/.cache`)`              | `Some({FOLDERID_LocalAppData})`   | `Some($HOME`/Library/Caches`)`              |
+| `config_dir`     | `Some($XDG_CONFIG_HOME)`        or `Some($HOME`/.config`)`             | `Some({FOLDERID_RoamingAppData})` | `Some($HOME`/Library/Application Support`)` |
+| `preference_dir` | `Some($XDG_CONFIG_HOME)`        or `Some($HOME`/.config`)`             | `Some({FOLDERID_RoamingAppData})` | `Some($HOME`/Library/Preferences`)`         |
+| `data_dir`       | `Some($XDG_DATA_HOME)`          or `Some($HOME`/.local/share`)`        | `Some({FOLDERID_RoamingAppData})` | `Some($HOME`/Library/Application Support`)` |
+| `data_local_dir` | `Some($XDG_DATA_HOME)`          or `Some($HOME`/.local/share`)`        | `Some({FOLDERID_LocalAppData})`   | `Some($HOME`/Library/Application Support`)` |
+| `executable_dir` | `Some($XDG_BIN_HOME)`           or `Some($HOME`/.local/bin`)`          | `None`                            | `None`                                      |
+| `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/`)`                  |
+| `download_dir`   | `Some(XDG_DOWNLOAD_DIR)`        or `None`                              | `Some({FOLDERID_Downloads})`      | `Some($HOME`/Downloads/`)`                  |
+| `font_dir`       | `Some($XDG_DATA_HOME`/fonts/`)` or `Some($HOME`/.local/share/fonts/`)` | `None`                            | `Some($HOME`/Library/Fonts/`)`              |
+| `picture_dir`    | `Some(XDG_PICTURES_DIR)`        or `None`                              | `Some({FOLDERID_Pictures})`       | `Some($HOME`/Pictures/`)`                   |
+| `public_dir`     | `Some(XDG_PUBLICSHARE_DIR)`     or `None`                              | `Some({FOLDERID_Public})`         | `Some($HOME`/Public/`)`                     |
+| `template_dir`   | `Some(XDG_TEMPLATES_DIR)`       or `None`                              | `Some({FOLDERID_Templates})`      | `None`                                      |
+| `video_dir`      | `Some(XDG_VIDEOS_DIR)`          or `None`                              | `Some({FOLDERID_Videos})`         | `Some($HOME`/Movies/`)`                     |
 
 ## Comparison
 

dirs/src/lib.rs

@@ -1,6 +1,6 @@
 //! The _dirs-next_ crate is
 //!
-//! - a tiny library with a minimal API (16 functions)
+//! - a tiny library with a minimal API (18 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.
@@ -76,13 +76,25 @@ pub fn cache_dir() -> Option<PathBuf> {
 ///
 /// 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_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config                      |
+/// | macOS   | `$HOME`/Library/Application Support   | /Users/Alice/Library/Application Support |
+/// | Windows | `{FOLDERID_RoamingAppData}`           | C:\Users\Alice\AppData\Roaming           |
+pub fn config_dir() -> Option<PathBuf> {
+    sys::config_dir()
+}
+/// Returns the path to the user's preference directory.
+///
+/// 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_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config              |
-/// | macOS   | `$HOME`/Library/Application Support   | /Users/Alice/Library/Application Support |
+/// | macOS   | `$HOME`/Library/Preferences           | /Users/Alice/Library/Preferences |
 /// | Windows | `{FOLDERID_RoamingAppData}`           | C:\Users\Alice\AppData\Roaming   |
-pub fn config_dir() -> Option<PathBuf> {
-    sys::config_dir()
+pub fn preference_dir() -> Option<PathBuf> {
+    sys::preference_dir()
 }
 /// Returns the path to the user's data directory.
 ///
@@ -122,6 +134,9 @@ pub fn executable_dir() -> Option<PathBuf> {
 }
 /// Returns the path to the user's runtime directory.
 ///
+/// The runtime directory contains transient, non-essential data (like sockets or named pipes) that
+/// is expected to be cleared when the user's session ends.
+///
 /// 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         |
@@ -132,6 +147,22 @@ pub fn executable_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.
 ///
@@ -248,14 +279,18 @@ mod tests {
     #[test]
     fn test_dirs() {
         println!("home_dir:       {:?}", crate::home_dir());
+        println!();
         println!("cache_dir:      {:?}", crate::cache_dir());
         println!("config_dir:     {:?}", crate::config_dir());
+        println!("preference_dir: {:?}", crate::preference_dir());
         println!("data_dir:       {:?}", crate::data_dir());
         println!("data_local_dir: {:?}", crate::data_local_dir());
         println!("executable_dir: {:?}", crate::executable_dir());
         println!("runtime_dir:    {:?}", crate::runtime_dir());
+        println!("state_dir:      {:?}", crate::state_dir());
+        println!();
         println!("audio_dir:      {:?}", crate::audio_dir());
-        println!("home_dir:       {:?}", crate::desktop_dir());
+        println!("desktop_dir:    {:?}", crate::desktop_dir());
         println!("cache_dir:      {:?}", crate::document_dir());
         println!("config_dir:     {:?}", crate::download_dir());
         println!("font_dir:       {:?}", crate::font_dir());

dirs/src/lin.rs

@@ -4,6 +4,7 @@ use std::path::PathBuf;
 pub fn home_dir() -> Option<PathBuf> {
     dirs_sys_next::home_dir()
 }
+
 pub fn cache_dir() -> Option<PathBuf> {
     env::var_os("XDG_CACHE_HOME")
         .and_then(dirs_sys_next::is_absolute_path)
@@ -14,6 +15,9 @@ pub fn config_dir() -> Option<PathBuf> {
         .and_then(dirs_sys_next::is_absolute_path)
         .or_else(|| home_dir().map(|h| h.join(".config")))
 }
+pub fn preference_dir() -> Option<PathBuf> {
+    config_dir()
+}
 pub fn data_dir() -> Option<PathBuf> {
     env::var_os("XDG_DATA_HOME")
         .and_then(dirs_sys_next::is_absolute_path)
@@ -26,14 +30,16 @@ pub fn runtime_dir() -> Option<PathBuf> {
     env::var_os("XDG_RUNTIME_DIR").and_then(dirs_sys_next::is_absolute_path)
 }
 pub fn executable_dir() -> Option<PathBuf> {
-    env::var_os("XDG_BIN_HOME").and_then(dirs_sys_next::is_absolute_path).or_else(|| {
-        data_dir().map(|mut e| {
-            e.pop();
-            e.push("bin");
-            e
-        })
-    })
+    env::var_os("XDG_BIN_HOME")
+        .and_then(dirs_sys_next::is_absolute_path)
+        .or_else(|| home_dir().map(|h| h.join(".local/bin")))
 }
+pub fn state_dir() -> Option<PathBuf> {
+    env::var_os("XDG_STATE_HOME")
+        .and_then(dirs_sys_next::is_absolute_path)
+        .or_else(|| home_dir().map(|h| h.join(".local/state")))
+}
+
 pub fn audio_dir() -> Option<PathBuf> {
     dirs_sys_next::user_dir("MUSIC")
 }

dirs/src/mac.rs

@@ -3,12 +3,16 @@ use std::path::PathBuf;
 pub fn home_dir() -> Option<PathBuf> {
     dirs_sys_next::home_dir()
 }
+
 pub fn cache_dir() -> Option<PathBuf> {
     home_dir().map(|h| h.join("Library/Caches"))
 }
 pub fn config_dir() -> Option<PathBuf> {
     data_dir()
 }
+pub fn preference_dir() -> Option<PathBuf> {
+    home_dir().map(|h| h.join("Library/Preferences"))
+}
 pub fn data_dir() -> Option<PathBuf> {
     home_dir().map(|h| h.join("Library/Application Support"))
 }
@@ -21,6 +25,10 @@ pub fn executable_dir() -> Option<PathBuf> {
 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"))
 }

dirs/src/wasm.rs

@@ -5,12 +5,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 preference_dir() -> Option<PathBuf> {
+    None
+}
 pub fn data_dir() -> Option<PathBuf> {
     None
 }
@@ -23,6 +27,10 @@ pub fn runtime_dir() -> Option<PathBuf> {
 pub fn executable_dir() -> Option<PathBuf> {
     None
 }
+pub fn state_dir() -> Option<PathBuf> {
+    None
+}
+
 pub fn audio_dir() -> Option<PathBuf> {
     None
 }

dirs/src/win.rs

@@ -3,6 +3,7 @@ use std::path::PathBuf;
 pub fn home_dir() -> Option<PathBuf> {
     dirs_sys_next::known_folder_profile()
 }
+
 pub fn data_dir() -> Option<PathBuf> {
     dirs_sys_next::known_folder_roaming_app_data()
 }
@@ -15,12 +16,19 @@ pub fn cache_dir() -> Option<PathBuf> {
 pub fn config_dir() -> Option<PathBuf> {
     data_dir()
 }
+pub fn preference_dir() -> Option<PathBuf> {
+    data_dir()
+}
 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> {
     dirs_sys_next::known_folder_music()
 }