From 0d6c07747bb0cbfe6aae54ce858ceb5594d3a61c Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sun, 2 Mar 2025 21:57:19 -0800 Subject: [PATCH 01/10] Vendor etcetera 0.9.0 --- src/etcetera/app_strategy.rs | 175 +++++++++++++++++++++ src/etcetera/app_strategy/apple.rs | 86 ++++++++++ src/etcetera/app_strategy/unix.rs | 87 +++++++++++ src/etcetera/app_strategy/windows.rs | 166 ++++++++++++++++++++ src/etcetera/app_strategy/xdg.rs | 217 ++++++++++++++++++++++++++ src/etcetera/base_strategy.rs | 69 ++++++++ src/etcetera/base_strategy/apple.rs | 78 +++++++++ src/etcetera/base_strategy/windows.rs | 206 ++++++++++++++++++++++++ src/etcetera/base_strategy/xdg.rs | 211 +++++++++++++++++++++++++ src/etcetera/lib.rs | 126 +++++++++++++++ 10 files changed, 1421 insertions(+) create mode 100644 src/etcetera/app_strategy.rs create mode 100644 src/etcetera/app_strategy/apple.rs create mode 100644 src/etcetera/app_strategy/unix.rs create mode 100644 src/etcetera/app_strategy/windows.rs create mode 100644 src/etcetera/app_strategy/xdg.rs create mode 100644 src/etcetera/base_strategy.rs create mode 100644 src/etcetera/base_strategy/apple.rs create mode 100644 src/etcetera/base_strategy/windows.rs create mode 100644 src/etcetera/base_strategy/xdg.rs create mode 100644 src/etcetera/lib.rs diff --git a/src/etcetera/app_strategy.rs b/src/etcetera/app_strategy.rs new file mode 100644 index 0000000..87ca0a6 --- /dev/null +++ b/src/etcetera/app_strategy.rs @@ -0,0 +1,175 @@ +//! These strategies require you to provide some information on your application, and they will in turn locate the configuration/data/cache directory specifically for your application. + +use std::ffi::OsStr; +use std::path::Path; +use std::path::PathBuf; + +use crate::HomeDirError; + +/// The arguments to the creator method of an [`AppStrategy`](trait.AppStrategy.html). +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Default)] +pub struct AppStrategyArgs { + /// The top level domain of the application, e.g. `com`, `org`, or `io.github`. + pub top_level_domain: String, + /// The name of the author of the application. + pub author: String, + /// The application’s name. This should be capitalised if appropriate. + pub app_name: String, +} + +impl AppStrategyArgs { + /// Constructs a bunde identifier from an `AppStrategyArgs`. + /// + /// ``` + /// use etcetera::app_strategy::AppStrategyArgs; + /// + /// let strategy_args = AppStrategyArgs { + /// top_level_domain: "org".to_string(), + /// author: "Acme Corp".to_string(), + /// app_name: "Frobnicator Plus".to_string(), + /// }; + /// + /// assert_eq!(strategy_args.bundle_id(), "org.acme-corp.Frobnicator-Plus".to_string()); + /// ``` + pub fn bundle_id(&self) -> String { + let author = self.author.to_lowercase().replace(' ', "-"); + let app_name = self.app_name.replace(' ', "-"); + let mut parts = vec![ + self.top_level_domain.as_str(), + author.as_str(), + app_name.as_str(), + ]; + parts.retain(|part| !part.is_empty()); + parts.join(".") + } + + /// Returns a ‘unixy’ version of the application’s name, akin to what would usually be used as a binary name. + /// + /// ``` + /// use etcetera::app_strategy::AppStrategyArgs; + /// + /// let strategy_args = AppStrategyArgs { + /// top_level_domain: "org".to_string(), + /// author: "Acme Corp".to_string(), + /// app_name: "Frobnicator Plus".to_string(), + /// }; + /// + /// assert_eq!(strategy_args.unixy_name(), "frobnicator-plus".to_string()); + /// ``` + pub fn unixy_name(&self) -> String { + self.app_name.to_lowercase().replace(' ', "-") + } +} + +macro_rules! in_dir_method { + ($self: ident, $path_extra: expr, $dir_method_name: ident) => {{ + let mut path = $self.$dir_method_name(); + path.push(Path::new(&$path_extra)); + path + }}; + (opt: $self: ident, $path_extra: expr, $dir_method_name: ident) => {{ + let mut path = $self.$dir_method_name()?; + path.push(Path::new(&$path_extra)); + Some(path) + }}; +} + +/// Allows applications to retrieve the paths of configuration, data, and cache directories specifically for them. +pub trait AppStrategy { + /// Gets the home directory of the current user. + fn home_dir(&self) -> &Path; + + /// Gets the configuration directory for your application. + fn config_dir(&self) -> PathBuf; + + /// Gets the data directory for your application. + fn data_dir(&self) -> PathBuf; + + /// Gets the cache directory for your application. + fn cache_dir(&self) -> PathBuf; + + /// Gets the state directory for your application. + /// Currently, only the [`Xdg`](struct.Xdg.html) & [`Unix`](struct.Unix.html) strategies support + /// this. + fn state_dir(&self) -> Option; + + /// Gets the runtime directory for your application. + /// Currently, only the [`Xdg`](struct.Xdg.html) & [`Unix`](struct.Unix.html) strategies support + /// this. + /// + /// Note: The [XDG Base Directory Specification](spec) places additional requirements on this + /// directory related to ownership, permissions, and persistence. This library does not check + /// these requirements. + /// + /// [spec]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html + fn runtime_dir(&self) -> Option; + + /// Constructs a path inside your application’s configuration directory to which a path of your choice has been appended. + fn in_config_dir>(&self, path: P) -> PathBuf { + in_dir_method!(self, path, config_dir) + } + + /// Constructs a path inside your application’s data directory to which a path of your choice has been appended. + fn in_data_dir>(&self, path: P) -> PathBuf { + in_dir_method!(self, path, data_dir) + } + + /// Constructs a path inside your application’s cache directory to which a path of your choice has been appended. + fn in_cache_dir>(&self, path: P) -> PathBuf { + in_dir_method!(self, path, cache_dir) + } + + /// Constructs a path inside your application’s state directory to which a path of your choice has been appended. + /// + /// Currently, this is only implemented for the [`Xdg`](struct.Xdg.html) strategy. + fn in_state_dir>(&self, path: P) -> Option { + in_dir_method!(opt: self, path, state_dir) + } + + /// Constructs a path inside your application’s runtime directory to which a path of your choice has been appended. + /// Currently, only the [`Xdg`](struct.Xdg.html) & [`Unix`](struct.Unix.html) strategies support + /// this. + /// + /// See the note in [`runtime_dir`](#method.runtime_dir) for more information. + fn in_runtime_dir>(&self, path: P) -> Option { + in_dir_method!(opt: self, path, runtime_dir) + } +} + +macro_rules! create_strategies { + ($native: ty, $app: ty) => { + /// Returns the current OS’s native [`AppStrategy`](trait.AppStrategy.html). + /// This uses the [`Windows`](struct.Windows.html) strategy on Windows, [`Apple`](struct.Apple.html) on macOS & iOS, and [`Xdg`](struct.Xdg.html) everywhere else. + /// This is the convention used by most GUI applications. + pub fn choose_native_strategy(args: AppStrategyArgs) -> Result<$native, HomeDirError> { + <$native>::new(args) + } + + /// Returns the current OS’s default [`AppStrategy`](trait.AppStrategy.html). + /// This uses the [`Windows`](struct.Windows.html) strategy on Windows, and [`Xdg`](struct.Xdg.html) everywhere else. + /// This is the convention used by most CLI applications. + pub fn choose_app_strategy(args: AppStrategyArgs) -> Result<$app, HomeDirError> { + <$app>::new(args) + } + }; +} + +cfg_if::cfg_if! { + if #[cfg(target_os = "windows")] { + create_strategies!(Windows, Windows); + } else if #[cfg(any(target_os = "macos", target_os = "ios"))] { + create_strategies!(Apple, Xdg); + } else { + create_strategies!(Xdg, Xdg); + } +} + +mod apple; +mod unix; +mod windows; +mod xdg; + +pub use apple::Apple; +pub use unix::Unix; +pub use windows::Windows; +pub use xdg::Xdg; diff --git a/src/etcetera/app_strategy/apple.rs b/src/etcetera/app_strategy/apple.rs new file mode 100644 index 0000000..f06d3bc --- /dev/null +++ b/src/etcetera/app_strategy/apple.rs @@ -0,0 +1,86 @@ +use crate::base_strategy::BaseStrategy; +use crate::{base_strategy, HomeDirError}; +use std::path::{Path, PathBuf}; + +/// This is the strategy created by Apple for use on macOS and iOS devices. It is always used by GUI apps on macOS, and is sometimes used by command-line applications there too. iOS only has GUIs, so all iOS applications follow this strategy. The specification is available [here](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW1). +/// +/// ``` +/// use etcetera::app_strategy::AppStrategy; +/// use etcetera::app_strategy::AppStrategyArgs; +/// use etcetera::app_strategy::Apple; +/// use std::path::Path; +/// +/// let app_strategy = Apple::new(AppStrategyArgs { +/// top_level_domain: "org".to_string(), +/// author: "Acme Corp".to_string(), +/// app_name: "Frobnicator Plus".to_string(), +/// }).unwrap(); +/// +/// let home_dir = etcetera::home_dir().unwrap(); +/// +/// assert_eq!( +/// app_strategy.home_dir(), +/// &home_dir +/// ); +/// assert_eq!( +/// app_strategy.config_dir().strip_prefix(&home_dir), +/// Ok(Path::new("Library/Preferences/org.acme-corp.Frobnicator-Plus/")) +/// ); +/// assert_eq!( +/// app_strategy.data_dir().strip_prefix(&home_dir), +/// Ok(Path::new("Library/Application Support/org.acme-corp.Frobnicator-Plus/")) +/// ); +/// assert_eq!( +/// app_strategy.cache_dir().strip_prefix(&home_dir), +/// Ok(Path::new("Library/Caches/org.acme-corp.Frobnicator-Plus/")) +/// ); +/// assert_eq!( +/// app_strategy.state_dir(), +/// None +/// ); +/// assert_eq!( +/// app_strategy.runtime_dir(), +/// None +/// ); +/// ``` +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct Apple { + base_strategy: base_strategy::Apple, + bundle_id: String, +} + +impl Apple { + /// Create a new Apple AppStrategy + pub fn new(args: super::AppStrategyArgs) -> Result { + Ok(Self { + base_strategy: base_strategy::Apple::new()?, + bundle_id: args.bundle_id(), + }) + } +} + +impl super::AppStrategy for Apple { + fn home_dir(&self) -> &Path { + self.base_strategy.home_dir() + } + + fn config_dir(&self) -> PathBuf { + self.base_strategy.config_dir().join(&self.bundle_id) + } + + fn data_dir(&self) -> PathBuf { + self.base_strategy.data_dir().join(&self.bundle_id) + } + + fn cache_dir(&self) -> PathBuf { + self.base_strategy.cache_dir().join(&self.bundle_id) + } + + fn state_dir(&self) -> Option { + None + } + + fn runtime_dir(&self) -> Option { + None + } +} diff --git a/src/etcetera/app_strategy/unix.rs b/src/etcetera/app_strategy/unix.rs new file mode 100644 index 0000000..932a9d8 --- /dev/null +++ b/src/etcetera/app_strategy/unix.rs @@ -0,0 +1,87 @@ +use std::path::{Path, PathBuf}; + +use crate::HomeDirError; + +/// This strategy has no standard or official specification. It has arisen over time through hundreds of Unixy tools. Vim and Cargo are notable examples whose configuration/data/cache directory layouts are similar to those created by this strategy. +/// +/// ``` +/// use etcetera::app_strategy::AppStrategy; +/// use etcetera::app_strategy::AppStrategyArgs; +/// use etcetera::app_strategy::Unix; +/// use std::path::Path; +/// +/// let app_strategy = Unix::new(AppStrategyArgs { +/// top_level_domain: "org".to_string(), +/// author: "Acme Corp".to_string(), +/// app_name: "Frobnicator Plus".to_string(), +/// }).unwrap(); +/// +/// let home_dir = etcetera::home_dir().unwrap(); +/// +/// assert_eq!( +/// app_strategy.home_dir(), +/// &home_dir +/// ); +/// assert_eq!( +/// app_strategy.config_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".frobnicator-plus/")) +/// ); +/// assert_eq!( +/// app_strategy.data_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".frobnicator-plus/data/")) +/// ); +/// assert_eq!( +/// app_strategy.cache_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".frobnicator-plus/cache/")) +/// ); +/// assert_eq!( +/// app_strategy.state_dir().unwrap().strip_prefix(&home_dir), +/// Ok(Path::new(".frobnicator-plus/state/")) +/// ); +/// assert_eq!( +/// app_strategy.runtime_dir().unwrap().strip_prefix(&home_dir), +/// Ok(Path::new(".frobnicator-plus/runtime/")) +/// ); +/// ``` +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct Unix { + // This is `.frobnicator-plus` in the above example. + home_dir: PathBuf, + unixy_name: String, +} + +impl Unix { + /// Create a new Unix AppStrategy + pub fn new(args: super::AppStrategyArgs) -> Result { + Ok(Self { + home_dir: crate::home_dir()?, + unixy_name: format!(".{}", args.unixy_name()), + }) + } +} + +impl super::AppStrategy for Unix { + fn home_dir(&self) -> &Path { + &self.home_dir + } + + fn config_dir(&self) -> PathBuf { + self.home_dir.join(&self.unixy_name) + } + + fn data_dir(&self) -> PathBuf { + self.home_dir.join(&self.unixy_name).join("data/") + } + + fn cache_dir(&self) -> PathBuf { + self.home_dir.join(&self.unixy_name).join("cache/") + } + + fn state_dir(&self) -> Option { + Some(self.home_dir.join(&self.unixy_name).join("state/")) + } + + fn runtime_dir(&self) -> Option { + Some(self.home_dir.join(&self.unixy_name).join("runtime/")) + } +} diff --git a/src/etcetera/app_strategy/windows.rs b/src/etcetera/app_strategy/windows.rs new file mode 100644 index 0000000..1fe938a --- /dev/null +++ b/src/etcetera/app_strategy/windows.rs @@ -0,0 +1,166 @@ +use crate::base_strategy::BaseStrategy; +use crate::{base_strategy, HomeDirError}; +use std::path::{Path, PathBuf}; + +/// This strategy follows Windows’ conventions. It seems that all Windows GUI apps, and some command-line ones follow this pattern. The specification is available [here](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). +/// +/// This initial example removes all the relevant environment variables to show the strategy’s use of the: +/// - (on Windows) SHGetKnownFolderPath API. +/// - (on non-Windows) Windows default directories. +/// +/// ``` +/// use etcetera::app_strategy::AppStrategy; +/// use etcetera::app_strategy::AppStrategyArgs; +/// use etcetera::app_strategy::Windows; +/// use std::path::Path; +/// +/// // Remove the environment variables that the strategy reads from. +/// std::env::remove_var("USERPROFILE"); +/// std::env::remove_var("APPDATA"); +/// std::env::remove_var("LOCALAPPDATA"); +/// +/// let app_strategy = Windows::new(AppStrategyArgs { +/// top_level_domain: "org".to_string(), +/// author: "Acme Corp".to_string(), +/// app_name: "Frobnicator Plus".to_string(), +/// }).unwrap(); +/// +/// let home_dir = etcetera::home_dir().unwrap(); +/// +/// assert_eq!( +/// app_strategy.home_dir(), +/// &home_dir +/// ); +/// assert_eq!( +/// app_strategy.config_dir().strip_prefix(&home_dir), +/// Ok(Path::new("AppData/Roaming/Acme Corp/Frobnicator Plus/config")) +/// ); +/// assert_eq!( +/// app_strategy.data_dir().strip_prefix(&home_dir), +/// Ok(Path::new("AppData/Roaming/Acme Corp/Frobnicator Plus/data")) +/// ); +/// assert_eq!( +/// app_strategy.cache_dir().strip_prefix(&home_dir), +/// Ok(Path::new("AppData/Local/Acme Corp/Frobnicator Plus/cache")) +/// ); +/// assert_eq!( +/// app_strategy.state_dir(), +/// None +/// ); +/// assert_eq!( +/// app_strategy.runtime_dir(), +/// None +/// ); +/// ``` +/// +/// This next example gives the environment variables values: +/// +/// ``` +/// use etcetera::app_strategy::AppStrategy; +/// use etcetera::app_strategy::AppStrategyArgs; +/// use etcetera::app_strategy::Windows; +/// use std::path::Path; +/// +/// let home_path = if cfg!(windows) { +/// "C:\\my_home_location\\".to_string() +/// } else { +/// etcetera::home_dir().unwrap().to_string_lossy().to_string() +/// }; +/// let data_path = if cfg!(windows) { +/// "C:\\my_data_location\\" +/// } else { +/// "/my_data_location/" +/// }; +/// let cache_path = if cfg!(windows) { +/// "C:\\my_cache_location\\" +/// } else { +/// "/my_cache_location/" +/// }; +/// +/// std::env::set_var("USERPROFILE", &home_path); +/// std::env::set_var("APPDATA", data_path); +/// std::env::set_var("LOCALAPPDATA", cache_path); +/// +/// let app_strategy = Windows::new(AppStrategyArgs { +/// top_level_domain: "org".to_string(), +/// author: "Acme Corp".to_string(), +/// app_name: "Frobnicator Plus".to_string(), +/// }).unwrap(); +/// +/// assert_eq!( +/// app_strategy.home_dir(), +/// Path::new(&home_path) +/// ); +/// assert_eq!( +/// app_strategy.config_dir(), +/// Path::new(&format!("{}/Acme Corp/Frobnicator Plus/config", data_path)) +/// ); +/// assert_eq!( +/// app_strategy.data_dir(), +/// Path::new(&format!("{}/Acme Corp/Frobnicator Plus/data", data_path)) +/// ); +/// assert_eq!( +/// app_strategy.cache_dir(), +/// Path::new(&format!("{}/Acme Corp/Frobnicator Plus/cache", cache_path)) +/// ); +/// assert_eq!( +/// app_strategy.state_dir(), +/// None +/// ); +/// assert_eq!( +/// app_strategy.runtime_dir(), +/// None +/// ); +/// ``` + +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct Windows { + base_strategy: base_strategy::Windows, + author_app_name_path: PathBuf, +} + +macro_rules! dir_method { + ($self: ident, $base_strategy_method: ident, $subfolder_name: expr) => {{ + let mut path = $self.base_strategy.$base_strategy_method(); + path.push(&$self.author_app_name_path); + path.push($subfolder_name); + + path + }}; +} + +impl Windows { + /// Create a new Windows AppStrategy + pub fn new(args: super::AppStrategyArgs) -> Result { + Ok(Self { + base_strategy: base_strategy::Windows::new()?, + author_app_name_path: PathBuf::from(args.author).join(args.app_name), + }) + } +} + +impl super::AppStrategy for Windows { + fn home_dir(&self) -> &Path { + self.base_strategy.home_dir() + } + + fn config_dir(&self) -> PathBuf { + dir_method!(self, config_dir, "config") + } + + fn data_dir(&self) -> PathBuf { + dir_method!(self, data_dir, "data") + } + + fn cache_dir(&self) -> PathBuf { + dir_method!(self, cache_dir, "cache") + } + + fn state_dir(&self) -> Option { + None + } + + fn runtime_dir(&self) -> Option { + None + } +} diff --git a/src/etcetera/app_strategy/xdg.rs b/src/etcetera/app_strategy/xdg.rs new file mode 100644 index 0000000..09f9ff0 --- /dev/null +++ b/src/etcetera/app_strategy/xdg.rs @@ -0,0 +1,217 @@ +use crate::base_strategy::BaseStrategy; +use crate::{base_strategy, HomeDirError}; +use std::path::{Path, PathBuf}; + +/// This strategy implements the [XDG Base Directories Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). It is the most common on Linux, but is increasingly being adopted elsewhere. +/// +/// This initial example removes all the XDG environment variables to show the strategy’s use of the XDG default directories. +/// +/// ``` +/// use etcetera::app_strategy::AppStrategy; +/// use etcetera::app_strategy::AppStrategyArgs; +/// use etcetera::app_strategy::Xdg; +/// use std::path::Path; +/// +/// // Remove the environment variables that the strategy reads from. +/// std::env::remove_var("XDG_CONFIG_HOME"); +/// std::env::remove_var("XDG_DATA_HOME"); +/// std::env::remove_var("XDG_CACHE_HOME"); +/// std::env::remove_var("XDG_STATE_HOME"); +/// std::env::remove_var("XDG_RUNTIME_DIR"); +/// +/// let app_strategy = Xdg::new(AppStrategyArgs { +/// top_level_domain: "org".to_string(), +/// author: "Acme Corp".to_string(), +/// app_name: "Frobnicator Plus".to_string(), +/// }).unwrap(); +/// +/// let home_dir = etcetera::home_dir().unwrap(); +/// +/// assert_eq!( +/// app_strategy.home_dir(), +/// &home_dir +/// ); +/// assert_eq!( +/// app_strategy.config_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".config/frobnicator-plus/")) +/// ); +/// assert_eq!( +/// app_strategy.data_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".local/share/frobnicator-plus/")) +/// ); +/// assert_eq!( +/// app_strategy.cache_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".cache/frobnicator-plus/")) +/// ); +/// assert_eq!( +/// app_strategy.state_dir().unwrap().strip_prefix(&home_dir), +/// Ok(Path::new(".local/state/frobnicator-plus/")) +/// ); +/// assert_eq!( +/// app_strategy.runtime_dir(), +/// None +/// ); +/// ``` +/// +/// This next example gives the environment variables values: +/// +/// ``` +/// use etcetera::app_strategy::AppStrategy; +/// use etcetera::app_strategy::AppStrategyArgs; +/// use etcetera::app_strategy::Xdg; +/// use std::path::Path; +/// +/// // We need to conditionally set these to ensure that they are absolute paths both on Windows and other systems. +/// let config_path = if cfg!(windows) { +/// "C:\\my_config_location\\" +/// } else { +/// "/my_config_location/" +/// }; +/// let data_path = if cfg!(windows) { +/// "C:\\my_data_location\\" +/// } else { +/// "/my_data_location/" +/// }; +/// let cache_path = if cfg!(windows) { +/// "C:\\my_cache_location\\" +/// } else { +/// "/my_cache_location/" +/// }; +/// let state_path = if cfg!(windows) { +/// "C:\\my_state_location\\" +/// } else { +/// "/my_state_location/" +/// }; +/// let runtime_path = if cfg!(windows) { +/// "C:\\my_runtime_location\\" +/// } else { +/// "/my_runtime_location/" +/// }; +/// +/// std::env::set_var("XDG_CONFIG_HOME", config_path); +/// std::env::set_var("XDG_DATA_HOME", data_path); +/// std::env::set_var("XDG_CACHE_HOME", cache_path); +/// std::env::set_var("XDG_STATE_HOME", state_path); +/// std::env::set_var("XDG_RUNTIME_DIR", runtime_path); +/// +/// let app_strategy = Xdg::new(AppStrategyArgs { +/// top_level_domain: "org".to_string(), +/// author: "Acme Corp".to_string(), +/// app_name: "Frobnicator Plus".to_string(), +/// }).unwrap(); +/// +/// assert_eq!( +/// app_strategy.config_dir(), +/// Path::new(&format!("{}/frobnicator-plus/", config_path)) +/// ); +/// assert_eq!( +/// app_strategy.data_dir(), +/// Path::new(&format!("{}/frobnicator-plus/", data_path)) +/// ); +/// assert_eq!( +/// app_strategy.cache_dir(), +/// Path::new(&format!("{}/frobnicator-plus/", cache_path)) +/// ); +/// assert_eq!( +/// app_strategy.state_dir().unwrap(), +/// Path::new(&format!("{}/frobnicator-plus/", state_path)) +/// ); +/// assert_eq!( +/// app_strategy.runtime_dir().unwrap(), +/// Path::new(&format!("{}/frobnicator-plus/", runtime_path)) +/// ); +/// ``` +/// +/// The XDG spec requires that when the environment variables’ values are not absolute paths, their values should be ignored. This example exemplifies this behaviour: +/// +/// ``` +/// use etcetera::app_strategy::AppStrategy; +/// use etcetera::app_strategy::AppStrategyArgs; +/// use etcetera::app_strategy::Xdg; +/// use std::path::Path; +/// +/// // Remove the environment variables that the strategy reads from. +/// std::env::set_var("XDG_CONFIG_HOME", "relative_path/"); +/// std::env::set_var("XDG_DATA_HOME", "./another_one/"); +/// std::env::set_var("XDG_CACHE_HOME", "yet_another/"); +/// std::env::set_var("XDG_STATE_HOME", "./and_another"); +/// std::env::set_var("XDG_RUNTIME_DIR", "relative_path/"); +/// +/// let app_strategy = Xdg::new(AppStrategyArgs { +/// top_level_domain: "org".to_string(), +/// author: "Acme Corp".to_string(), +/// app_name: "Frobnicator Plus".to_string(), +/// }).unwrap(); +/// +/// let home_dir = etcetera::home_dir().unwrap(); +/// +/// // We still get the default values. +/// assert_eq!( +/// app_strategy.config_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".config/frobnicator-plus/")) +/// ); +/// assert_eq!( +/// app_strategy.data_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".local/share/frobnicator-plus/")) +/// ); +/// assert_eq!( +/// app_strategy.cache_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".cache/frobnicator-plus/")) +/// ); +/// assert_eq!( +/// app_strategy.state_dir().unwrap().strip_prefix(&home_dir), +/// Ok(Path::new(".local/state/frobnicator-plus/")) +/// ); +/// assert_eq!( +/// app_strategy.runtime_dir(), +/// None +/// ); +/// ``` +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct Xdg { + base_strategy: base_strategy::Xdg, + unixy_name: String, +} + +impl Xdg { + /// Create a new Xdg AppStrategy + pub fn new(args: super::AppStrategyArgs) -> Result { + Ok(Self { + base_strategy: base_strategy::Xdg::new()?, + unixy_name: args.unixy_name(), + }) + } +} + +impl super::AppStrategy for Xdg { + fn home_dir(&self) -> &Path { + self.base_strategy.home_dir() + } + + fn config_dir(&self) -> PathBuf { + self.base_strategy.config_dir().join(&self.unixy_name) + } + + fn data_dir(&self) -> PathBuf { + self.base_strategy.data_dir().join(&self.unixy_name) + } + + fn cache_dir(&self) -> PathBuf { + self.base_strategy.cache_dir().join(&self.unixy_name) + } + + fn state_dir(&self) -> Option { + Some( + self.base_strategy + .state_dir() + .unwrap() + .join(&self.unixy_name), + ) + } + + fn runtime_dir(&self) -> Option { + self.base_strategy + .runtime_dir() + .map(|runtime_dir| runtime_dir.join(&self.unixy_name)) + } +} diff --git a/src/etcetera/base_strategy.rs b/src/etcetera/base_strategy.rs new file mode 100644 index 0000000..80b271d --- /dev/null +++ b/src/etcetera/base_strategy.rs @@ -0,0 +1,69 @@ +//! These strategies simply provide the user’s configuration, data, and cache directories, without knowing about the application specifically. + +use crate::HomeDirError; +use std::path::{Path, PathBuf}; + +/// Provides configuration, data, and cache directories of the current user. +pub trait BaseStrategy { + /// Gets the home directory of the current user. + fn home_dir(&self) -> &Path; + + /// Gets the user’s configuration directory. + fn config_dir(&self) -> PathBuf; + + /// Gets the user’s data directory. + fn data_dir(&self) -> PathBuf; + + /// Gets the user’s cache directory. + fn cache_dir(&self) -> PathBuf; + + /// Gets the user’s state directory. + /// Currently, only the [`Xdg`](struct.Xdg.html) strategy supports this. + fn state_dir(&self) -> Option; + + /// Gets the user’s runtime directory. + /// Currently, only the [`Xdg`](struct.Xdg.html) strategy supports this. + /// + /// Note: The [XDG Base Directory Specification](spec) places additional requirements on this + /// directory related to ownership, permissions, and persistence. This library does not check + /// these requirements. + /// + /// [spec]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html + fn runtime_dir(&self) -> Option; +} + +macro_rules! create_strategies { + ($native: ty, $base: ty) => { + /// Returns the current OS’s native [`BaseStrategy`](trait.BaseStrategy.html). + /// This uses the [`Windows`](struct.Windows.html) strategy on Windows, [`Apple`](struct.Apple.html) on macOS & iOS, and [`Xdg`](struct.Xdg.html) everywhere else. + /// This is the convention used by most GUI applications. + pub fn choose_native_strategy() -> Result<$native, HomeDirError> { + <$native>::new() + } + + /// Returns the current OS’s default [`BaseStrategy`](trait.BaseStrategy.html). + /// This uses the [`Windows`](struct.Windows.html) strategy on Windows, and [`Xdg`](struct.Xdg.html) everywhere else. + /// This is the convention used by most CLI applications. + pub fn choose_base_strategy() -> Result<$base, HomeDirError> { + <$base>::new() + } + }; +} + +cfg_if::cfg_if! { + if #[cfg(target_os = "windows")] { + create_strategies!(Windows, Windows); + } else if #[cfg(any(target_os = "macos", target_os = "ios"))] { + create_strategies!(Apple, Xdg); + } else { + create_strategies!(Xdg, Xdg); + } +} + +mod apple; +mod windows; +mod xdg; + +pub use apple::Apple; +pub use windows::Windows; +pub use xdg::Xdg; diff --git a/src/etcetera/base_strategy/apple.rs b/src/etcetera/base_strategy/apple.rs new file mode 100644 index 0000000..358119c --- /dev/null +++ b/src/etcetera/base_strategy/apple.rs @@ -0,0 +1,78 @@ +use std::path::{Path, PathBuf}; + +use crate::HomeDirError; + +/// This is the strategy created by Apple for use on macOS and iOS devices. It is always used by GUI apps on macOS, and is sometimes used by command-line applications there too. iOS only has GUIs, so all iOS applications follow this strategy. The specification is available [here](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW1). +/// +/// ``` +/// use etcetera::base_strategy::Apple; +/// use etcetera::base_strategy::BaseStrategy; +/// use std::path::Path; +/// +/// let base_strategy = Apple::new().unwrap(); +/// +/// let home_dir = etcetera::home_dir().unwrap(); +/// +/// assert_eq!( +/// base_strategy.home_dir(), +/// &home_dir +/// ); +/// assert_eq!( +/// base_strategy.config_dir().strip_prefix(&home_dir), +/// Ok(Path::new("Library/Preferences/")) +/// ); +/// assert_eq!( +/// base_strategy.data_dir().strip_prefix(&home_dir), +/// Ok(Path::new("Library/Application Support/")) +/// ); +/// assert_eq!( +/// base_strategy.cache_dir().strip_prefix(&home_dir), +/// Ok(Path::new("Library/Caches/")) +/// ); +/// assert_eq!( +/// base_strategy.state_dir(), +/// None +/// ); +/// assert_eq!( +/// base_strategy.runtime_dir(), +/// None +/// ); +/// ``` +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct Apple { + home_dir: PathBuf, +} +impl Apple { + /// Create a new Apple BaseStrategy + pub fn new() -> Result { + Ok(Self { + home_dir: crate::home_dir()?, + }) + } +} + +impl super::BaseStrategy for Apple { + fn home_dir(&self) -> &Path { + &self.home_dir + } + + fn config_dir(&self) -> PathBuf { + self.home_dir.join("Library/Preferences/") + } + + fn data_dir(&self) -> PathBuf { + self.home_dir.join("Library/Application Support/") + } + + fn cache_dir(&self) -> PathBuf { + self.home_dir.join("Library/Caches/") + } + + fn state_dir(&self) -> Option { + None + } + + fn runtime_dir(&self) -> Option { + None + } +} diff --git a/src/etcetera/base_strategy/windows.rs b/src/etcetera/base_strategy/windows.rs new file mode 100644 index 0000000..88bc788 --- /dev/null +++ b/src/etcetera/base_strategy/windows.rs @@ -0,0 +1,206 @@ +use std::path::{Path, PathBuf}; + +use crate::HomeDirError; + +/// This strategy follows Windows’ conventions. It seems that all Windows GUI apps, and some command-line ones follow this pattern. The specification is available [here](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). +/// +/// This initial example removes all the relevant environment variables to show the strategy’s use of the: +/// - (on Windows) SHGetKnownFolderPath API. +/// - (on non-Windows) Windows default directories. +/// +/// ``` +/// use etcetera::base_strategy::BaseStrategy; +/// use etcetera::base_strategy::Windows; +/// use std::path::Path; +/// +/// // Remove the environment variables that the strategy reads from. +/// std::env::remove_var("USERPROFILE"); +/// std::env::remove_var("APPDATA"); +/// std::env::remove_var("LOCALAPPDATA"); +/// +/// let base_strategy = Windows::new().unwrap(); +/// +/// let home_dir = etcetera::home_dir().unwrap(); +/// +/// assert_eq!( +/// base_strategy.home_dir(), +/// &home_dir +/// ); +/// assert_eq!( +/// base_strategy.config_dir().strip_prefix(&home_dir), +/// Ok(Path::new("AppData/Roaming/")) +/// ); +/// assert_eq!( +/// base_strategy.data_dir().strip_prefix(&home_dir), +/// Ok(Path::new("AppData/Roaming/")) +/// ); +/// assert_eq!( +/// base_strategy.cache_dir().strip_prefix(&home_dir), +/// Ok(Path::new("AppData/Local/")) +/// ); +/// assert_eq!( +/// base_strategy.state_dir(), +/// None +/// ); +/// assert_eq!( +/// base_strategy.runtime_dir(), +/// None +/// ); +/// ``` +/// +/// This next example gives the environment variables values: +/// +/// ``` +/// use etcetera::base_strategy::BaseStrategy; +/// use etcetera::base_strategy::Windows; +/// use std::path::Path; +/// +/// let home_path = if cfg!(windows) { +/// "C:\\foo\\".to_string() +/// } else { +/// etcetera::home_dir().unwrap().to_string_lossy().to_string() +/// }; +/// let data_path = if cfg!(windows) { +/// "C:\\bar\\" +/// } else { +/// "/bar/" +/// }; +/// let cache_path = if cfg!(windows) { +/// "C:\\baz\\" +/// } else { +/// "/baz/" +/// }; +/// +/// std::env::set_var("USERPROFILE", &home_path); +/// std::env::set_var("APPDATA", data_path); +/// std::env::set_var("LOCALAPPDATA", cache_path); +/// +/// let base_strategy = Windows::new().unwrap(); +/// +/// assert_eq!( +/// base_strategy.home_dir(), +/// Path::new(&home_path) +/// ); +/// assert_eq!( +/// base_strategy.config_dir(), +/// Path::new(data_path) +/// ); +/// assert_eq!( +/// base_strategy.data_dir(), +/// Path::new(data_path) +/// ); +/// assert_eq!( +/// base_strategy.cache_dir(), +/// Path::new(cache_path) +/// ); +/// assert_eq!( +/// base_strategy.state_dir(), +/// None +/// ); +/// assert_eq!( +/// base_strategy.runtime_dir(), +/// None +/// ); +/// ``` + +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct Windows { + home_dir: PathBuf, +} + +impl Windows { + /// Create a new Windows BaseStrategy + pub fn new() -> Result { + Ok(Self { + home_dir: crate::home_dir()?, + }) + } + + fn dir_inner(env: &'static str) -> Option { + std::env::var_os(env) + .filter(|s| !s.is_empty()) + .map(PathBuf::from) + .or_else(|| Self::dir_crt(env)) + } + + // Ref: https://github.com/rust-lang/cargo/blob/home-0.5.11/crates/home/src/windows.rs + // We should keep this code in sync with the above. + #[cfg(all(windows, not(target_vendor = "uwp")))] + fn dir_crt(env: &'static str) -> Option { + use std::ffi::OsString; + use std::os::windows::ffi::OsStringExt; + use std::ptr; + use std::slice; + + use windows_sys::Win32::Foundation::S_OK; + use windows_sys::Win32::System::Com::CoTaskMemFree; + use windows_sys::Win32::UI::Shell::{ + FOLDERID_LocalAppData, FOLDERID_RoamingAppData, SHGetKnownFolderPath, + KF_FLAG_DONT_VERIFY, + }; + + extern "C" { + fn wcslen(buf: *const u16) -> usize; + } + + let folder_id = match env { + "APPDATA" => FOLDERID_RoamingAppData, + "LOCALAPPDATA" => FOLDERID_LocalAppData, + _ => return None, + }; + + unsafe { + let mut path = ptr::null_mut(); + match SHGetKnownFolderPath( + &folder_id, + KF_FLAG_DONT_VERIFY as u32, + std::ptr::null_mut(), + &mut path, + ) { + S_OK => { + let path_slice = slice::from_raw_parts(path, wcslen(path)); + let s = OsString::from_wide(path_slice); + CoTaskMemFree(path.cast()); + Some(PathBuf::from(s)) + } + _ => { + // Free any allocated memory even on failure. A null ptr is a no-op for `CoTaskMemFree`. + CoTaskMemFree(path.cast()); + None + } + } + } + } + + #[cfg(not(all(windows, not(target_vendor = "uwp"))))] + fn dir_crt(_env: &'static str) -> Option { + None + } +} + +impl super::BaseStrategy for Windows { + fn home_dir(&self) -> &Path { + &self.home_dir + } + + fn config_dir(&self) -> PathBuf { + self.data_dir() + } + + fn data_dir(&self) -> PathBuf { + Self::dir_inner("APPDATA").unwrap_or_else(|| self.home_dir.join("AppData").join("Roaming")) + } + + fn cache_dir(&self) -> PathBuf { + Self::dir_inner("LOCALAPPDATA") + .unwrap_or_else(|| self.home_dir.join("AppData").join("Local")) + } + + fn state_dir(&self) -> Option { + None + } + + fn runtime_dir(&self) -> Option { + None + } +} diff --git a/src/etcetera/base_strategy/xdg.rs b/src/etcetera/base_strategy/xdg.rs new file mode 100644 index 0000000..65e004c --- /dev/null +++ b/src/etcetera/base_strategy/xdg.rs @@ -0,0 +1,211 @@ +use std::path::Path; +use std::path::PathBuf; + +use crate::HomeDirError; + +/// This strategy implements the [XDG Base Directories Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). It is the most common on Linux, but is increasingly being adopted elsewhere. +/// +/// This initial example removes all the XDG environment variables to show the strategy’s use of the XDG default directories. +/// +/// ``` +/// use etcetera::base_strategy::BaseStrategy; +/// use etcetera::base_strategy::Xdg; +/// use std::path::Path; +/// +/// // Remove the environment variables that the strategy reads from. +/// std::env::remove_var("XDG_CONFIG_HOME"); +/// std::env::remove_var("XDG_DATA_HOME"); +/// std::env::remove_var("XDG_CACHE_HOME"); +/// std::env::remove_var("XDG_STATE_HOME"); +/// std::env::remove_var("XDG_RUNTIME_DIR"); +/// +/// let base_strategy = Xdg::new().unwrap(); +/// +/// let home_dir = etcetera::home_dir().unwrap(); +/// +/// assert_eq!( +/// base_strategy.home_dir(), +/// &home_dir +/// ); +/// assert_eq!( +/// base_strategy.config_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".config/")) +/// ); +/// assert_eq!( +/// base_strategy.data_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".local/share/")) +/// ); +/// assert_eq!( +/// base_strategy.cache_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".cache/")) +/// ); +/// assert_eq!( +/// base_strategy.state_dir().unwrap().strip_prefix(&home_dir), +/// Ok(Path::new(".local/state")) +/// ); +/// assert_eq!( +/// base_strategy.runtime_dir(), +/// None +/// ); +/// ``` +/// +/// This next example gives the environment variables values: +/// +/// ``` +/// use etcetera::base_strategy::BaseStrategy; +/// use etcetera::base_strategy::Xdg; +/// use std::path::Path; +/// +/// // We need to conditionally set these to ensure that they are absolute paths both on Windows and other systems. +/// let config_path = if cfg!(windows) { +/// "C:\\foo\\" +/// } else { +/// "/foo/" +/// }; +/// let data_path = if cfg!(windows) { +/// "C:\\bar\\" +/// } else { +/// "/bar/" +/// }; +/// let cache_path = if cfg!(windows) { +/// "C:\\baz\\" +/// } else { +/// "/baz/" +/// }; +/// let state_path = if cfg!(windows) { +/// "C:\\foobar\\" +/// } else { +/// "/foobar/" +/// }; +/// let runtime_path = if cfg!(windows) { +/// "C:\\qux\\" +/// } else { +/// "/qux/" +/// }; +/// +/// std::env::set_var("XDG_CONFIG_HOME", config_path); +/// std::env::set_var("XDG_DATA_HOME", data_path); +/// std::env::set_var("XDG_CACHE_HOME", cache_path); +/// std::env::set_var("XDG_STATE_HOME", state_path); +/// std::env::set_var("XDG_RUNTIME_DIR", runtime_path); +/// +/// let base_strategy = Xdg::new().unwrap(); +/// +/// assert_eq!( +/// base_strategy.config_dir(), +/// Path::new(config_path) +/// ); +/// assert_eq!( +/// base_strategy.data_dir(), +/// Path::new(data_path) +/// ); +/// assert_eq!( +/// base_strategy.cache_dir(), +/// Path::new(cache_path) +/// ); +/// assert_eq!( +/// base_strategy.state_dir().unwrap(), +/// Path::new(state_path) +/// ); +/// assert_eq!( +/// base_strategy.runtime_dir().unwrap(), +/// Path::new(runtime_path) +/// ); +/// ``` +/// +/// The XDG spec requires that when the environment variables’ values are not absolute paths, their values should be ignored. This example exemplifies this behaviour: +/// +/// ``` +/// use etcetera::base_strategy::BaseStrategy; +/// use etcetera::base_strategy::Xdg; +/// use std::path::Path; +/// +/// // Remove the environment variables that the strategy reads from. +/// std::env::set_var("XDG_CONFIG_HOME", "foo/"); +/// std::env::set_var("XDG_DATA_HOME", "bar/"); +/// std::env::set_var("XDG_CACHE_HOME", "baz/"); +/// std::env::set_var("XDG_STATE_HOME", "foobar/"); +/// std::env::set_var("XDG_RUNTIME_DIR", "qux/"); +/// +/// let base_strategy = Xdg::new().unwrap(); +/// +/// let home_dir = etcetera::home_dir().unwrap(); +/// +/// // We still get the default values. +/// assert_eq!( +/// base_strategy.config_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".config/")) +/// ); +/// assert_eq!( +/// base_strategy.data_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".local/share/")) +/// ); +/// assert_eq!( +/// base_strategy.cache_dir().strip_prefix(&home_dir), +/// Ok(Path::new(".cache/")) +/// ); +/// assert_eq!( +/// base_strategy.state_dir().unwrap().strip_prefix(&home_dir), +/// Ok(Path::new(".local/state/")) +/// ); +/// assert_eq!( +/// base_strategy.runtime_dir(), +/// None +/// ); +/// ``` +#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub struct Xdg { + home_dir: PathBuf, +} + +impl Xdg { + /// Create a new Xdg BaseStrategy + pub fn new() -> Result { + Ok(Self { + home_dir: crate::home_dir()?, + }) + } + + fn env_var_or_none(env_var: &str) -> Option { + std::env::var(env_var).ok().and_then(|path| { + let path = PathBuf::from(path); + + // Return None if the path obtained from the environment variable isn’t absolute. + if path.is_absolute() { + Some(path) + } else { + None + } + }) + } + + fn env_var_or_default(&self, env_var: &str, default: impl AsRef) -> PathBuf { + Self::env_var_or_none(env_var).unwrap_or_else(|| self.home_dir.join(default)) + } +} + +impl super::BaseStrategy for Xdg { + fn home_dir(&self) -> &Path { + &self.home_dir + } + + fn config_dir(&self) -> PathBuf { + self.env_var_or_default("XDG_CONFIG_HOME", ".config/") + } + + fn data_dir(&self) -> PathBuf { + self.env_var_or_default("XDG_DATA_HOME", ".local/share/") + } + + fn cache_dir(&self) -> PathBuf { + self.env_var_or_default("XDG_CACHE_HOME", ".cache/") + } + + fn state_dir(&self) -> Option { + Some(self.env_var_or_default("XDG_STATE_HOME", ".local/state/")) + } + + fn runtime_dir(&self) -> Option { + Self::env_var_or_none("XDG_RUNTIME_DIR") + } +} diff --git a/src/etcetera/lib.rs b/src/etcetera/lib.rs new file mode 100644 index 0000000..e76468c --- /dev/null +++ b/src/etcetera/lib.rs @@ -0,0 +1,126 @@ +//! This is a Rust library that allows you to determine the locations of configuration, data, cache & other files for your application. +//! Existing Rust libraries generally do not give you a choice in terms of which standards/conventions they follow. +//! Etcetera, on the other hand, gives you the choice. +//! +//! # Conventions +//! Etcetera supports the following conventions: +//! - the [XDG base directory](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) +//! - Apple's [Standard Directories](https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html) +//! - Window's [Known Folder Locations](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid) +//! - the "Unix Single-folder Convention" i.e. everything in `~/.myapp` +//! +//! # Strategies +//! If you want to get started quickly, you can use the following convenience functions that use the default strategies (as determined arbitrarily by yours truly) or the native strategies for each OS. +//! +//! ## BaseStrategy +//! If you just want to get the path to a configuration, data, cache or another directory, you can use the `choose_base_strategy` function. +//! +//! ``` +//! use etcetera::{choose_base_strategy, BaseStrategy}; +//! +//! let strategy = choose_base_strategy().unwrap(); +//! +//! let config_dir = strategy.config_dir(); +//! let data_dir = strategy.data_dir(); +//! let cache_dir = strategy.cache_dir(); +//! let state_dir = strategy.state_dir(); +//! let runtime_dir = strategy.runtime_dir(); +//! ``` +//! +//! ## AppStrategy +//! If you want to get the path to a configuration, data, cache or another directory, and you want to follow the naming conventions for your application, you can use the `choose_app_strategy` function. +//! +//! Let’s take an application created by `Acme Corp` with the name `Frobnicator Plus` and the top-level domain of `jrg` as an example. +//! - XDG strategy would place these in `~/.config/frobnicator-plus`. +//! - Unix strategy would place these in `~/.frobnicator-plus`. +//! - Apple strategy would place these in `~/Library/Preferences/org.acme-corp.Frobnicator-Plus`. +//! - Windows strategy would place these in `~\AppData\Roaming\Acme Corp\Frobnicator Plus`. +//! +//! ``` +//! use etcetera::{choose_app_strategy, AppStrategy, AppStrategyArgs}; +//! +//! let strategy = choose_app_strategy(AppStrategyArgs { +//! top_level_domain: "org".to_string(), +//! author: "Acme Corp".to_string(), +//! app_name: "Frobnicator Plus".to_string(), +//! }).unwrap(); +//! +//! let config_dir = strategy.config_dir(); +//! let data_dir = strategy.data_dir(); +//! let cache_dir = strategy.cache_dir(); +//! let state_dir = strategy.state_dir(); +//! let runtime_dir = strategy.runtime_dir(); +//! ``` +//! +//! ## Native Strategy +//! +//! `choose_base_strategy()` and `choose_app_strategy()` will use the `XDG` strategy on Linux & macOS, and the `Windows` strategy on Windows. +//! This is used by most CLI tools & some GUI tools on each platform. +//! +//! If you're developing a GUI application, you might want to use the "Standard directories" on macOS by using `choose_native_strategy()` instead. +//! Note that if your application expects the user to modify the configuration files, you should still prefer the `XDG` strategy on macOS. +//! +//! ## Custom Conventions +//! +//! You aren’t limited to the built-in conventions – you can implement the relevant traits yourself. Please consider contributing these back, as the more preset conventions there are, the better. +//! +//! # More Examples +//! Say you were a hardened Unix veteran, and didn’t want to have any of this XDG nonsense, clutter in the home directory be damned! Instead of using `choose_app_strategy` or `choose_base_strategy`, you can pick a strategy yourself. Here’s an example using the [`Unix`](app_strategy/struct.Unix.html) strategy – see its documentation to see what kind of folder structures it produces: +//! +//! ``` +//! use etcetera::{app_strategy, AppStrategy, AppStrategyArgs}; +//! +//! let strategy = app_strategy::Unix::new(AppStrategyArgs { +//! top_level_domain: "com".to_string(), +//! author: "Hardened Unix Veteran Who Likes Short Command Names".to_string(), +//! app_name: "wry".to_string(), +//! }).unwrap(); +//! +//! let config_dir = strategy.config_dir(); // produces ~/.wry/ +//! // et cetera. +//! ``` +//! +//! Oftentimes the location of a configuration, data or cache directory is needed solely to create a path that starts inside it. For this purpose, [`AppStrategy`](app_strategy/trait.AppStrategy.html) implements a couple of convenience methods for you: +//! +//! ``` +//! use etcetera::{choose_app_strategy, AppStrategy, AppStrategyArgs}; +//! +//! let strategy = choose_app_strategy(AppStrategyArgs { +//! top_level_domain: "org".to_string(), +//! author: "Acme Corp".to_string(), +//! app_name: "Frobnicator".to_string(), +//! }).unwrap(); +//! +//! // Path to configuration directory. +//! let config_dir = strategy.config_dir(); +//! +//! // Path to config.toml inside the configuration directory. +//! let config_file = strategy.in_config_dir("config.toml"); +//! +//! assert_eq!(config_dir.join("config.toml"), config_file); +//! ``` + +#![warn(missing_docs, rust_2018_idioms, missing_debug_implementations)] + +pub mod app_strategy; +pub mod base_strategy; + +pub use app_strategy::{choose_app_strategy, AppStrategy, AppStrategyArgs}; +pub use base_strategy::{choose_base_strategy, BaseStrategy}; + +/// A convenience function that wraps the [`home_dir`](https://docs.rs/home/0.5.4/home/fn.home_dir.html) function from the [home](https://docs.rs/home) crate. +pub fn home_dir() -> Result { + home::home_dir().ok_or(HomeDirError) +} + +/// This error occurs when the home directory cannot be located. +#[derive(Debug)] +pub struct HomeDirError; + +impl std::fmt::Display for HomeDirError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "could not locate home directory") + } +} + +impl std::error::Error for HomeDirError {} From 6a2b06f3be5cba6015c58d63d7fa20127c8095e7 Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sun, 2 Mar 2025 21:57:57 -0800 Subject: [PATCH 02/10] Make etcetera buildable as module --- Cargo.lock | 104 ++++---------------------- Cargo.toml | 5 +- src/assets.rs | 2 +- src/error.rs | 1 + src/etcetera/app_strategy.rs | 2 +- src/etcetera/app_strategy/apple.rs | 4 +- src/etcetera/app_strategy/unix.rs | 4 +- src/etcetera/app_strategy/windows.rs | 4 +- src/etcetera/app_strategy/xdg.rs | 4 +- src/etcetera/base_strategy.rs | 2 +- src/etcetera/base_strategy/apple.rs | 4 +- src/etcetera/base_strategy/windows.rs | 4 +- src/etcetera/base_strategy/xdg.rs | 4 +- src/etcetera/{lib.rs => mod.rs} | 0 src/main.rs | 1 + 15 files changed, 37 insertions(+), 108 deletions(-) rename src/etcetera/{lib.rs => mod.rs} (100%) diff --git a/Cargo.lock b/Cargo.lock index b92ebe7..c75d036 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -197,10 +197,10 @@ version = "1.0.100" dependencies = [ "bat", "cargo-subcommand-metadata", + "cfg-if", "clap", "clap-cargo", "console", - "etcetera", "fs-err", "home", "prettyplease", @@ -215,6 +215,7 @@ dependencies = [ "termcolor", "toml", "toolchain_find", + "windows-sys 0.59.0", ] [[package]] @@ -411,17 +412,6 @@ dependencies = [ "windows-sys 0.59.0", ] -[[package]] -name = "etcetera" -version = "0.8.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "136d1b5283a1ab77bd9257427ffd09d8667ced0570b6f938942bc7568ed5b943" -dependencies = [ - "cfg-if", - "home", - "windows-sys 0.48.0", -] - [[package]] name = "fancy-regex" version = "0.11.0" @@ -1112,7 +1102,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1de69df01bdf1ead2f4ac895dc77c9351aefff65b2f3db429a343f9cbf05e132" dependencies = [ "windows-core", - "windows-targets 0.52.6", + "windows-targets", ] [[package]] @@ -1124,7 +1114,7 @@ dependencies = [ "windows-implement", "windows-interface", "windows-result", - "windows-targets 0.52.6", + "windows-targets", ] [[package]] @@ -1155,16 +1145,7 @@ version = "0.1.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "5e383302e8ec8515204254685643de10811af0ed97ea37210dc26fb0032647f8" dependencies = [ - "windows-targets 0.52.6", -] - -[[package]] -name = "windows-sys" -version = "0.48.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "677d2418bec65e3338edb076e806bc1ec15693c5d0104683f2efe857f61056a9" -dependencies = [ - "windows-targets 0.48.5", + "windows-targets", ] [[package]] @@ -1173,7 +1154,7 @@ version = "0.52.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d" dependencies = [ - "windows-targets 0.52.6", + "windows-targets", ] [[package]] @@ -1182,22 +1163,7 @@ version = "0.59.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" dependencies = [ - "windows-targets 0.52.6", -] - -[[package]] -name = "windows-targets" -version = "0.48.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9a2fa6e2155d7247be68c096456083145c183cbbbc2764150dda45a87197940c" -dependencies = [ - "windows_aarch64_gnullvm 0.48.5", - "windows_aarch64_msvc 0.48.5", - "windows_i686_gnu 0.48.5", - "windows_i686_msvc 0.48.5", - "windows_x86_64_gnu 0.48.5", - "windows_x86_64_gnullvm 0.48.5", - "windows_x86_64_msvc 0.48.5", + "windows-targets", ] [[package]] @@ -1206,46 +1172,28 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" dependencies = [ - "windows_aarch64_gnullvm 0.52.6", - "windows_aarch64_msvc 0.52.6", - "windows_i686_gnu 0.52.6", + "windows_aarch64_gnullvm", + "windows_aarch64_msvc", + "windows_i686_gnu", "windows_i686_gnullvm", - "windows_i686_msvc 0.52.6", - "windows_x86_64_gnu 0.52.6", - "windows_x86_64_gnullvm 0.52.6", - "windows_x86_64_msvc 0.52.6", + "windows_i686_msvc", + "windows_x86_64_gnu", + "windows_x86_64_gnullvm", + "windows_x86_64_msvc", ] -[[package]] -name = "windows_aarch64_gnullvm" -version = "0.48.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2b38e32f0abccf9987a4e3079dfb67dcd799fb61361e53e2882c3cbaf0d905d8" - [[package]] name = "windows_aarch64_gnullvm" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" -[[package]] -name = "windows_aarch64_msvc" -version = "0.48.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dc35310971f3b2dbbf3f0690a219f40e2d9afcf64f9ab7cc1be722937c26b4bc" - [[package]] name = "windows_aarch64_msvc" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" -[[package]] -name = "windows_i686_gnu" -version = "0.48.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a75915e7def60c94dcef72200b9a8e58e5091744960da64ec734a6c6e9b3743e" - [[package]] name = "windows_i686_gnu" version = "0.52.6" @@ -1258,48 +1206,24 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" -[[package]] -name = "windows_i686_msvc" -version = "0.48.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8f55c233f70c4b27f66c523580f78f1004e8b5a8b659e05a4eb49d4166cca406" - [[package]] name = "windows_i686_msvc" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" -[[package]] -name = "windows_x86_64_gnu" -version = "0.48.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "53d40abd2583d23e4718fddf1ebec84dbff8381c07cae67ff7768bbf19c6718e" - [[package]] name = "windows_x86_64_gnu" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" -[[package]] -name = "windows_x86_64_gnullvm" -version = "0.48.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0b7b52767868a23d5bab768e390dc5f5c55825b6d30b86c844ff2dc7414044cc" - [[package]] name = "windows_x86_64_gnullvm" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" -[[package]] -name = "windows_x86_64_msvc" -version = "0.48.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ed94fce61571a4006852b7389a063ab983c02eb1bb37b47f8272ce92d06d9538" - [[package]] name = "windows_x86_64_msvc" version = "0.52.6" diff --git a/Cargo.toml b/Cargo.toml index 4caea9a..75db8da 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -19,10 +19,10 @@ prettyplease = [] [dependencies] bat = { version = "0.25", default-features = false, features = ["paging", "regex-fancy"] } cargo-subcommand-metadata = "0.1" +cfg-if = "1" clap = { version = "4", features = ["deprecated", "derive"] } clap-cargo = "0.15" console = "0.15" -etcetera = "0.8" fs-err = "3" home = "0.5" prettyplease = { version = "0.2.29", features = ["verbatim"] } @@ -38,6 +38,9 @@ termcolor = "1.0" toml = "0.8" toolchain_find = "0.4" +[target.'cfg(windows)'.dependencies] +windows-sys = { version = "0.59", features = ["Win32_Foundation", "Win32_System_Com", "Win32_UI_Shell"] } + [package.metadata.docs.rs] targets = ["x86_64-unknown-linux-gnu"] diff --git a/src/assets.rs b/src/assets.rs index 67910e5..32165d8 100644 --- a/src/assets.rs +++ b/src/assets.rs @@ -1,5 +1,5 @@ use crate::error::Result; -use etcetera::BaseStrategy as _; +use crate::etcetera::{self, BaseStrategy as _}; use std::env; use std::path::PathBuf; use std::str; diff --git a/src/error.rs b/src/error.rs index ffda7b2..1620ce6 100644 --- a/src/error.rs +++ b/src/error.rs @@ -1,3 +1,4 @@ +use crate::etcetera; use std::error::Error as StdError; use std::fmt::{self, Display}; use std::io; diff --git a/src/etcetera/app_strategy.rs b/src/etcetera/app_strategy.rs index 87ca0a6..a2430c1 100644 --- a/src/etcetera/app_strategy.rs +++ b/src/etcetera/app_strategy.rs @@ -4,7 +4,7 @@ use std::ffi::OsStr; use std::path::Path; use std::path::PathBuf; -use crate::HomeDirError; +use crate::etcetera::HomeDirError; /// The arguments to the creator method of an [`AppStrategy`](trait.AppStrategy.html). #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Default)] diff --git a/src/etcetera/app_strategy/apple.rs b/src/etcetera/app_strategy/apple.rs index f06d3bc..f7b4765 100644 --- a/src/etcetera/app_strategy/apple.rs +++ b/src/etcetera/app_strategy/apple.rs @@ -1,5 +1,5 @@ -use crate::base_strategy::BaseStrategy; -use crate::{base_strategy, HomeDirError}; +use crate::etcetera::base_strategy::BaseStrategy; +use crate::etcetera::{base_strategy, HomeDirError}; use std::path::{Path, PathBuf}; /// This is the strategy created by Apple for use on macOS and iOS devices. It is always used by GUI apps on macOS, and is sometimes used by command-line applications there too. iOS only has GUIs, so all iOS applications follow this strategy. The specification is available [here](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW1). diff --git a/src/etcetera/app_strategy/unix.rs b/src/etcetera/app_strategy/unix.rs index 932a9d8..c68cb34 100644 --- a/src/etcetera/app_strategy/unix.rs +++ b/src/etcetera/app_strategy/unix.rs @@ -1,6 +1,6 @@ use std::path::{Path, PathBuf}; -use crate::HomeDirError; +use crate::etcetera::HomeDirError; /// This strategy has no standard or official specification. It has arisen over time through hundreds of Unixy tools. Vim and Cargo are notable examples whose configuration/data/cache directory layouts are similar to those created by this strategy. /// @@ -54,7 +54,7 @@ impl Unix { /// Create a new Unix AppStrategy pub fn new(args: super::AppStrategyArgs) -> Result { Ok(Self { - home_dir: crate::home_dir()?, + home_dir: crate::etcetera::home_dir()?, unixy_name: format!(".{}", args.unixy_name()), }) } diff --git a/src/etcetera/app_strategy/windows.rs b/src/etcetera/app_strategy/windows.rs index 1fe938a..733c167 100644 --- a/src/etcetera/app_strategy/windows.rs +++ b/src/etcetera/app_strategy/windows.rs @@ -1,5 +1,5 @@ -use crate::base_strategy::BaseStrategy; -use crate::{base_strategy, HomeDirError}; +use crate::etcetera::base_strategy::BaseStrategy; +use crate::etcetera::{base_strategy, HomeDirError}; use std::path::{Path, PathBuf}; /// This strategy follows Windows’ conventions. It seems that all Windows GUI apps, and some command-line ones follow this pattern. The specification is available [here](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). diff --git a/src/etcetera/app_strategy/xdg.rs b/src/etcetera/app_strategy/xdg.rs index 09f9ff0..c40291a 100644 --- a/src/etcetera/app_strategy/xdg.rs +++ b/src/etcetera/app_strategy/xdg.rs @@ -1,5 +1,5 @@ -use crate::base_strategy::BaseStrategy; -use crate::{base_strategy, HomeDirError}; +use crate::etcetera::base_strategy::BaseStrategy; +use crate::etcetera::{base_strategy, HomeDirError}; use std::path::{Path, PathBuf}; /// This strategy implements the [XDG Base Directories Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). It is the most common on Linux, but is increasingly being adopted elsewhere. diff --git a/src/etcetera/base_strategy.rs b/src/etcetera/base_strategy.rs index 80b271d..78e0d5c 100644 --- a/src/etcetera/base_strategy.rs +++ b/src/etcetera/base_strategy.rs @@ -1,6 +1,6 @@ //! These strategies simply provide the user’s configuration, data, and cache directories, without knowing about the application specifically. -use crate::HomeDirError; +use crate::etcetera::HomeDirError; use std::path::{Path, PathBuf}; /// Provides configuration, data, and cache directories of the current user. diff --git a/src/etcetera/base_strategy/apple.rs b/src/etcetera/base_strategy/apple.rs index 358119c..85ae420 100644 --- a/src/etcetera/base_strategy/apple.rs +++ b/src/etcetera/base_strategy/apple.rs @@ -1,6 +1,6 @@ use std::path::{Path, PathBuf}; -use crate::HomeDirError; +use crate::etcetera::HomeDirError; /// This is the strategy created by Apple for use on macOS and iOS devices. It is always used by GUI apps on macOS, and is sometimes used by command-line applications there too. iOS only has GUIs, so all iOS applications follow this strategy. The specification is available [here](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW1). /// @@ -46,7 +46,7 @@ impl Apple { /// Create a new Apple BaseStrategy pub fn new() -> Result { Ok(Self { - home_dir: crate::home_dir()?, + home_dir: crate::etcetera::home_dir()?, }) } } diff --git a/src/etcetera/base_strategy/windows.rs b/src/etcetera/base_strategy/windows.rs index 88bc788..0b367a9 100644 --- a/src/etcetera/base_strategy/windows.rs +++ b/src/etcetera/base_strategy/windows.rs @@ -1,6 +1,6 @@ use std::path::{Path, PathBuf}; -use crate::HomeDirError; +use crate::etcetera::HomeDirError; /// This strategy follows Windows’ conventions. It seems that all Windows GUI apps, and some command-line ones follow this pattern. The specification is available [here](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). /// @@ -112,7 +112,7 @@ impl Windows { /// Create a new Windows BaseStrategy pub fn new() -> Result { Ok(Self { - home_dir: crate::home_dir()?, + home_dir: crate::etcetera::home_dir()?, }) } diff --git a/src/etcetera/base_strategy/xdg.rs b/src/etcetera/base_strategy/xdg.rs index 65e004c..ed7569d 100644 --- a/src/etcetera/base_strategy/xdg.rs +++ b/src/etcetera/base_strategy/xdg.rs @@ -1,7 +1,7 @@ use std::path::Path; use std::path::PathBuf; -use crate::HomeDirError; +use crate::etcetera::HomeDirError; /// This strategy implements the [XDG Base Directories Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). It is the most common on Linux, but is increasingly being adopted elsewhere. /// @@ -162,7 +162,7 @@ impl Xdg { /// Create a new Xdg BaseStrategy pub fn new() -> Result { Ok(Self { - home_dir: crate::home_dir()?, + home_dir: crate::etcetera::home_dir()?, }) } diff --git a/src/etcetera/lib.rs b/src/etcetera/mod.rs similarity index 100% rename from src/etcetera/lib.rs rename to src/etcetera/mod.rs diff --git a/src/main.rs b/src/main.rs index cee76f4..d067422 100644 --- a/src/main.rs +++ b/src/main.rs @@ -21,6 +21,7 @@ mod cmd; mod config; mod edit; mod error; +mod etcetera; mod fmt; mod manifest; mod opts; From d876f6e2385d4154b583b8cd8b46ecfb9188a04f Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sun, 2 Mar 2025 22:04:57 -0800 Subject: [PATCH 03/10] Strip unused code from etcetera --- src/etcetera/app_strategy.rs | 175 --------------------- src/etcetera/app_strategy/apple.rs | 86 ---------- src/etcetera/app_strategy/unix.rs | 87 ----------- src/etcetera/app_strategy/windows.rs | 166 -------------------- src/etcetera/app_strategy/xdg.rs | 217 -------------------------- src/etcetera/base_strategy.rs | 49 +----- src/etcetera/base_strategy/apple.rs | 78 --------- src/etcetera/base_strategy/windows.rs | 125 +-------------- src/etcetera/base_strategy/xdg.rs | 172 -------------------- src/etcetera/mod.rs | 108 ------------- 10 files changed, 6 insertions(+), 1257 deletions(-) delete mode 100644 src/etcetera/app_strategy.rs delete mode 100644 src/etcetera/app_strategy/apple.rs delete mode 100644 src/etcetera/app_strategy/unix.rs delete mode 100644 src/etcetera/app_strategy/windows.rs delete mode 100644 src/etcetera/app_strategy/xdg.rs delete mode 100644 src/etcetera/base_strategy/apple.rs diff --git a/src/etcetera/app_strategy.rs b/src/etcetera/app_strategy.rs deleted file mode 100644 index a2430c1..0000000 --- a/src/etcetera/app_strategy.rs +++ /dev/null @@ -1,175 +0,0 @@ -//! These strategies require you to provide some information on your application, and they will in turn locate the configuration/data/cache directory specifically for your application. - -use std::ffi::OsStr; -use std::path::Path; -use std::path::PathBuf; - -use crate::etcetera::HomeDirError; - -/// The arguments to the creator method of an [`AppStrategy`](trait.AppStrategy.html). -#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Default)] -pub struct AppStrategyArgs { - /// The top level domain of the application, e.g. `com`, `org`, or `io.github`. - pub top_level_domain: String, - /// The name of the author of the application. - pub author: String, - /// The application’s name. This should be capitalised if appropriate. - pub app_name: String, -} - -impl AppStrategyArgs { - /// Constructs a bunde identifier from an `AppStrategyArgs`. - /// - /// ``` - /// use etcetera::app_strategy::AppStrategyArgs; - /// - /// let strategy_args = AppStrategyArgs { - /// top_level_domain: "org".to_string(), - /// author: "Acme Corp".to_string(), - /// app_name: "Frobnicator Plus".to_string(), - /// }; - /// - /// assert_eq!(strategy_args.bundle_id(), "org.acme-corp.Frobnicator-Plus".to_string()); - /// ``` - pub fn bundle_id(&self) -> String { - let author = self.author.to_lowercase().replace(' ', "-"); - let app_name = self.app_name.replace(' ', "-"); - let mut parts = vec![ - self.top_level_domain.as_str(), - author.as_str(), - app_name.as_str(), - ]; - parts.retain(|part| !part.is_empty()); - parts.join(".") - } - - /// Returns a ‘unixy’ version of the application’s name, akin to what would usually be used as a binary name. - /// - /// ``` - /// use etcetera::app_strategy::AppStrategyArgs; - /// - /// let strategy_args = AppStrategyArgs { - /// top_level_domain: "org".to_string(), - /// author: "Acme Corp".to_string(), - /// app_name: "Frobnicator Plus".to_string(), - /// }; - /// - /// assert_eq!(strategy_args.unixy_name(), "frobnicator-plus".to_string()); - /// ``` - pub fn unixy_name(&self) -> String { - self.app_name.to_lowercase().replace(' ', "-") - } -} - -macro_rules! in_dir_method { - ($self: ident, $path_extra: expr, $dir_method_name: ident) => {{ - let mut path = $self.$dir_method_name(); - path.push(Path::new(&$path_extra)); - path - }}; - (opt: $self: ident, $path_extra: expr, $dir_method_name: ident) => {{ - let mut path = $self.$dir_method_name()?; - path.push(Path::new(&$path_extra)); - Some(path) - }}; -} - -/// Allows applications to retrieve the paths of configuration, data, and cache directories specifically for them. -pub trait AppStrategy { - /// Gets the home directory of the current user. - fn home_dir(&self) -> &Path; - - /// Gets the configuration directory for your application. - fn config_dir(&self) -> PathBuf; - - /// Gets the data directory for your application. - fn data_dir(&self) -> PathBuf; - - /// Gets the cache directory for your application. - fn cache_dir(&self) -> PathBuf; - - /// Gets the state directory for your application. - /// Currently, only the [`Xdg`](struct.Xdg.html) & [`Unix`](struct.Unix.html) strategies support - /// this. - fn state_dir(&self) -> Option; - - /// Gets the runtime directory for your application. - /// Currently, only the [`Xdg`](struct.Xdg.html) & [`Unix`](struct.Unix.html) strategies support - /// this. - /// - /// Note: The [XDG Base Directory Specification](spec) places additional requirements on this - /// directory related to ownership, permissions, and persistence. This library does not check - /// these requirements. - /// - /// [spec]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html - fn runtime_dir(&self) -> Option; - - /// Constructs a path inside your application’s configuration directory to which a path of your choice has been appended. - fn in_config_dir>(&self, path: P) -> PathBuf { - in_dir_method!(self, path, config_dir) - } - - /// Constructs a path inside your application’s data directory to which a path of your choice has been appended. - fn in_data_dir>(&self, path: P) -> PathBuf { - in_dir_method!(self, path, data_dir) - } - - /// Constructs a path inside your application’s cache directory to which a path of your choice has been appended. - fn in_cache_dir>(&self, path: P) -> PathBuf { - in_dir_method!(self, path, cache_dir) - } - - /// Constructs a path inside your application’s state directory to which a path of your choice has been appended. - /// - /// Currently, this is only implemented for the [`Xdg`](struct.Xdg.html) strategy. - fn in_state_dir>(&self, path: P) -> Option { - in_dir_method!(opt: self, path, state_dir) - } - - /// Constructs a path inside your application’s runtime directory to which a path of your choice has been appended. - /// Currently, only the [`Xdg`](struct.Xdg.html) & [`Unix`](struct.Unix.html) strategies support - /// this. - /// - /// See the note in [`runtime_dir`](#method.runtime_dir) for more information. - fn in_runtime_dir>(&self, path: P) -> Option { - in_dir_method!(opt: self, path, runtime_dir) - } -} - -macro_rules! create_strategies { - ($native: ty, $app: ty) => { - /// Returns the current OS’s native [`AppStrategy`](trait.AppStrategy.html). - /// This uses the [`Windows`](struct.Windows.html) strategy on Windows, [`Apple`](struct.Apple.html) on macOS & iOS, and [`Xdg`](struct.Xdg.html) everywhere else. - /// This is the convention used by most GUI applications. - pub fn choose_native_strategy(args: AppStrategyArgs) -> Result<$native, HomeDirError> { - <$native>::new(args) - } - - /// Returns the current OS’s default [`AppStrategy`](trait.AppStrategy.html). - /// This uses the [`Windows`](struct.Windows.html) strategy on Windows, and [`Xdg`](struct.Xdg.html) everywhere else. - /// This is the convention used by most CLI applications. - pub fn choose_app_strategy(args: AppStrategyArgs) -> Result<$app, HomeDirError> { - <$app>::new(args) - } - }; -} - -cfg_if::cfg_if! { - if #[cfg(target_os = "windows")] { - create_strategies!(Windows, Windows); - } else if #[cfg(any(target_os = "macos", target_os = "ios"))] { - create_strategies!(Apple, Xdg); - } else { - create_strategies!(Xdg, Xdg); - } -} - -mod apple; -mod unix; -mod windows; -mod xdg; - -pub use apple::Apple; -pub use unix::Unix; -pub use windows::Windows; -pub use xdg::Xdg; diff --git a/src/etcetera/app_strategy/apple.rs b/src/etcetera/app_strategy/apple.rs deleted file mode 100644 index f7b4765..0000000 --- a/src/etcetera/app_strategy/apple.rs +++ /dev/null @@ -1,86 +0,0 @@ -use crate::etcetera::base_strategy::BaseStrategy; -use crate::etcetera::{base_strategy, HomeDirError}; -use std::path::{Path, PathBuf}; - -/// This is the strategy created by Apple for use on macOS and iOS devices. It is always used by GUI apps on macOS, and is sometimes used by command-line applications there too. iOS only has GUIs, so all iOS applications follow this strategy. The specification is available [here](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW1). -/// -/// ``` -/// use etcetera::app_strategy::AppStrategy; -/// use etcetera::app_strategy::AppStrategyArgs; -/// use etcetera::app_strategy::Apple; -/// use std::path::Path; -/// -/// let app_strategy = Apple::new(AppStrategyArgs { -/// top_level_domain: "org".to_string(), -/// author: "Acme Corp".to_string(), -/// app_name: "Frobnicator Plus".to_string(), -/// }).unwrap(); -/// -/// let home_dir = etcetera::home_dir().unwrap(); -/// -/// assert_eq!( -/// app_strategy.home_dir(), -/// &home_dir -/// ); -/// assert_eq!( -/// app_strategy.config_dir().strip_prefix(&home_dir), -/// Ok(Path::new("Library/Preferences/org.acme-corp.Frobnicator-Plus/")) -/// ); -/// assert_eq!( -/// app_strategy.data_dir().strip_prefix(&home_dir), -/// Ok(Path::new("Library/Application Support/org.acme-corp.Frobnicator-Plus/")) -/// ); -/// assert_eq!( -/// app_strategy.cache_dir().strip_prefix(&home_dir), -/// Ok(Path::new("Library/Caches/org.acme-corp.Frobnicator-Plus/")) -/// ); -/// assert_eq!( -/// app_strategy.state_dir(), -/// None -/// ); -/// assert_eq!( -/// app_strategy.runtime_dir(), -/// None -/// ); -/// ``` -#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] -pub struct Apple { - base_strategy: base_strategy::Apple, - bundle_id: String, -} - -impl Apple { - /// Create a new Apple AppStrategy - pub fn new(args: super::AppStrategyArgs) -> Result { - Ok(Self { - base_strategy: base_strategy::Apple::new()?, - bundle_id: args.bundle_id(), - }) - } -} - -impl super::AppStrategy for Apple { - fn home_dir(&self) -> &Path { - self.base_strategy.home_dir() - } - - fn config_dir(&self) -> PathBuf { - self.base_strategy.config_dir().join(&self.bundle_id) - } - - fn data_dir(&self) -> PathBuf { - self.base_strategy.data_dir().join(&self.bundle_id) - } - - fn cache_dir(&self) -> PathBuf { - self.base_strategy.cache_dir().join(&self.bundle_id) - } - - fn state_dir(&self) -> Option { - None - } - - fn runtime_dir(&self) -> Option { - None - } -} diff --git a/src/etcetera/app_strategy/unix.rs b/src/etcetera/app_strategy/unix.rs deleted file mode 100644 index c68cb34..0000000 --- a/src/etcetera/app_strategy/unix.rs +++ /dev/null @@ -1,87 +0,0 @@ -use std::path::{Path, PathBuf}; - -use crate::etcetera::HomeDirError; - -/// This strategy has no standard or official specification. It has arisen over time through hundreds of Unixy tools. Vim and Cargo are notable examples whose configuration/data/cache directory layouts are similar to those created by this strategy. -/// -/// ``` -/// use etcetera::app_strategy::AppStrategy; -/// use etcetera::app_strategy::AppStrategyArgs; -/// use etcetera::app_strategy::Unix; -/// use std::path::Path; -/// -/// let app_strategy = Unix::new(AppStrategyArgs { -/// top_level_domain: "org".to_string(), -/// author: "Acme Corp".to_string(), -/// app_name: "Frobnicator Plus".to_string(), -/// }).unwrap(); -/// -/// let home_dir = etcetera::home_dir().unwrap(); -/// -/// assert_eq!( -/// app_strategy.home_dir(), -/// &home_dir -/// ); -/// assert_eq!( -/// app_strategy.config_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".frobnicator-plus/")) -/// ); -/// assert_eq!( -/// app_strategy.data_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".frobnicator-plus/data/")) -/// ); -/// assert_eq!( -/// app_strategy.cache_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".frobnicator-plus/cache/")) -/// ); -/// assert_eq!( -/// app_strategy.state_dir().unwrap().strip_prefix(&home_dir), -/// Ok(Path::new(".frobnicator-plus/state/")) -/// ); -/// assert_eq!( -/// app_strategy.runtime_dir().unwrap().strip_prefix(&home_dir), -/// Ok(Path::new(".frobnicator-plus/runtime/")) -/// ); -/// ``` -#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] -pub struct Unix { - // This is `.frobnicator-plus` in the above example. - home_dir: PathBuf, - unixy_name: String, -} - -impl Unix { - /// Create a new Unix AppStrategy - pub fn new(args: super::AppStrategyArgs) -> Result { - Ok(Self { - home_dir: crate::etcetera::home_dir()?, - unixy_name: format!(".{}", args.unixy_name()), - }) - } -} - -impl super::AppStrategy for Unix { - fn home_dir(&self) -> &Path { - &self.home_dir - } - - fn config_dir(&self) -> PathBuf { - self.home_dir.join(&self.unixy_name) - } - - fn data_dir(&self) -> PathBuf { - self.home_dir.join(&self.unixy_name).join("data/") - } - - fn cache_dir(&self) -> PathBuf { - self.home_dir.join(&self.unixy_name).join("cache/") - } - - fn state_dir(&self) -> Option { - Some(self.home_dir.join(&self.unixy_name).join("state/")) - } - - fn runtime_dir(&self) -> Option { - Some(self.home_dir.join(&self.unixy_name).join("runtime/")) - } -} diff --git a/src/etcetera/app_strategy/windows.rs b/src/etcetera/app_strategy/windows.rs deleted file mode 100644 index 733c167..0000000 --- a/src/etcetera/app_strategy/windows.rs +++ /dev/null @@ -1,166 +0,0 @@ -use crate::etcetera::base_strategy::BaseStrategy; -use crate::etcetera::{base_strategy, HomeDirError}; -use std::path::{Path, PathBuf}; - -/// This strategy follows Windows’ conventions. It seems that all Windows GUI apps, and some command-line ones follow this pattern. The specification is available [here](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). -/// -/// This initial example removes all the relevant environment variables to show the strategy’s use of the: -/// - (on Windows) SHGetKnownFolderPath API. -/// - (on non-Windows) Windows default directories. -/// -/// ``` -/// use etcetera::app_strategy::AppStrategy; -/// use etcetera::app_strategy::AppStrategyArgs; -/// use etcetera::app_strategy::Windows; -/// use std::path::Path; -/// -/// // Remove the environment variables that the strategy reads from. -/// std::env::remove_var("USERPROFILE"); -/// std::env::remove_var("APPDATA"); -/// std::env::remove_var("LOCALAPPDATA"); -/// -/// let app_strategy = Windows::new(AppStrategyArgs { -/// top_level_domain: "org".to_string(), -/// author: "Acme Corp".to_string(), -/// app_name: "Frobnicator Plus".to_string(), -/// }).unwrap(); -/// -/// let home_dir = etcetera::home_dir().unwrap(); -/// -/// assert_eq!( -/// app_strategy.home_dir(), -/// &home_dir -/// ); -/// assert_eq!( -/// app_strategy.config_dir().strip_prefix(&home_dir), -/// Ok(Path::new("AppData/Roaming/Acme Corp/Frobnicator Plus/config")) -/// ); -/// assert_eq!( -/// app_strategy.data_dir().strip_prefix(&home_dir), -/// Ok(Path::new("AppData/Roaming/Acme Corp/Frobnicator Plus/data")) -/// ); -/// assert_eq!( -/// app_strategy.cache_dir().strip_prefix(&home_dir), -/// Ok(Path::new("AppData/Local/Acme Corp/Frobnicator Plus/cache")) -/// ); -/// assert_eq!( -/// app_strategy.state_dir(), -/// None -/// ); -/// assert_eq!( -/// app_strategy.runtime_dir(), -/// None -/// ); -/// ``` -/// -/// This next example gives the environment variables values: -/// -/// ``` -/// use etcetera::app_strategy::AppStrategy; -/// use etcetera::app_strategy::AppStrategyArgs; -/// use etcetera::app_strategy::Windows; -/// use std::path::Path; -/// -/// let home_path = if cfg!(windows) { -/// "C:\\my_home_location\\".to_string() -/// } else { -/// etcetera::home_dir().unwrap().to_string_lossy().to_string() -/// }; -/// let data_path = if cfg!(windows) { -/// "C:\\my_data_location\\" -/// } else { -/// "/my_data_location/" -/// }; -/// let cache_path = if cfg!(windows) { -/// "C:\\my_cache_location\\" -/// } else { -/// "/my_cache_location/" -/// }; -/// -/// std::env::set_var("USERPROFILE", &home_path); -/// std::env::set_var("APPDATA", data_path); -/// std::env::set_var("LOCALAPPDATA", cache_path); -/// -/// let app_strategy = Windows::new(AppStrategyArgs { -/// top_level_domain: "org".to_string(), -/// author: "Acme Corp".to_string(), -/// app_name: "Frobnicator Plus".to_string(), -/// }).unwrap(); -/// -/// assert_eq!( -/// app_strategy.home_dir(), -/// Path::new(&home_path) -/// ); -/// assert_eq!( -/// app_strategy.config_dir(), -/// Path::new(&format!("{}/Acme Corp/Frobnicator Plus/config", data_path)) -/// ); -/// assert_eq!( -/// app_strategy.data_dir(), -/// Path::new(&format!("{}/Acme Corp/Frobnicator Plus/data", data_path)) -/// ); -/// assert_eq!( -/// app_strategy.cache_dir(), -/// Path::new(&format!("{}/Acme Corp/Frobnicator Plus/cache", cache_path)) -/// ); -/// assert_eq!( -/// app_strategy.state_dir(), -/// None -/// ); -/// assert_eq!( -/// app_strategy.runtime_dir(), -/// None -/// ); -/// ``` - -#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] -pub struct Windows { - base_strategy: base_strategy::Windows, - author_app_name_path: PathBuf, -} - -macro_rules! dir_method { - ($self: ident, $base_strategy_method: ident, $subfolder_name: expr) => {{ - let mut path = $self.base_strategy.$base_strategy_method(); - path.push(&$self.author_app_name_path); - path.push($subfolder_name); - - path - }}; -} - -impl Windows { - /// Create a new Windows AppStrategy - pub fn new(args: super::AppStrategyArgs) -> Result { - Ok(Self { - base_strategy: base_strategy::Windows::new()?, - author_app_name_path: PathBuf::from(args.author).join(args.app_name), - }) - } -} - -impl super::AppStrategy for Windows { - fn home_dir(&self) -> &Path { - self.base_strategy.home_dir() - } - - fn config_dir(&self) -> PathBuf { - dir_method!(self, config_dir, "config") - } - - fn data_dir(&self) -> PathBuf { - dir_method!(self, data_dir, "data") - } - - fn cache_dir(&self) -> PathBuf { - dir_method!(self, cache_dir, "cache") - } - - fn state_dir(&self) -> Option { - None - } - - fn runtime_dir(&self) -> Option { - None - } -} diff --git a/src/etcetera/app_strategy/xdg.rs b/src/etcetera/app_strategy/xdg.rs deleted file mode 100644 index c40291a..0000000 --- a/src/etcetera/app_strategy/xdg.rs +++ /dev/null @@ -1,217 +0,0 @@ -use crate::etcetera::base_strategy::BaseStrategy; -use crate::etcetera::{base_strategy, HomeDirError}; -use std::path::{Path, PathBuf}; - -/// This strategy implements the [XDG Base Directories Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). It is the most common on Linux, but is increasingly being adopted elsewhere. -/// -/// This initial example removes all the XDG environment variables to show the strategy’s use of the XDG default directories. -/// -/// ``` -/// use etcetera::app_strategy::AppStrategy; -/// use etcetera::app_strategy::AppStrategyArgs; -/// use etcetera::app_strategy::Xdg; -/// use std::path::Path; -/// -/// // Remove the environment variables that the strategy reads from. -/// std::env::remove_var("XDG_CONFIG_HOME"); -/// std::env::remove_var("XDG_DATA_HOME"); -/// std::env::remove_var("XDG_CACHE_HOME"); -/// std::env::remove_var("XDG_STATE_HOME"); -/// std::env::remove_var("XDG_RUNTIME_DIR"); -/// -/// let app_strategy = Xdg::new(AppStrategyArgs { -/// top_level_domain: "org".to_string(), -/// author: "Acme Corp".to_string(), -/// app_name: "Frobnicator Plus".to_string(), -/// }).unwrap(); -/// -/// let home_dir = etcetera::home_dir().unwrap(); -/// -/// assert_eq!( -/// app_strategy.home_dir(), -/// &home_dir -/// ); -/// assert_eq!( -/// app_strategy.config_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".config/frobnicator-plus/")) -/// ); -/// assert_eq!( -/// app_strategy.data_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".local/share/frobnicator-plus/")) -/// ); -/// assert_eq!( -/// app_strategy.cache_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".cache/frobnicator-plus/")) -/// ); -/// assert_eq!( -/// app_strategy.state_dir().unwrap().strip_prefix(&home_dir), -/// Ok(Path::new(".local/state/frobnicator-plus/")) -/// ); -/// assert_eq!( -/// app_strategy.runtime_dir(), -/// None -/// ); -/// ``` -/// -/// This next example gives the environment variables values: -/// -/// ``` -/// use etcetera::app_strategy::AppStrategy; -/// use etcetera::app_strategy::AppStrategyArgs; -/// use etcetera::app_strategy::Xdg; -/// use std::path::Path; -/// -/// // We need to conditionally set these to ensure that they are absolute paths both on Windows and other systems. -/// let config_path = if cfg!(windows) { -/// "C:\\my_config_location\\" -/// } else { -/// "/my_config_location/" -/// }; -/// let data_path = if cfg!(windows) { -/// "C:\\my_data_location\\" -/// } else { -/// "/my_data_location/" -/// }; -/// let cache_path = if cfg!(windows) { -/// "C:\\my_cache_location\\" -/// } else { -/// "/my_cache_location/" -/// }; -/// let state_path = if cfg!(windows) { -/// "C:\\my_state_location\\" -/// } else { -/// "/my_state_location/" -/// }; -/// let runtime_path = if cfg!(windows) { -/// "C:\\my_runtime_location\\" -/// } else { -/// "/my_runtime_location/" -/// }; -/// -/// std::env::set_var("XDG_CONFIG_HOME", config_path); -/// std::env::set_var("XDG_DATA_HOME", data_path); -/// std::env::set_var("XDG_CACHE_HOME", cache_path); -/// std::env::set_var("XDG_STATE_HOME", state_path); -/// std::env::set_var("XDG_RUNTIME_DIR", runtime_path); -/// -/// let app_strategy = Xdg::new(AppStrategyArgs { -/// top_level_domain: "org".to_string(), -/// author: "Acme Corp".to_string(), -/// app_name: "Frobnicator Plus".to_string(), -/// }).unwrap(); -/// -/// assert_eq!( -/// app_strategy.config_dir(), -/// Path::new(&format!("{}/frobnicator-plus/", config_path)) -/// ); -/// assert_eq!( -/// app_strategy.data_dir(), -/// Path::new(&format!("{}/frobnicator-plus/", data_path)) -/// ); -/// assert_eq!( -/// app_strategy.cache_dir(), -/// Path::new(&format!("{}/frobnicator-plus/", cache_path)) -/// ); -/// assert_eq!( -/// app_strategy.state_dir().unwrap(), -/// Path::new(&format!("{}/frobnicator-plus/", state_path)) -/// ); -/// assert_eq!( -/// app_strategy.runtime_dir().unwrap(), -/// Path::new(&format!("{}/frobnicator-plus/", runtime_path)) -/// ); -/// ``` -/// -/// The XDG spec requires that when the environment variables’ values are not absolute paths, their values should be ignored. This example exemplifies this behaviour: -/// -/// ``` -/// use etcetera::app_strategy::AppStrategy; -/// use etcetera::app_strategy::AppStrategyArgs; -/// use etcetera::app_strategy::Xdg; -/// use std::path::Path; -/// -/// // Remove the environment variables that the strategy reads from. -/// std::env::set_var("XDG_CONFIG_HOME", "relative_path/"); -/// std::env::set_var("XDG_DATA_HOME", "./another_one/"); -/// std::env::set_var("XDG_CACHE_HOME", "yet_another/"); -/// std::env::set_var("XDG_STATE_HOME", "./and_another"); -/// std::env::set_var("XDG_RUNTIME_DIR", "relative_path/"); -/// -/// let app_strategy = Xdg::new(AppStrategyArgs { -/// top_level_domain: "org".to_string(), -/// author: "Acme Corp".to_string(), -/// app_name: "Frobnicator Plus".to_string(), -/// }).unwrap(); -/// -/// let home_dir = etcetera::home_dir().unwrap(); -/// -/// // We still get the default values. -/// assert_eq!( -/// app_strategy.config_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".config/frobnicator-plus/")) -/// ); -/// assert_eq!( -/// app_strategy.data_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".local/share/frobnicator-plus/")) -/// ); -/// assert_eq!( -/// app_strategy.cache_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".cache/frobnicator-plus/")) -/// ); -/// assert_eq!( -/// app_strategy.state_dir().unwrap().strip_prefix(&home_dir), -/// Ok(Path::new(".local/state/frobnicator-plus/")) -/// ); -/// assert_eq!( -/// app_strategy.runtime_dir(), -/// None -/// ); -/// ``` -#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] -pub struct Xdg { - base_strategy: base_strategy::Xdg, - unixy_name: String, -} - -impl Xdg { - /// Create a new Xdg AppStrategy - pub fn new(args: super::AppStrategyArgs) -> Result { - Ok(Self { - base_strategy: base_strategy::Xdg::new()?, - unixy_name: args.unixy_name(), - }) - } -} - -impl super::AppStrategy for Xdg { - fn home_dir(&self) -> &Path { - self.base_strategy.home_dir() - } - - fn config_dir(&self) -> PathBuf { - self.base_strategy.config_dir().join(&self.unixy_name) - } - - fn data_dir(&self) -> PathBuf { - self.base_strategy.data_dir().join(&self.unixy_name) - } - - fn cache_dir(&self) -> PathBuf { - self.base_strategy.cache_dir().join(&self.unixy_name) - } - - fn state_dir(&self) -> Option { - Some( - self.base_strategy - .state_dir() - .unwrap() - .join(&self.unixy_name), - ) - } - - fn runtime_dir(&self) -> Option { - self.base_strategy - .runtime_dir() - .map(|runtime_dir| runtime_dir.join(&self.unixy_name)) - } -} diff --git a/src/etcetera/base_strategy.rs b/src/etcetera/base_strategy.rs index 78e0d5c..aa674d8 100644 --- a/src/etcetera/base_strategy.rs +++ b/src/etcetera/base_strategy.rs @@ -1,49 +1,12 @@ -//! These strategies simply provide the user’s configuration, data, and cache directories, without knowing about the application specifically. - use crate::etcetera::HomeDirError; -use std::path::{Path, PathBuf}; +use std::path::PathBuf; -/// Provides configuration, data, and cache directories of the current user. pub trait BaseStrategy { - /// Gets the home directory of the current user. - fn home_dir(&self) -> &Path; - - /// Gets the user’s configuration directory. - fn config_dir(&self) -> PathBuf; - - /// Gets the user’s data directory. - fn data_dir(&self) -> PathBuf; - - /// Gets the user’s cache directory. fn cache_dir(&self) -> PathBuf; - - /// Gets the user’s state directory. - /// Currently, only the [`Xdg`](struct.Xdg.html) strategy supports this. - fn state_dir(&self) -> Option; - - /// Gets the user’s runtime directory. - /// Currently, only the [`Xdg`](struct.Xdg.html) strategy supports this. - /// - /// Note: The [XDG Base Directory Specification](spec) places additional requirements on this - /// directory related to ownership, permissions, and persistence. This library does not check - /// these requirements. - /// - /// [spec]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html - fn runtime_dir(&self) -> Option; } macro_rules! create_strategies { - ($native: ty, $base: ty) => { - /// Returns the current OS’s native [`BaseStrategy`](trait.BaseStrategy.html). - /// This uses the [`Windows`](struct.Windows.html) strategy on Windows, [`Apple`](struct.Apple.html) on macOS & iOS, and [`Xdg`](struct.Xdg.html) everywhere else. - /// This is the convention used by most GUI applications. - pub fn choose_native_strategy() -> Result<$native, HomeDirError> { - <$native>::new() - } - - /// Returns the current OS’s default [`BaseStrategy`](trait.BaseStrategy.html). - /// This uses the [`Windows`](struct.Windows.html) strategy on Windows, and [`Xdg`](struct.Xdg.html) everywhere else. - /// This is the convention used by most CLI applications. + ($base: ty) => { pub fn choose_base_strategy() -> Result<$base, HomeDirError> { <$base>::new() } @@ -52,18 +15,16 @@ macro_rules! create_strategies { cfg_if::cfg_if! { if #[cfg(target_os = "windows")] { - create_strategies!(Windows, Windows); + create_strategies!(Windows); } else if #[cfg(any(target_os = "macos", target_os = "ios"))] { - create_strategies!(Apple, Xdg); + create_strategies!(Xdg); } else { - create_strategies!(Xdg, Xdg); + create_strategies!(Xdg); } } -mod apple; mod windows; mod xdg; -pub use apple::Apple; pub use windows::Windows; pub use xdg::Xdg; diff --git a/src/etcetera/base_strategy/apple.rs b/src/etcetera/base_strategy/apple.rs deleted file mode 100644 index 85ae420..0000000 --- a/src/etcetera/base_strategy/apple.rs +++ /dev/null @@ -1,78 +0,0 @@ -use std::path::{Path, PathBuf}; - -use crate::etcetera::HomeDirError; - -/// This is the strategy created by Apple for use on macOS and iOS devices. It is always used by GUI apps on macOS, and is sometimes used by command-line applications there too. iOS only has GUIs, so all iOS applications follow this strategy. The specification is available [here](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW1). -/// -/// ``` -/// use etcetera::base_strategy::Apple; -/// use etcetera::base_strategy::BaseStrategy; -/// use std::path::Path; -/// -/// let base_strategy = Apple::new().unwrap(); -/// -/// let home_dir = etcetera::home_dir().unwrap(); -/// -/// assert_eq!( -/// base_strategy.home_dir(), -/// &home_dir -/// ); -/// assert_eq!( -/// base_strategy.config_dir().strip_prefix(&home_dir), -/// Ok(Path::new("Library/Preferences/")) -/// ); -/// assert_eq!( -/// base_strategy.data_dir().strip_prefix(&home_dir), -/// Ok(Path::new("Library/Application Support/")) -/// ); -/// assert_eq!( -/// base_strategy.cache_dir().strip_prefix(&home_dir), -/// Ok(Path::new("Library/Caches/")) -/// ); -/// assert_eq!( -/// base_strategy.state_dir(), -/// None -/// ); -/// assert_eq!( -/// base_strategy.runtime_dir(), -/// None -/// ); -/// ``` -#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] -pub struct Apple { - home_dir: PathBuf, -} -impl Apple { - /// Create a new Apple BaseStrategy - pub fn new() -> Result { - Ok(Self { - home_dir: crate::etcetera::home_dir()?, - }) - } -} - -impl super::BaseStrategy for Apple { - fn home_dir(&self) -> &Path { - &self.home_dir - } - - fn config_dir(&self) -> PathBuf { - self.home_dir.join("Library/Preferences/") - } - - fn data_dir(&self) -> PathBuf { - self.home_dir.join("Library/Application Support/") - } - - fn cache_dir(&self) -> PathBuf { - self.home_dir.join("Library/Caches/") - } - - fn state_dir(&self) -> Option { - None - } - - fn runtime_dir(&self) -> Option { - None - } -} diff --git a/src/etcetera/base_strategy/windows.rs b/src/etcetera/base_strategy/windows.rs index 0b367a9..c90fe34 100644 --- a/src/etcetera/base_strategy/windows.rs +++ b/src/etcetera/base_strategy/windows.rs @@ -1,115 +1,12 @@ -use std::path::{Path, PathBuf}; +use std::path::PathBuf; use crate::etcetera::HomeDirError; -/// This strategy follows Windows’ conventions. It seems that all Windows GUI apps, and some command-line ones follow this pattern. The specification is available [here](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). -/// -/// This initial example removes all the relevant environment variables to show the strategy’s use of the: -/// - (on Windows) SHGetKnownFolderPath API. -/// - (on non-Windows) Windows default directories. -/// -/// ``` -/// use etcetera::base_strategy::BaseStrategy; -/// use etcetera::base_strategy::Windows; -/// use std::path::Path; -/// -/// // Remove the environment variables that the strategy reads from. -/// std::env::remove_var("USERPROFILE"); -/// std::env::remove_var("APPDATA"); -/// std::env::remove_var("LOCALAPPDATA"); -/// -/// let base_strategy = Windows::new().unwrap(); -/// -/// let home_dir = etcetera::home_dir().unwrap(); -/// -/// assert_eq!( -/// base_strategy.home_dir(), -/// &home_dir -/// ); -/// assert_eq!( -/// base_strategy.config_dir().strip_prefix(&home_dir), -/// Ok(Path::new("AppData/Roaming/")) -/// ); -/// assert_eq!( -/// base_strategy.data_dir().strip_prefix(&home_dir), -/// Ok(Path::new("AppData/Roaming/")) -/// ); -/// assert_eq!( -/// base_strategy.cache_dir().strip_prefix(&home_dir), -/// Ok(Path::new("AppData/Local/")) -/// ); -/// assert_eq!( -/// base_strategy.state_dir(), -/// None -/// ); -/// assert_eq!( -/// base_strategy.runtime_dir(), -/// None -/// ); -/// ``` -/// -/// This next example gives the environment variables values: -/// -/// ``` -/// use etcetera::base_strategy::BaseStrategy; -/// use etcetera::base_strategy::Windows; -/// use std::path::Path; -/// -/// let home_path = if cfg!(windows) { -/// "C:\\foo\\".to_string() -/// } else { -/// etcetera::home_dir().unwrap().to_string_lossy().to_string() -/// }; -/// let data_path = if cfg!(windows) { -/// "C:\\bar\\" -/// } else { -/// "/bar/" -/// }; -/// let cache_path = if cfg!(windows) { -/// "C:\\baz\\" -/// } else { -/// "/baz/" -/// }; -/// -/// std::env::set_var("USERPROFILE", &home_path); -/// std::env::set_var("APPDATA", data_path); -/// std::env::set_var("LOCALAPPDATA", cache_path); -/// -/// let base_strategy = Windows::new().unwrap(); -/// -/// assert_eq!( -/// base_strategy.home_dir(), -/// Path::new(&home_path) -/// ); -/// assert_eq!( -/// base_strategy.config_dir(), -/// Path::new(data_path) -/// ); -/// assert_eq!( -/// base_strategy.data_dir(), -/// Path::new(data_path) -/// ); -/// assert_eq!( -/// base_strategy.cache_dir(), -/// Path::new(cache_path) -/// ); -/// assert_eq!( -/// base_strategy.state_dir(), -/// None -/// ); -/// assert_eq!( -/// base_strategy.runtime_dir(), -/// None -/// ); -/// ``` - -#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct Windows { home_dir: PathBuf, } impl Windows { - /// Create a new Windows BaseStrategy pub fn new() -> Result { Ok(Self { home_dir: crate::etcetera::home_dir()?, @@ -179,28 +76,8 @@ impl Windows { } impl super::BaseStrategy for Windows { - fn home_dir(&self) -> &Path { - &self.home_dir - } - - fn config_dir(&self) -> PathBuf { - self.data_dir() - } - - fn data_dir(&self) -> PathBuf { - Self::dir_inner("APPDATA").unwrap_or_else(|| self.home_dir.join("AppData").join("Roaming")) - } - fn cache_dir(&self) -> PathBuf { Self::dir_inner("LOCALAPPDATA") .unwrap_or_else(|| self.home_dir.join("AppData").join("Local")) } - - fn state_dir(&self) -> Option { - None - } - - fn runtime_dir(&self) -> Option { - None - } } diff --git a/src/etcetera/base_strategy/xdg.rs b/src/etcetera/base_strategy/xdg.rs index ed7569d..075d991 100644 --- a/src/etcetera/base_strategy/xdg.rs +++ b/src/etcetera/base_strategy/xdg.rs @@ -3,163 +3,11 @@ use std::path::PathBuf; use crate::etcetera::HomeDirError; -/// This strategy implements the [XDG Base Directories Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). It is the most common on Linux, but is increasingly being adopted elsewhere. -/// -/// This initial example removes all the XDG environment variables to show the strategy’s use of the XDG default directories. -/// -/// ``` -/// use etcetera::base_strategy::BaseStrategy; -/// use etcetera::base_strategy::Xdg; -/// use std::path::Path; -/// -/// // Remove the environment variables that the strategy reads from. -/// std::env::remove_var("XDG_CONFIG_HOME"); -/// std::env::remove_var("XDG_DATA_HOME"); -/// std::env::remove_var("XDG_CACHE_HOME"); -/// std::env::remove_var("XDG_STATE_HOME"); -/// std::env::remove_var("XDG_RUNTIME_DIR"); -/// -/// let base_strategy = Xdg::new().unwrap(); -/// -/// let home_dir = etcetera::home_dir().unwrap(); -/// -/// assert_eq!( -/// base_strategy.home_dir(), -/// &home_dir -/// ); -/// assert_eq!( -/// base_strategy.config_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".config/")) -/// ); -/// assert_eq!( -/// base_strategy.data_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".local/share/")) -/// ); -/// assert_eq!( -/// base_strategy.cache_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".cache/")) -/// ); -/// assert_eq!( -/// base_strategy.state_dir().unwrap().strip_prefix(&home_dir), -/// Ok(Path::new(".local/state")) -/// ); -/// assert_eq!( -/// base_strategy.runtime_dir(), -/// None -/// ); -/// ``` -/// -/// This next example gives the environment variables values: -/// -/// ``` -/// use etcetera::base_strategy::BaseStrategy; -/// use etcetera::base_strategy::Xdg; -/// use std::path::Path; -/// -/// // We need to conditionally set these to ensure that they are absolute paths both on Windows and other systems. -/// let config_path = if cfg!(windows) { -/// "C:\\foo\\" -/// } else { -/// "/foo/" -/// }; -/// let data_path = if cfg!(windows) { -/// "C:\\bar\\" -/// } else { -/// "/bar/" -/// }; -/// let cache_path = if cfg!(windows) { -/// "C:\\baz\\" -/// } else { -/// "/baz/" -/// }; -/// let state_path = if cfg!(windows) { -/// "C:\\foobar\\" -/// } else { -/// "/foobar/" -/// }; -/// let runtime_path = if cfg!(windows) { -/// "C:\\qux\\" -/// } else { -/// "/qux/" -/// }; -/// -/// std::env::set_var("XDG_CONFIG_HOME", config_path); -/// std::env::set_var("XDG_DATA_HOME", data_path); -/// std::env::set_var("XDG_CACHE_HOME", cache_path); -/// std::env::set_var("XDG_STATE_HOME", state_path); -/// std::env::set_var("XDG_RUNTIME_DIR", runtime_path); -/// -/// let base_strategy = Xdg::new().unwrap(); -/// -/// assert_eq!( -/// base_strategy.config_dir(), -/// Path::new(config_path) -/// ); -/// assert_eq!( -/// base_strategy.data_dir(), -/// Path::new(data_path) -/// ); -/// assert_eq!( -/// base_strategy.cache_dir(), -/// Path::new(cache_path) -/// ); -/// assert_eq!( -/// base_strategy.state_dir().unwrap(), -/// Path::new(state_path) -/// ); -/// assert_eq!( -/// base_strategy.runtime_dir().unwrap(), -/// Path::new(runtime_path) -/// ); -/// ``` -/// -/// The XDG spec requires that when the environment variables’ values are not absolute paths, their values should be ignored. This example exemplifies this behaviour: -/// -/// ``` -/// use etcetera::base_strategy::BaseStrategy; -/// use etcetera::base_strategy::Xdg; -/// use std::path::Path; -/// -/// // Remove the environment variables that the strategy reads from. -/// std::env::set_var("XDG_CONFIG_HOME", "foo/"); -/// std::env::set_var("XDG_DATA_HOME", "bar/"); -/// std::env::set_var("XDG_CACHE_HOME", "baz/"); -/// std::env::set_var("XDG_STATE_HOME", "foobar/"); -/// std::env::set_var("XDG_RUNTIME_DIR", "qux/"); -/// -/// let base_strategy = Xdg::new().unwrap(); -/// -/// let home_dir = etcetera::home_dir().unwrap(); -/// -/// // We still get the default values. -/// assert_eq!( -/// base_strategy.config_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".config/")) -/// ); -/// assert_eq!( -/// base_strategy.data_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".local/share/")) -/// ); -/// assert_eq!( -/// base_strategy.cache_dir().strip_prefix(&home_dir), -/// Ok(Path::new(".cache/")) -/// ); -/// assert_eq!( -/// base_strategy.state_dir().unwrap().strip_prefix(&home_dir), -/// Ok(Path::new(".local/state/")) -/// ); -/// assert_eq!( -/// base_strategy.runtime_dir(), -/// None -/// ); -/// ``` -#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct Xdg { home_dir: PathBuf, } impl Xdg { - /// Create a new Xdg BaseStrategy pub fn new() -> Result { Ok(Self { home_dir: crate::etcetera::home_dir()?, @@ -185,27 +33,7 @@ impl Xdg { } impl super::BaseStrategy for Xdg { - fn home_dir(&self) -> &Path { - &self.home_dir - } - - fn config_dir(&self) -> PathBuf { - self.env_var_or_default("XDG_CONFIG_HOME", ".config/") - } - - fn data_dir(&self) -> PathBuf { - self.env_var_or_default("XDG_DATA_HOME", ".local/share/") - } - fn cache_dir(&self) -> PathBuf { self.env_var_or_default("XDG_CACHE_HOME", ".cache/") } - - fn state_dir(&self) -> Option { - Some(self.env_var_or_default("XDG_STATE_HOME", ".local/state/")) - } - - fn runtime_dir(&self) -> Option { - Self::env_var_or_none("XDG_RUNTIME_DIR") - } } diff --git a/src/etcetera/mod.rs b/src/etcetera/mod.rs index e76468c..3bf0257 100644 --- a/src/etcetera/mod.rs +++ b/src/etcetera/mod.rs @@ -1,119 +1,11 @@ -//! This is a Rust library that allows you to determine the locations of configuration, data, cache & other files for your application. -//! Existing Rust libraries generally do not give you a choice in terms of which standards/conventions they follow. -//! Etcetera, on the other hand, gives you the choice. -//! -//! # Conventions -//! Etcetera supports the following conventions: -//! - the [XDG base directory](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) -//! - Apple's [Standard Directories](https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html) -//! - Window's [Known Folder Locations](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid) -//! - the "Unix Single-folder Convention" i.e. everything in `~/.myapp` -//! -//! # Strategies -//! If you want to get started quickly, you can use the following convenience functions that use the default strategies (as determined arbitrarily by yours truly) or the native strategies for each OS. -//! -//! ## BaseStrategy -//! If you just want to get the path to a configuration, data, cache or another directory, you can use the `choose_base_strategy` function. -//! -//! ``` -//! use etcetera::{choose_base_strategy, BaseStrategy}; -//! -//! let strategy = choose_base_strategy().unwrap(); -//! -//! let config_dir = strategy.config_dir(); -//! let data_dir = strategy.data_dir(); -//! let cache_dir = strategy.cache_dir(); -//! let state_dir = strategy.state_dir(); -//! let runtime_dir = strategy.runtime_dir(); -//! ``` -//! -//! ## AppStrategy -//! If you want to get the path to a configuration, data, cache or another directory, and you want to follow the naming conventions for your application, you can use the `choose_app_strategy` function. -//! -//! Let’s take an application created by `Acme Corp` with the name `Frobnicator Plus` and the top-level domain of `jrg` as an example. -//! - XDG strategy would place these in `~/.config/frobnicator-plus`. -//! - Unix strategy would place these in `~/.frobnicator-plus`. -//! - Apple strategy would place these in `~/Library/Preferences/org.acme-corp.Frobnicator-Plus`. -//! - Windows strategy would place these in `~\AppData\Roaming\Acme Corp\Frobnicator Plus`. -//! -//! ``` -//! use etcetera::{choose_app_strategy, AppStrategy, AppStrategyArgs}; -//! -//! let strategy = choose_app_strategy(AppStrategyArgs { -//! top_level_domain: "org".to_string(), -//! author: "Acme Corp".to_string(), -//! app_name: "Frobnicator Plus".to_string(), -//! }).unwrap(); -//! -//! let config_dir = strategy.config_dir(); -//! let data_dir = strategy.data_dir(); -//! let cache_dir = strategy.cache_dir(); -//! let state_dir = strategy.state_dir(); -//! let runtime_dir = strategy.runtime_dir(); -//! ``` -//! -//! ## Native Strategy -//! -//! `choose_base_strategy()` and `choose_app_strategy()` will use the `XDG` strategy on Linux & macOS, and the `Windows` strategy on Windows. -//! This is used by most CLI tools & some GUI tools on each platform. -//! -//! If you're developing a GUI application, you might want to use the "Standard directories" on macOS by using `choose_native_strategy()` instead. -//! Note that if your application expects the user to modify the configuration files, you should still prefer the `XDG` strategy on macOS. -//! -//! ## Custom Conventions -//! -//! You aren’t limited to the built-in conventions – you can implement the relevant traits yourself. Please consider contributing these back, as the more preset conventions there are, the better. -//! -//! # More Examples -//! Say you were a hardened Unix veteran, and didn’t want to have any of this XDG nonsense, clutter in the home directory be damned! Instead of using `choose_app_strategy` or `choose_base_strategy`, you can pick a strategy yourself. Here’s an example using the [`Unix`](app_strategy/struct.Unix.html) strategy – see its documentation to see what kind of folder structures it produces: -//! -//! ``` -//! use etcetera::{app_strategy, AppStrategy, AppStrategyArgs}; -//! -//! let strategy = app_strategy::Unix::new(AppStrategyArgs { -//! top_level_domain: "com".to_string(), -//! author: "Hardened Unix Veteran Who Likes Short Command Names".to_string(), -//! app_name: "wry".to_string(), -//! }).unwrap(); -//! -//! let config_dir = strategy.config_dir(); // produces ~/.wry/ -//! // et cetera. -//! ``` -//! -//! Oftentimes the location of a configuration, data or cache directory is needed solely to create a path that starts inside it. For this purpose, [`AppStrategy`](app_strategy/trait.AppStrategy.html) implements a couple of convenience methods for you: -//! -//! ``` -//! use etcetera::{choose_app_strategy, AppStrategy, AppStrategyArgs}; -//! -//! let strategy = choose_app_strategy(AppStrategyArgs { -//! top_level_domain: "org".to_string(), -//! author: "Acme Corp".to_string(), -//! app_name: "Frobnicator".to_string(), -//! }).unwrap(); -//! -//! // Path to configuration directory. -//! let config_dir = strategy.config_dir(); -//! -//! // Path to config.toml inside the configuration directory. -//! let config_file = strategy.in_config_dir("config.toml"); -//! -//! assert_eq!(config_dir.join("config.toml"), config_file); -//! ``` - -#![warn(missing_docs, rust_2018_idioms, missing_debug_implementations)] - -pub mod app_strategy; pub mod base_strategy; -pub use app_strategy::{choose_app_strategy, AppStrategy, AppStrategyArgs}; pub use base_strategy::{choose_base_strategy, BaseStrategy}; -/// A convenience function that wraps the [`home_dir`](https://docs.rs/home/0.5.4/home/fn.home_dir.html) function from the [home](https://docs.rs/home) crate. pub fn home_dir() -> Result { home::home_dir().ok_or(HomeDirError) } -/// This error occurs when the home directory cannot be located. #[derive(Debug)] pub struct HomeDirError; From b1a731c5f782c27825c53299063f622dbabf17b5 Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sun, 2 Mar 2025 22:18:55 -0800 Subject: [PATCH 04/10] Combine error types --- src/error.rs | 13 +++---------- src/etcetera/base_strategy.rs | 4 ++-- src/etcetera/base_strategy/windows.rs | 5 ++--- src/etcetera/base_strategy/xdg.rs | 5 ++--- src/etcetera/mod.rs | 17 ++++------------- 5 files changed, 13 insertions(+), 31 deletions(-) diff --git a/src/error.rs b/src/error.rs index 1620ce6..3d7ec41 100644 --- a/src/error.rs +++ b/src/error.rs @@ -1,4 +1,3 @@ -use crate::etcetera; use std::error::Error as StdError; use std::fmt::{self, Display}; use std::io; @@ -9,7 +8,7 @@ pub enum Error { TomlSer(toml::ser::Error), TomlDe(toml::de::Error), Quote(shlex::QuoteError), - HomeDir(etcetera::HomeDirError), + HomeDir, Bat(bat::error::Error), } @@ -39,12 +38,6 @@ impl From for Error { } } -impl From for Error { - fn from(error: etcetera::HomeDirError) -> Self { - Error::HomeDir(error) - } -} - impl From for Error { fn from(error: bat::error::Error) -> Self { Error::Bat(error) @@ -58,7 +51,7 @@ impl Display for Error { Error::TomlSer(e) => e.fmt(formatter), Error::TomlDe(e) => e.fmt(formatter), Error::Quote(e) => e.fmt(formatter), - Error::HomeDir(e) => e.fmt(formatter), + Error::HomeDir => formatter.write_str("could not locate home directory"), Error::Bat(e) => e.fmt(formatter), } } @@ -71,7 +64,7 @@ impl StdError for Error { Error::TomlSer(e) => e.source(), Error::TomlDe(e) => e.source(), Error::Quote(e) => e.source(), - Error::HomeDir(e) => e.source(), + Error::HomeDir => None, Error::Bat(e) => e.source(), } } diff --git a/src/etcetera/base_strategy.rs b/src/etcetera/base_strategy.rs index aa674d8..f3ed44e 100644 --- a/src/etcetera/base_strategy.rs +++ b/src/etcetera/base_strategy.rs @@ -1,4 +1,4 @@ -use crate::etcetera::HomeDirError; +use crate::error::Result; use std::path::PathBuf; pub trait BaseStrategy { @@ -7,7 +7,7 @@ pub trait BaseStrategy { macro_rules! create_strategies { ($base: ty) => { - pub fn choose_base_strategy() -> Result<$base, HomeDirError> { + pub fn choose_base_strategy() -> Result<$base> { <$base>::new() } }; diff --git a/src/etcetera/base_strategy/windows.rs b/src/etcetera/base_strategy/windows.rs index c90fe34..e3756b9 100644 --- a/src/etcetera/base_strategy/windows.rs +++ b/src/etcetera/base_strategy/windows.rs @@ -1,13 +1,12 @@ +use crate::error::Result; use std::path::PathBuf; -use crate::etcetera::HomeDirError; - pub struct Windows { home_dir: PathBuf, } impl Windows { - pub fn new() -> Result { + pub fn new() -> Result { Ok(Self { home_dir: crate::etcetera::home_dir()?, }) diff --git a/src/etcetera/base_strategy/xdg.rs b/src/etcetera/base_strategy/xdg.rs index 075d991..d22369e 100644 --- a/src/etcetera/base_strategy/xdg.rs +++ b/src/etcetera/base_strategy/xdg.rs @@ -1,14 +1,13 @@ +use crate::error::Result; use std::path::Path; use std::path::PathBuf; -use crate::etcetera::HomeDirError; - pub struct Xdg { home_dir: PathBuf, } impl Xdg { - pub fn new() -> Result { + pub fn new() -> Result { Ok(Self { home_dir: crate::etcetera::home_dir()?, }) diff --git a/src/etcetera/mod.rs b/src/etcetera/mod.rs index 3bf0257..708f6bf 100644 --- a/src/etcetera/mod.rs +++ b/src/etcetera/mod.rs @@ -1,18 +1,9 @@ +use crate::error::{Error, Result}; + pub mod base_strategy; pub use base_strategy::{choose_base_strategy, BaseStrategy}; -pub fn home_dir() -> Result { - home::home_dir().ok_or(HomeDirError) +pub fn home_dir() -> Result { + home::home_dir().ok_or(Error::HomeDir) } - -#[derive(Debug)] -pub struct HomeDirError; - -impl std::fmt::Display for HomeDirError { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - write!(f, "could not locate home directory") - } -} - -impl std::error::Error for HomeDirError {} From 69f8fad695ca20f6b72e48be49dc409fa0beb7ae Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sun, 2 Mar 2025 22:23:42 -0800 Subject: [PATCH 05/10] Inline etcetera modules into a single file --- src/etcetera.rs | 163 ++++++++++++++++++++++++++ src/etcetera/base_strategy.rs | 30 ----- src/etcetera/base_strategy/windows.rs | 82 ------------- src/etcetera/base_strategy/xdg.rs | 38 ------ src/etcetera/mod.rs | 9 -- 5 files changed, 163 insertions(+), 159 deletions(-) create mode 100644 src/etcetera.rs delete mode 100644 src/etcetera/base_strategy.rs delete mode 100644 src/etcetera/base_strategy/windows.rs delete mode 100644 src/etcetera/base_strategy/xdg.rs delete mode 100644 src/etcetera/mod.rs diff --git a/src/etcetera.rs b/src/etcetera.rs new file mode 100644 index 0000000..e5a6fff --- /dev/null +++ b/src/etcetera.rs @@ -0,0 +1,163 @@ +use crate::error::{Error, Result}; + +pub mod base_strategy { + use crate::error::Result; + use std::path::PathBuf; + + pub trait BaseStrategy { + fn cache_dir(&self) -> PathBuf; + } + + macro_rules! create_strategies { + ($base: ty) => { + pub fn choose_base_strategy() -> Result<$base> { + <$base>::new() + } + }; + } + + cfg_if::cfg_if! { + if #[cfg(target_os = "windows")] { + create_strategies!(Windows); + } else if #[cfg(any(target_os = "macos", target_os = "ios"))] { + create_strategies!(Xdg); + } else { + create_strategies!(Xdg); + } + } + + mod windows { + use crate::error::Result; + use std::path::PathBuf; + + pub struct Windows { + home_dir: PathBuf, + } + + impl Windows { + pub fn new() -> Result { + Ok(Self { + home_dir: crate::etcetera::home_dir()?, + }) + } + + fn dir_inner(env: &'static str) -> Option { + std::env::var_os(env) + .filter(|s| !s.is_empty()) + .map(PathBuf::from) + .or_else(|| Self::dir_crt(env)) + } + + // Ref: https://github.com/rust-lang/cargo/blob/home-0.5.11/crates/home/src/windows.rs + // We should keep this code in sync with the above. + #[cfg(all(windows, not(target_vendor = "uwp")))] + fn dir_crt(env: &'static str) -> Option { + use std::ffi::OsString; + use std::os::windows::ffi::OsStringExt; + use std::ptr; + use std::slice; + + use windows_sys::Win32::Foundation::S_OK; + use windows_sys::Win32::System::Com::CoTaskMemFree; + use windows_sys::Win32::UI::Shell::{ + FOLDERID_LocalAppData, FOLDERID_RoamingAppData, SHGetKnownFolderPath, + KF_FLAG_DONT_VERIFY, + }; + + extern "C" { + fn wcslen(buf: *const u16) -> usize; + } + + let folder_id = match env { + "APPDATA" => FOLDERID_RoamingAppData, + "LOCALAPPDATA" => FOLDERID_LocalAppData, + _ => return None, + }; + + unsafe { + let mut path = ptr::null_mut(); + match SHGetKnownFolderPath( + &folder_id, + KF_FLAG_DONT_VERIFY as u32, + std::ptr::null_mut(), + &mut path, + ) { + S_OK => { + let path_slice = slice::from_raw_parts(path, wcslen(path)); + let s = OsString::from_wide(path_slice); + CoTaskMemFree(path.cast()); + Some(PathBuf::from(s)) + } + _ => { + // Free any allocated memory even on failure. A null ptr is a no-op for `CoTaskMemFree`. + CoTaskMemFree(path.cast()); + None + } + } + } + } + + #[cfg(not(all(windows, not(target_vendor = "uwp"))))] + fn dir_crt(_env: &'static str) -> Option { + None + } + } + + impl super::BaseStrategy for Windows { + fn cache_dir(&self) -> PathBuf { + Self::dir_inner("LOCALAPPDATA") + .unwrap_or_else(|| self.home_dir.join("AppData").join("Local")) + } + } + } + + mod xdg { + use crate::error::Result; + use std::path::Path; + use std::path::PathBuf; + + pub struct Xdg { + home_dir: PathBuf, + } + + impl Xdg { + pub fn new() -> Result { + Ok(Self { + home_dir: crate::etcetera::home_dir()?, + }) + } + + fn env_var_or_none(env_var: &str) -> Option { + std::env::var(env_var).ok().and_then(|path| { + let path = PathBuf::from(path); + + // Return None if the path obtained from the environment variable isn’t absolute. + if path.is_absolute() { + Some(path) + } else { + None + } + }) + } + + fn env_var_or_default(&self, env_var: &str, default: impl AsRef) -> PathBuf { + Self::env_var_or_none(env_var).unwrap_or_else(|| self.home_dir.join(default)) + } + } + + impl super::BaseStrategy for Xdg { + fn cache_dir(&self) -> PathBuf { + self.env_var_or_default("XDG_CACHE_HOME", ".cache/") + } + } + } + + pub use windows::Windows; + pub use xdg::Xdg; +} + +pub use base_strategy::{choose_base_strategy, BaseStrategy}; + +pub fn home_dir() -> Result { + home::home_dir().ok_or(Error::HomeDir) +} diff --git a/src/etcetera/base_strategy.rs b/src/etcetera/base_strategy.rs deleted file mode 100644 index f3ed44e..0000000 --- a/src/etcetera/base_strategy.rs +++ /dev/null @@ -1,30 +0,0 @@ -use crate::error::Result; -use std::path::PathBuf; - -pub trait BaseStrategy { - fn cache_dir(&self) -> PathBuf; -} - -macro_rules! create_strategies { - ($base: ty) => { - pub fn choose_base_strategy() -> Result<$base> { - <$base>::new() - } - }; -} - -cfg_if::cfg_if! { - if #[cfg(target_os = "windows")] { - create_strategies!(Windows); - } else if #[cfg(any(target_os = "macos", target_os = "ios"))] { - create_strategies!(Xdg); - } else { - create_strategies!(Xdg); - } -} - -mod windows; -mod xdg; - -pub use windows::Windows; -pub use xdg::Xdg; diff --git a/src/etcetera/base_strategy/windows.rs b/src/etcetera/base_strategy/windows.rs deleted file mode 100644 index e3756b9..0000000 --- a/src/etcetera/base_strategy/windows.rs +++ /dev/null @@ -1,82 +0,0 @@ -use crate::error::Result; -use std::path::PathBuf; - -pub struct Windows { - home_dir: PathBuf, -} - -impl Windows { - pub fn new() -> Result { - Ok(Self { - home_dir: crate::etcetera::home_dir()?, - }) - } - - fn dir_inner(env: &'static str) -> Option { - std::env::var_os(env) - .filter(|s| !s.is_empty()) - .map(PathBuf::from) - .or_else(|| Self::dir_crt(env)) - } - - // Ref: https://github.com/rust-lang/cargo/blob/home-0.5.11/crates/home/src/windows.rs - // We should keep this code in sync with the above. - #[cfg(all(windows, not(target_vendor = "uwp")))] - fn dir_crt(env: &'static str) -> Option { - use std::ffi::OsString; - use std::os::windows::ffi::OsStringExt; - use std::ptr; - use std::slice; - - use windows_sys::Win32::Foundation::S_OK; - use windows_sys::Win32::System::Com::CoTaskMemFree; - use windows_sys::Win32::UI::Shell::{ - FOLDERID_LocalAppData, FOLDERID_RoamingAppData, SHGetKnownFolderPath, - KF_FLAG_DONT_VERIFY, - }; - - extern "C" { - fn wcslen(buf: *const u16) -> usize; - } - - let folder_id = match env { - "APPDATA" => FOLDERID_RoamingAppData, - "LOCALAPPDATA" => FOLDERID_LocalAppData, - _ => return None, - }; - - unsafe { - let mut path = ptr::null_mut(); - match SHGetKnownFolderPath( - &folder_id, - KF_FLAG_DONT_VERIFY as u32, - std::ptr::null_mut(), - &mut path, - ) { - S_OK => { - let path_slice = slice::from_raw_parts(path, wcslen(path)); - let s = OsString::from_wide(path_slice); - CoTaskMemFree(path.cast()); - Some(PathBuf::from(s)) - } - _ => { - // Free any allocated memory even on failure. A null ptr is a no-op for `CoTaskMemFree`. - CoTaskMemFree(path.cast()); - None - } - } - } - } - - #[cfg(not(all(windows, not(target_vendor = "uwp"))))] - fn dir_crt(_env: &'static str) -> Option { - None - } -} - -impl super::BaseStrategy for Windows { - fn cache_dir(&self) -> PathBuf { - Self::dir_inner("LOCALAPPDATA") - .unwrap_or_else(|| self.home_dir.join("AppData").join("Local")) - } -} diff --git a/src/etcetera/base_strategy/xdg.rs b/src/etcetera/base_strategy/xdg.rs deleted file mode 100644 index d22369e..0000000 --- a/src/etcetera/base_strategy/xdg.rs +++ /dev/null @@ -1,38 +0,0 @@ -use crate::error::Result; -use std::path::Path; -use std::path::PathBuf; - -pub struct Xdg { - home_dir: PathBuf, -} - -impl Xdg { - pub fn new() -> Result { - Ok(Self { - home_dir: crate::etcetera::home_dir()?, - }) - } - - fn env_var_or_none(env_var: &str) -> Option { - std::env::var(env_var).ok().and_then(|path| { - let path = PathBuf::from(path); - - // Return None if the path obtained from the environment variable isn’t absolute. - if path.is_absolute() { - Some(path) - } else { - None - } - }) - } - - fn env_var_or_default(&self, env_var: &str, default: impl AsRef) -> PathBuf { - Self::env_var_or_none(env_var).unwrap_or_else(|| self.home_dir.join(default)) - } -} - -impl super::BaseStrategy for Xdg { - fn cache_dir(&self) -> PathBuf { - self.env_var_or_default("XDG_CACHE_HOME", ".cache/") - } -} diff --git a/src/etcetera/mod.rs b/src/etcetera/mod.rs deleted file mode 100644 index 708f6bf..0000000 --- a/src/etcetera/mod.rs +++ /dev/null @@ -1,9 +0,0 @@ -use crate::error::{Error, Result}; - -pub mod base_strategy; - -pub use base_strategy::{choose_base_strategy, BaseStrategy}; - -pub fn home_dir() -> Result { - home::home_dir().ok_or(Error::HomeDir) -} From a58bd1a6ca7900a80aba3826a7f6cbf2ddb286e7 Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sun, 2 Mar 2025 22:27:38 -0800 Subject: [PATCH 06/10] Simplify interface to obtaining cache_dir --- Cargo.lock | 1 - Cargo.toml | 1 - src/assets.rs | 6 +- src/etcetera.rs | 226 ++++++++++++++++++------------------------------ 4 files changed, 87 insertions(+), 147 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index c75d036..ea2b5f4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -197,7 +197,6 @@ version = "1.0.100" dependencies = [ "bat", "cargo-subcommand-metadata", - "cfg-if", "clap", "clap-cargo", "console", diff --git a/Cargo.toml b/Cargo.toml index 75db8da..a02bffe 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -19,7 +19,6 @@ prettyplease = [] [dependencies] bat = { version = "0.25", default-features = false, features = ["paging", "regex-fancy"] } cargo-subcommand-metadata = "0.1" -cfg-if = "1" clap = { version = "4", features = ["deprecated", "derive"] } clap-cargo = "0.15" console = "0.15" diff --git a/src/assets.rs b/src/assets.rs index 32165d8..b01a2ac 100644 --- a/src/assets.rs +++ b/src/assets.rs @@ -1,5 +1,5 @@ use crate::error::Result; -use crate::etcetera::{self, BaseStrategy as _}; +use crate::etcetera; use std::env; use std::path::PathBuf; use std::str; @@ -21,6 +21,6 @@ pub fn cache_dir() -> Result { return Ok(PathBuf::from(cache_dir)); } - let basedirs = etcetera::choose_base_strategy()?; - Ok(basedirs.cache_dir().join("bat")) + let cache_dir = etcetera::cache_dir()?; + Ok(cache_dir.join("bat")) } diff --git a/src/etcetera.rs b/src/etcetera.rs index e5a6fff..a8af857 100644 --- a/src/etcetera.rs +++ b/src/etcetera.rs @@ -1,163 +1,105 @@ use crate::error::{Error, Result}; +use std::path::PathBuf; -pub mod base_strategy { - use crate::error::Result; - use std::path::PathBuf; +pub fn cache_dir() -> Result { + let home_dir = home::home_dir().ok_or(Error::HomeDir)?; + if cfg!(windows) { + Ok(windows::cache_dir(&home_dir)) + } else { + Ok(xdg::cache_dir(&home_dir)) + } +} - pub trait BaseStrategy { - fn cache_dir(&self) -> PathBuf; +mod windows { + use std::path::{Path, PathBuf}; + + fn dir_inner(env: &'static str) -> Option { + std::env::var_os(env) + .filter(|s| !s.is_empty()) + .map(PathBuf::from) + .or_else(|| dir_crt(env)) } - macro_rules! create_strategies { - ($base: ty) => { - pub fn choose_base_strategy() -> Result<$base> { - <$base>::new() - } + // Ref: https://github.com/rust-lang/cargo/blob/home-0.5.11/crates/home/src/windows.rs + // We should keep this code in sync with the above. + #[cfg(all(windows, not(target_vendor = "uwp")))] + fn dir_crt(env: &'static str) -> Option { + use std::ffi::OsString; + use std::os::windows::ffi::OsStringExt; + use std::ptr; + use std::slice; + + use windows_sys::Win32::Foundation::S_OK; + use windows_sys::Win32::System::Com::CoTaskMemFree; + use windows_sys::Win32::UI::Shell::{ + FOLDERID_LocalAppData, FOLDERID_RoamingAppData, SHGetKnownFolderPath, + KF_FLAG_DONT_VERIFY, }; - } - cfg_if::cfg_if! { - if #[cfg(target_os = "windows")] { - create_strategies!(Windows); - } else if #[cfg(any(target_os = "macos", target_os = "ios"))] { - create_strategies!(Xdg); - } else { - create_strategies!(Xdg); + extern "C" { + fn wcslen(buf: *const u16) -> usize; + } + + let folder_id = match env { + "APPDATA" => FOLDERID_RoamingAppData, + "LOCALAPPDATA" => FOLDERID_LocalAppData, + _ => return None, + }; + + unsafe { + let mut path = ptr::null_mut(); + match SHGetKnownFolderPath( + &folder_id, + KF_FLAG_DONT_VERIFY as u32, + std::ptr::null_mut(), + &mut path, + ) { + S_OK => { + let path_slice = slice::from_raw_parts(path, wcslen(path)); + let s = OsString::from_wide(path_slice); + CoTaskMemFree(path.cast()); + Some(PathBuf::from(s)) + } + _ => { + // Free any allocated memory even on failure. A null ptr is a no-op for `CoTaskMemFree`. + CoTaskMemFree(path.cast()); + None + } + } } } - mod windows { - use crate::error::Result; - use std::path::PathBuf; + #[cfg(not(all(windows, not(target_vendor = "uwp"))))] + fn dir_crt(_env: &'static str) -> Option { + None + } - pub struct Windows { - home_dir: PathBuf, - } + pub fn cache_dir(home_dir: &Path) -> PathBuf { + dir_inner("LOCALAPPDATA").unwrap_or_else(|| home_dir.join("AppData").join("Local")) + } +} - impl Windows { - pub fn new() -> Result { - Ok(Self { - home_dir: crate::etcetera::home_dir()?, - }) - } +mod xdg { + use std::path::{Path, PathBuf}; - fn dir_inner(env: &'static str) -> Option { - std::env::var_os(env) - .filter(|s| !s.is_empty()) - .map(PathBuf::from) - .or_else(|| Self::dir_crt(env)) - } + fn env_var_or_none(env_var: &str) -> Option { + std::env::var(env_var).ok().and_then(|path| { + let path = PathBuf::from(path); - // Ref: https://github.com/rust-lang/cargo/blob/home-0.5.11/crates/home/src/windows.rs - // We should keep this code in sync with the above. - #[cfg(all(windows, not(target_vendor = "uwp")))] - fn dir_crt(env: &'static str) -> Option { - use std::ffi::OsString; - use std::os::windows::ffi::OsStringExt; - use std::ptr; - use std::slice; - - use windows_sys::Win32::Foundation::S_OK; - use windows_sys::Win32::System::Com::CoTaskMemFree; - use windows_sys::Win32::UI::Shell::{ - FOLDERID_LocalAppData, FOLDERID_RoamingAppData, SHGetKnownFolderPath, - KF_FLAG_DONT_VERIFY, - }; - - extern "C" { - fn wcslen(buf: *const u16) -> usize; - } - - let folder_id = match env { - "APPDATA" => FOLDERID_RoamingAppData, - "LOCALAPPDATA" => FOLDERID_LocalAppData, - _ => return None, - }; - - unsafe { - let mut path = ptr::null_mut(); - match SHGetKnownFolderPath( - &folder_id, - KF_FLAG_DONT_VERIFY as u32, - std::ptr::null_mut(), - &mut path, - ) { - S_OK => { - let path_slice = slice::from_raw_parts(path, wcslen(path)); - let s = OsString::from_wide(path_slice); - CoTaskMemFree(path.cast()); - Some(PathBuf::from(s)) - } - _ => { - // Free any allocated memory even on failure. A null ptr is a no-op for `CoTaskMemFree`. - CoTaskMemFree(path.cast()); - None - } - } - } - } - - #[cfg(not(all(windows, not(target_vendor = "uwp"))))] - fn dir_crt(_env: &'static str) -> Option { + // Return None if the path obtained from the environment variable isn’t absolute. + if path.is_absolute() { + Some(path) + } else { None } - } - - impl super::BaseStrategy for Windows { - fn cache_dir(&self) -> PathBuf { - Self::dir_inner("LOCALAPPDATA") - .unwrap_or_else(|| self.home_dir.join("AppData").join("Local")) - } - } + }) } - mod xdg { - use crate::error::Result; - use std::path::Path; - use std::path::PathBuf; - - pub struct Xdg { - home_dir: PathBuf, - } - - impl Xdg { - pub fn new() -> Result { - Ok(Self { - home_dir: crate::etcetera::home_dir()?, - }) - } - - fn env_var_or_none(env_var: &str) -> Option { - std::env::var(env_var).ok().and_then(|path| { - let path = PathBuf::from(path); - - // Return None if the path obtained from the environment variable isn’t absolute. - if path.is_absolute() { - Some(path) - } else { - None - } - }) - } - - fn env_var_or_default(&self, env_var: &str, default: impl AsRef) -> PathBuf { - Self::env_var_or_none(env_var).unwrap_or_else(|| self.home_dir.join(default)) - } - } - - impl super::BaseStrategy for Xdg { - fn cache_dir(&self) -> PathBuf { - self.env_var_or_default("XDG_CACHE_HOME", ".cache/") - } - } + fn env_var_or_default(home_dir: &Path, env_var: &str, default: impl AsRef) -> PathBuf { + env_var_or_none(env_var).unwrap_or_else(|| home_dir.join(default)) } - pub use windows::Windows; - pub use xdg::Xdg; -} - -pub use base_strategy::{choose_base_strategy, BaseStrategy}; - -pub fn home_dir() -> Result { - home::home_dir().ok_or(Error::HomeDir) + pub fn cache_dir(home_dir: &Path) -> PathBuf { + env_var_or_default(home_dir, "XDG_CACHE_HOME", ".cache/") + } } From d46967c7454c2e3e2df852a4637ebdd32bc4900d Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sun, 2 Mar 2025 22:36:57 -0800 Subject: [PATCH 07/10] Inline cache_dir into assets module --- src/assets.rs | 106 ++++++++++++++++++++++++++++++++++++++++++++++-- src/etcetera.rs | 105 ----------------------------------------------- src/main.rs | 1 - 3 files changed, 103 insertions(+), 109 deletions(-) delete mode 100644 src/etcetera.rs diff --git a/src/assets.rs b/src/assets.rs index b01a2ac..bb0ae43 100644 --- a/src/assets.rs +++ b/src/assets.rs @@ -1,5 +1,4 @@ -use crate::error::Result; -use crate::etcetera; +use crate::error::{Error, Result}; use std::env; use std::path::PathBuf; use std::str; @@ -21,6 +20,107 @@ pub fn cache_dir() -> Result { return Ok(PathBuf::from(cache_dir)); } - let cache_dir = etcetera::cache_dir()?; + let home_dir = home::home_dir().ok_or(Error::HomeDir)?; + + let cache_dir = if cfg!(windows) { + windows::cache_dir(&home_dir) + } else { + xdg::cache_dir(&home_dir) + }; + Ok(cache_dir.join("bat")) } + +mod windows { + use std::path::{Path, PathBuf}; + + fn dir_inner(env: &'static str) -> Option { + std::env::var_os(env) + .filter(|s| !s.is_empty()) + .map(PathBuf::from) + .or_else(|| dir_crt(env)) + } + + // Ref: https://github.com/rust-lang/cargo/blob/home-0.5.11/crates/home/src/windows.rs + // We should keep this code in sync with the above. + #[cfg(all(windows, not(target_vendor = "uwp")))] + fn dir_crt(env: &'static str) -> Option { + use std::ffi::OsString; + use std::os::windows::ffi::OsStringExt; + use std::ptr; + use std::slice; + + use windows_sys::Win32::Foundation::S_OK; + use windows_sys::Win32::System::Com::CoTaskMemFree; + use windows_sys::Win32::UI::Shell::{ + FOLDERID_LocalAppData, FOLDERID_RoamingAppData, SHGetKnownFolderPath, + KF_FLAG_DONT_VERIFY, + }; + + extern "C" { + fn wcslen(buf: *const u16) -> usize; + } + + let folder_id = match env { + "APPDATA" => FOLDERID_RoamingAppData, + "LOCALAPPDATA" => FOLDERID_LocalAppData, + _ => return None, + }; + + unsafe { + let mut path = ptr::null_mut(); + match SHGetKnownFolderPath( + &folder_id, + KF_FLAG_DONT_VERIFY as u32, + std::ptr::null_mut(), + &mut path, + ) { + S_OK => { + let path_slice = slice::from_raw_parts(path, wcslen(path)); + let s = OsString::from_wide(path_slice); + CoTaskMemFree(path.cast()); + Some(PathBuf::from(s)) + } + _ => { + // Free any allocated memory even on failure. A null ptr is a no-op for `CoTaskMemFree`. + CoTaskMemFree(path.cast()); + None + } + } + } + } + + #[cfg(not(all(windows, not(target_vendor = "uwp"))))] + fn dir_crt(_env: &'static str) -> Option { + None + } + + pub fn cache_dir(home_dir: &Path) -> PathBuf { + dir_inner("LOCALAPPDATA").unwrap_or_else(|| home_dir.join("AppData").join("Local")) + } +} + +mod xdg { + use std::path::{Path, PathBuf}; + + fn env_var_or_none(env_var: &str) -> Option { + std::env::var(env_var).ok().and_then(|path| { + let path = PathBuf::from(path); + + // Return None if the path obtained from the environment variable isn’t absolute. + if path.is_absolute() { + Some(path) + } else { + None + } + }) + } + + fn env_var_or_default(home_dir: &Path, env_var: &str, default: impl AsRef) -> PathBuf { + env_var_or_none(env_var).unwrap_or_else(|| home_dir.join(default)) + } + + pub fn cache_dir(home_dir: &Path) -> PathBuf { + env_var_or_default(home_dir, "XDG_CACHE_HOME", ".cache/") + } +} diff --git a/src/etcetera.rs b/src/etcetera.rs deleted file mode 100644 index a8af857..0000000 --- a/src/etcetera.rs +++ /dev/null @@ -1,105 +0,0 @@ -use crate::error::{Error, Result}; -use std::path::PathBuf; - -pub fn cache_dir() -> Result { - let home_dir = home::home_dir().ok_or(Error::HomeDir)?; - if cfg!(windows) { - Ok(windows::cache_dir(&home_dir)) - } else { - Ok(xdg::cache_dir(&home_dir)) - } -} - -mod windows { - use std::path::{Path, PathBuf}; - - fn dir_inner(env: &'static str) -> Option { - std::env::var_os(env) - .filter(|s| !s.is_empty()) - .map(PathBuf::from) - .or_else(|| dir_crt(env)) - } - - // Ref: https://github.com/rust-lang/cargo/blob/home-0.5.11/crates/home/src/windows.rs - // We should keep this code in sync with the above. - #[cfg(all(windows, not(target_vendor = "uwp")))] - fn dir_crt(env: &'static str) -> Option { - use std::ffi::OsString; - use std::os::windows::ffi::OsStringExt; - use std::ptr; - use std::slice; - - use windows_sys::Win32::Foundation::S_OK; - use windows_sys::Win32::System::Com::CoTaskMemFree; - use windows_sys::Win32::UI::Shell::{ - FOLDERID_LocalAppData, FOLDERID_RoamingAppData, SHGetKnownFolderPath, - KF_FLAG_DONT_VERIFY, - }; - - extern "C" { - fn wcslen(buf: *const u16) -> usize; - } - - let folder_id = match env { - "APPDATA" => FOLDERID_RoamingAppData, - "LOCALAPPDATA" => FOLDERID_LocalAppData, - _ => return None, - }; - - unsafe { - let mut path = ptr::null_mut(); - match SHGetKnownFolderPath( - &folder_id, - KF_FLAG_DONT_VERIFY as u32, - std::ptr::null_mut(), - &mut path, - ) { - S_OK => { - let path_slice = slice::from_raw_parts(path, wcslen(path)); - let s = OsString::from_wide(path_slice); - CoTaskMemFree(path.cast()); - Some(PathBuf::from(s)) - } - _ => { - // Free any allocated memory even on failure. A null ptr is a no-op for `CoTaskMemFree`. - CoTaskMemFree(path.cast()); - None - } - } - } - } - - #[cfg(not(all(windows, not(target_vendor = "uwp"))))] - fn dir_crt(_env: &'static str) -> Option { - None - } - - pub fn cache_dir(home_dir: &Path) -> PathBuf { - dir_inner("LOCALAPPDATA").unwrap_or_else(|| home_dir.join("AppData").join("Local")) - } -} - -mod xdg { - use std::path::{Path, PathBuf}; - - fn env_var_or_none(env_var: &str) -> Option { - std::env::var(env_var).ok().and_then(|path| { - let path = PathBuf::from(path); - - // Return None if the path obtained from the environment variable isn’t absolute. - if path.is_absolute() { - Some(path) - } else { - None - } - }) - } - - fn env_var_or_default(home_dir: &Path, env_var: &str, default: impl AsRef) -> PathBuf { - env_var_or_none(env_var).unwrap_or_else(|| home_dir.join(default)) - } - - pub fn cache_dir(home_dir: &Path) -> PathBuf { - env_var_or_default(home_dir, "XDG_CACHE_HOME", ".cache/") - } -} diff --git a/src/main.rs b/src/main.rs index d067422..cee76f4 100644 --- a/src/main.rs +++ b/src/main.rs @@ -21,7 +21,6 @@ mod cmd; mod config; mod edit; mod error; -mod etcetera; mod fmt; mod manifest; mod opts; From 36dbffb78c5e0469f35d1b8776f60d0ee39ae81c Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sun, 2 Mar 2025 22:39:59 -0800 Subject: [PATCH 08/10] Conditionally compile OS-specific cache dir logic --- src/assets.rs | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/src/assets.rs b/src/assets.rs index bb0ae43..5f41db2 100644 --- a/src/assets.rs +++ b/src/assets.rs @@ -22,15 +22,15 @@ pub fn cache_dir() -> Result { let home_dir = home::home_dir().ok_or(Error::HomeDir)?; - let cache_dir = if cfg!(windows) { - windows::cache_dir(&home_dir) - } else { - xdg::cache_dir(&home_dir) - }; + #[cfg(windows)] + let cache_dir = windows::cache_dir(&home_dir); + #[cfg(not(windows))] + let cache_dir = xdg::cache_dir(&home_dir); Ok(cache_dir.join("bat")) } +#[cfg(windows)] mod windows { use std::path::{Path, PathBuf}; @@ -43,7 +43,7 @@ mod windows { // Ref: https://github.com/rust-lang/cargo/blob/home-0.5.11/crates/home/src/windows.rs // We should keep this code in sync with the above. - #[cfg(all(windows, not(target_vendor = "uwp")))] + #[cfg(not(target_vendor = "uwp"))] fn dir_crt(env: &'static str) -> Option { use std::ffi::OsString; use std::os::windows::ffi::OsStringExt; @@ -90,7 +90,7 @@ mod windows { } } - #[cfg(not(all(windows, not(target_vendor = "uwp"))))] + #[cfg(target_vendor = "uwp")] fn dir_crt(_env: &'static str) -> Option { None } @@ -100,6 +100,7 @@ mod windows { } } +#[cfg(not(windows))] mod xdg { use std::path::{Path, PathBuf}; From 4317adcaf1a73a8e0c2d3a0c628a420e0b956145 Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sun, 2 Mar 2025 22:43:27 -0800 Subject: [PATCH 09/10] Touch up etcetera cache dir code --- Cargo.toml | 2 +- src/assets.rs | 84 ++++++++++++++++++--------------------------------- 2 files changed, 30 insertions(+), 56 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index a02bffe..ef155f0 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -37,7 +37,7 @@ termcolor = "1.0" toml = "0.8" toolchain_find = "0.4" -[target.'cfg(windows)'.dependencies] +[target.'cfg(all(windows, not(target_vendor = "uwp")))'.dependencies] windows-sys = { version = "0.59", features = ["Win32_Foundation", "Win32_System_Com", "Win32_UI_Shell"] } [package.metadata.docs.rs] diff --git a/src/assets.rs b/src/assets.rs index 5f41db2..aaa44cd 100644 --- a/src/assets.rs +++ b/src/assets.rs @@ -32,96 +32,70 @@ pub fn cache_dir() -> Result { #[cfg(windows)] mod windows { + use std::env; use std::path::{Path, PathBuf}; - fn dir_inner(env: &'static str) -> Option { - std::env::var_os(env) + pub fn cache_dir(home_dir: &Path) -> PathBuf { + env::var_os("LOCALAPPDATA") .filter(|s| !s.is_empty()) .map(PathBuf::from) - .or_else(|| dir_crt(env)) + .or_else(dir_crt) + .unwrap_or_else(|| home_dir.join("AppData").join("Local")) } // Ref: https://github.com/rust-lang/cargo/blob/home-0.5.11/crates/home/src/windows.rs // We should keep this code in sync with the above. #[cfg(not(target_vendor = "uwp"))] - fn dir_crt(env: &'static str) -> Option { + fn dir_crt() -> Option { use std::ffi::OsString; use std::os::windows::ffi::OsStringExt; use std::ptr; use std::slice; - use windows_sys::Win32::Foundation::S_OK; use windows_sys::Win32::System::Com::CoTaskMemFree; use windows_sys::Win32::UI::Shell::{ - FOLDERID_LocalAppData, FOLDERID_RoamingAppData, SHGetKnownFolderPath, - KF_FLAG_DONT_VERIFY, + FOLDERID_LocalAppData, SHGetKnownFolderPath, KF_FLAG_DONT_VERIFY, }; extern "C" { fn wcslen(buf: *const u16) -> usize; } - let folder_id = match env { - "APPDATA" => FOLDERID_RoamingAppData, - "LOCALAPPDATA" => FOLDERID_LocalAppData, - _ => return None, + let mut path = ptr::null_mut(); + let S_OK = (unsafe { + SHGetKnownFolderPath( + &FOLDERID_LocalAppData, + KF_FLAG_DONT_VERIFY as u32, + ptr::null_mut(), + &mut path, + ) + }) else { + // Free any allocated memory even on failure. A null ptr is a no-op for `CoTaskMemFree`. + unsafe { CoTaskMemFree(path.cast()) }; + return None; }; - unsafe { - let mut path = ptr::null_mut(); - match SHGetKnownFolderPath( - &folder_id, - KF_FLAG_DONT_VERIFY as u32, - std::ptr::null_mut(), - &mut path, - ) { - S_OK => { - let path_slice = slice::from_raw_parts(path, wcslen(path)); - let s = OsString::from_wide(path_slice); - CoTaskMemFree(path.cast()); - Some(PathBuf::from(s)) - } - _ => { - // Free any allocated memory even on failure. A null ptr is a no-op for `CoTaskMemFree`. - CoTaskMemFree(path.cast()); - None - } - } - } + let path_slice = unsafe { slice::from_raw_parts(path, wcslen(path)) }; + let s = OsString::from_wide(path_slice); + unsafe { CoTaskMemFree(path.cast()) }; + Some(PathBuf::from(s)) } #[cfg(target_vendor = "uwp")] - fn dir_crt(_env: &'static str) -> Option { + fn dir_crt() -> Option { None } - - pub fn cache_dir(home_dir: &Path) -> PathBuf { - dir_inner("LOCALAPPDATA").unwrap_or_else(|| home_dir.join("AppData").join("Local")) - } } #[cfg(not(windows))] mod xdg { + use std::env; use std::path::{Path, PathBuf}; - fn env_var_or_none(env_var: &str) -> Option { - std::env::var(env_var).ok().and_then(|path| { - let path = PathBuf::from(path); - - // Return None if the path obtained from the environment variable isn’t absolute. - if path.is_absolute() { - Some(path) - } else { - None - } - }) - } - - fn env_var_or_default(home_dir: &Path, env_var: &str, default: impl AsRef) -> PathBuf { - env_var_or_none(env_var).unwrap_or_else(|| home_dir.join(default)) - } - pub fn cache_dir(home_dir: &Path) -> PathBuf { - env_var_or_default(home_dir, "XDG_CACHE_HOME", ".cache/") + env::var_os("XDG_CACHE_HOME") + .map(PathBuf::from) + .filter(|path| path.is_absolute()) + .unwrap_or_else(|| home_dir.join(".cache/")) } } From 5f32c30ad138ae0a2c2b3986b4e113ada8e524be Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Sun, 2 Mar 2025 23:11:56 -0800 Subject: [PATCH 10/10] Acknowledge provenance of cache_dir code --- src/assets.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/assets.rs b/src/assets.rs index aaa44cd..7319e75 100644 --- a/src/assets.rs +++ b/src/assets.rs @@ -30,6 +30,7 @@ pub fn cache_dir() -> Result { Ok(cache_dir.join("bat")) } +// Based on etcetera v0.9.0 #[cfg(windows)] mod windows { use std::env; @@ -87,6 +88,7 @@ mod windows { } } +// Based on etcetera v0.9.0 #[cfg(not(windows))] mod xdg { use std::env;