From 7101b3666de817653efeca4243abb193beafcb91 Mon Sep 17 00:00:00 2001 From: Utkarsh Gupta Date: Fri, 21 Apr 2023 20:35:36 +0530 Subject: [PATCH 1/3] Docs/readme: minor changes --- README.md | 18 ++++++++++++------ src/app_strategy.rs | 6 +++--- src/app_strategy/windows.rs | 2 +- src/base_strategy.rs | 8 ++++---- src/base_strategy/windows.rs | 2 +- src/base_strategy/xdg.rs | 13 ++++++------- src/lib.rs | 27 +++++++++++++++++---------- 7 files changed, 44 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 94baccc..653ed2c 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,18 @@ # Etcetera -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 (Etcetera calls these ‘strategies’) they follow. Etcetera, on the other hand, gives you the choice. +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. -Etcetera supports the following strategies: +## Conventions +Etcetera supports the following conventions: - the [XDG base directory](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) -- the [Known Folder Locations](https://msdn.microsoft.com/en-us/library/windows/desktop/dd378457.aspx) -- the [Standard Directories](https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html) -- the "Unix Single-folder Strategy" i.e. everything in `~/.myapp` +- 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 Etcetera has 2 modes of operation: `BaseStrategy` & `AppStrategy`: - With `BaseStrategy`, you just get the location of the respective directory. For eg. for `config_dir()`: - XDG: `~/.config` @@ -27,10 +31,12 @@ Etcetera has 2 modes of operation: `BaseStrategy` & `AppStrategy`: Note: the location of the home (~) is determined by the [`home`](https://docs.rs/home/0.5.4/home/fn.home_dir.html) crate. +### Convenience functions Etcetera also provides convenience functions for selecting the appropriate strategy on each platform: - `base_strategy::choose_base_strategy` & `app_strategy::choose_app_strategy`: Uses `Windows` on Windows & `XDG` everywhere else. This is used by most CLI tools & some GUI tools on each platform. - `base_strategy::choose_native_strategy` & `app_strategy::choose_native_strategy`: Uses `Windows` on Windows, `Apple` on macOS/iOS, & `XDG` everywhere else. This is used by most GUI applications on each platform. -See the documentation for examples. +## +See the ![documentation](https://docs.rs/etcetera) for examples. diff --git a/src/app_strategy.rs b/src/app_strategy.rs index 272c6bd..3208dd4 100644 --- a/src/app_strategy.rs +++ b/src/app_strategy.rs @@ -69,7 +69,7 @@ macro_rules! in_dir_method { }}; } -/// Allows applications to retrieve the paths of configuration, data and cache directories specifically for them. +/// Allows applications to retrieve the paths of configuration, data, and cache directories specifically for them. pub trait AppStrategy: Sized { /// The error type returned by `new`. type CreationError: std::error::Error; @@ -87,11 +87,11 @@ pub trait AppStrategy: Sized { fn cache_dir(&self) -> PathBuf; /// Gets the state directory for your application. - /// State directory may not to exist for all platforms. + /// State directory may not to exist for all conventions. fn state_dir(&self) -> Option; /// Gets the runtime directory for your application. - /// Runtime directory may not to exist for all platforms. + /// Runtime directory may not to exist for all conventions. fn runtime_dir(&self) -> Option; /// Constructs a path inside your application’s configuration directory to which a path of your choice has been appended. diff --git a/src/app_strategy/windows.rs b/src/app_strategy/windows.rs index 0cec286..49e007e 100644 --- a/src/app_strategy/windows.rs +++ b/src/app_strategy/windows.rs @@ -2,7 +2,7 @@ use crate::base_strategy; use crate::base_strategy::BaseStrategy; use std::path::PathBuf; -/// This strategy follows Windows’ conventions. It seems that all Windows GUI apps, and some command-line ones follow this pattern. +/// 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). /// /// ``` /// use etcetera::app_strategy::AppStrategy; diff --git a/src/base_strategy.rs b/src/base_strategy.rs index b6ccd9e..6dcb6c1 100644 --- a/src/base_strategy.rs +++ b/src/base_strategy.rs @@ -1,8 +1,8 @@ -//! These strategies simply provide the user’s configuration, data and cache directories, without knowing about the application specifically. +//! These strategies simply provide the user’s configuration, data, and cache directories, without knowing about the application specifically. use std::path::PathBuf; -/// Provides configuration, data and cache directories of the current user. +/// Provides configuration, data, and cache directories of the current user. pub trait BaseStrategy: Sized { /// The error type returned by `new`. type CreationError: std::error::Error; @@ -20,11 +20,11 @@ pub trait BaseStrategy: Sized { fn cache_dir(&self) -> PathBuf; /// Gets the user’s state directory. - /// State directory may not exist for all platforms. + /// State directory may not exist for all conventions. fn state_dir(&self) -> Option; /// Gets the user’s runtime directory. - /// Runtime directory may not exist for all platforms. + /// Runtime directory may not exist for all conventions. fn runtime_dir(&self) -> Option; } diff --git a/src/base_strategy/windows.rs b/src/base_strategy/windows.rs index ccc49af..55c6f13 100644 --- a/src/base_strategy/windows.rs +++ b/src/base_strategy/windows.rs @@ -1,6 +1,6 @@ use std::path::PathBuf; -/// This strategy follows Windows’ conventions. It seems that all Windows GUI apps, and some command-line ones follow this pattern. +/// 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). /// /// ``` /// use etcetera::base_strategy::BaseStrategy; diff --git a/src/base_strategy/xdg.rs b/src/base_strategy/xdg.rs index 8900d44..ccbd3d0 100644 --- a/src/base_strategy/xdg.rs +++ b/src/base_strategy/xdg.rs @@ -3,13 +3,14 @@ use std::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. /// -/// In this first example the relevant XDG environment variables have been unset so as to demonstrate the strategy’s behaviour when it has to fall back to the defaults. +/// 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"); @@ -42,7 +43,7 @@ use std::path::PathBuf; /// ); /// ``` /// -/// And here is another example with the environment variables set to demonstrate that the strategy really does read them: +/// This next example gives the environment variables values: /// /// ``` /// use etcetera::base_strategy::BaseStrategy; @@ -106,17 +107,14 @@ use std::path::PathBuf; /// ); /// ``` /// -/// The specification states that: -/// -/// > All paths set in these environment variables must be absolute. If an implementation encounters a relative path in any of these variables it should consider the path invalid and ignore it. -/// -/// In this example the environment variables have been given relative values. The strategy behaves correctly and uses the defaults: +/// 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/"); @@ -127,6 +125,7 @@ use std::path::PathBuf; /// /// 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/")) diff --git a/src/lib.rs b/src/lib.rs index 36edc08..36ff145 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,10 +1,19 @@ -//! 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 (Etcetera calls these ‘strategies’) they follow. Etcetera, on the other hand, gives you the choice. +//! 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 provided convenience functions that use the default strategies (as determined arbitrarily by yours truly) or the native strategies for each OS. +//! 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 -//! This first example is for when you just want the path to a configuration, data or cache directory (this is called a ‘base strategy’): +//! 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::base_strategy; @@ -20,16 +29,14 @@ //! ``` //! //! ## AppStrategy -//! Here is an example where you provide Etcetera with some basic information about your application, and Etcetera will in turn give you a path that includes this information (this is called an ‘app strategy’). +//! 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 `.org` as an example. +//! 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.acmecorp.FrobnicatorPlus`. //! - Windows strategy would place these in `~\AppData\Roaming\Acme Corp\Frobnicator Plus`. //! -//! Etcetera takes care of the distinctions. -//! //! ``` //! use etcetera::app_strategy; //! use etcetera::app_strategy::AppStrategy; @@ -54,11 +61,11 @@ //! 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 still should prefer the `XDG` strategy on macOS. +//! Note that if your application expects the user to modify the configuration files, you should still prefer the `XDG` strategy on macOS. //! -//! ## Custom Strategies +//! ## Custom Conventions //! -//! You aren’t limited to the built-in strategies, however – you can implement the relevant traits yourself. Please consider contributing these back, as the more preset strategies there are, the better. +//! 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: From 15cce5c4a493416ca8104bed9b6ec31312778b9d Mon Sep 17 00:00:00 2001 From: Utkarsh Gupta Date: Fri, 21 Apr 2023 20:30:55 +0530 Subject: [PATCH 2/3] Cargo.toml: rearrange keywords --- Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Cargo.toml b/Cargo.toml index 630ce18..b00daa1 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ description = "An unopinionated library for obtaining configuration, data, cache documentation = "https://docs.rs/etcetera" edition = "2018" homepage = "https://github.com/lunacookies/etcetera" -keywords = ["xdg", "dirs", "directories", "directory", "basedir", "app_dirs", "cli_dirs", "config", "path", "folder"] +keywords = ["xdg", "dirs", "directories", "basedir", "path", "folder", "directory", "app_dirs", "cli_dirs", "config"] license = "MIT OR Apache-2.0" name = "etcetera" readme = "README.md" From fd3faad543855ce9c74e62adf1af8533c4807f72 Mon Sep 17 00:00:00 2001 From: Utkarsh Gupta Date: Fri, 21 Apr 2023 20:31:08 +0530 Subject: [PATCH 3/3] Cargo.toml: bump version --- Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Cargo.toml b/Cargo.toml index b00daa1..37ddc35 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -9,7 +9,7 @@ license = "MIT OR Apache-2.0" name = "etcetera" readme = "README.md" repository = "https://github.com/lunacookies/etcetera" -version = "0.5.0" +version = "0.6.0" [dependencies] cfg-if = "1.0.0"