devela/sys/env/
app.rs

Help
1//
2//! Defines [`AppConfig`], [`AppEnv`], [`AppApple`], [`AppUnix`], [`AppWindows`] and [`AppXdg`].
3//
4// TODO:
5// - add more docs and examples.
6//   - https://github.com/lunacookies/etcetera/pull/22/files
7// - add more Xdg directories.
8//   - https://github.com/lunacookies/etcetera/pull/16/files
9//   - WAIT: [XDG_BIN_HOME](https://gitlab.freedesktop.org/xdg/xdg-specs/-/issues/14)
10// - add environment specific validations.
11//   - android app name 30 char max.
12//   - apple bundle_id 155 char max, app_name 50 char max.
13//   - windows server 36 char max.
14
15use crate::{iif, Env, Path, PathBuf};
16
17/// Application specific metadata.
18///
19/// It is used together with [`AppEnv`].
20#[derive(Clone, Debug, PartialEq)]
21pub struct AppConfig {
22    tld: String,
23    author: String,
24    app_name: String,
25}
26impl AppConfig {
27    /// Creates a new `AppConfig` if all fields are valid.
28    ///
29    /// In order to be valid, they can't be empty, and:
30    /// - <abbr title = "Top Level Domain">`tld`</abbr>:
31    ///   up to 127 lowercase alphanumeric characters and dots (`^[a-z0-9\.]+$`).
32    /// - `author`:
33    ///   up to 50 alphanumeric characters, dashes, and spaces (`^[0-9A-Za-z\s\-]+$`).
34    /// - `app_name`:
35    ///   up to 50 alphanumeric characters and spaces (`^[0-9A-Za-z\s]+$`).
36    pub fn new(tld: &str, author: &str, app_name: &str) -> Option<Self> {
37        if Self::validate_tld(tld)
38            && Self::validate_author(author)
39            && Self::validate_app_name(app_name)
40        {
41            None
42        } else {
43            Some(Self {
44                tld: tld.into(),
45                author: author.into(),
46                app_name: app_name.into(),
47            })
48        }
49    }
50    /// Gets the *Top Level Domain* of the application (e.g. `com` or `io.github`).
51    #[must_use]
52    pub fn tld(&self) -> &str {
53        &self.tld
54    }
55    /// Gets the name of the author of the application.
56    #[must_use]
57    pub fn author(&self) -> &str {
58        &self.author
59    }
60    /// Gets the name of the application.
61    #[must_use]
62    pub fn app_name(&self) -> &str {
63        &self.app_name
64    }
65
66    fn validate_tld(tld: &str) -> bool {
67        !tld.is_empty()
68            && tld.len() <= 127
69            && tld.split('.').all(|label| {
70                !label.is_empty()
71                    && label.len() <= 63
72                    && label.chars().all(|c| c.is_ascii_lowercase() || c.is_ascii_digit())
73            })
74    }
75    fn validate_author(author: &str) -> bool {
76        !author.is_empty()
77            && author.len() <= 50
78            && author.chars().all(|c| c.is_ascii_alphanumeric() || c.is_whitespace() || c == '-')
79    }
80    fn validate_app_name(app_name: &str) -> bool {
81        !app_name.is_empty()
82            && app_name.len() <= 50
83            && app_name.chars().all(|c| c.is_ascii_alphanumeric() || c.is_whitespace())
84    }
85
86    /// Returns an Apple bundle identifier.
87    ///
88    /// This is used in [`AppApple`].
89    #[must_use]
90    pub fn bundle_id(&self) -> String {
91        let author = self.author.to_lowercase().replace(' ', "-");
92        let app_name = self.app_name.replace(' ', "-");
93        let mut parts = vec![self.tld.as_str(), author.as_str(), app_name.as_str()];
94        parts.retain(|part| !part.is_empty());
95        parts.join(".")
96    }
97
98    /// Returns a ‘unixy’ version of the application’s name, akin to what would
99    /// usually be used as a binary name.
100    ///
101    /// Replaces whitespaces with underscores.
102    ///
103    /// This is used in [`AppUnix`] and [`AppXdg`].
104    #[must_use]
105    pub fn unixy_name(&self) -> String {
106        self.app_name.to_lowercase().replace(' ', "_")
107    }
108}
109
110/// Manages directory paths in an environment-aware manner.
111///
112#[doc = crate::doc_!(vendor: "etcetera")]
113#[rustfmt::skip]
114pub trait AppEnv {
115    /// Gets the home directory.
116    #[must_use]
117    fn app_home(&self) -> &Path;
118
119    /// Gets the configuration directory.
120    #[must_use]
121    fn app_config(&self) -> PathBuf;
122
123    /// Gets the data directory.
124    #[must_use]
125    fn app_data(&self) -> PathBuf;
126
127    /// Gets the cache directory.
128    #[must_use]
129    fn app_cache(&self) -> PathBuf;
130
131    /// Gets the state directory.
132    ///
133    /// Currently, only the [`Xdg`](struct.Xdg.html) & [`AppUnix`] environments support this.
134    ///
135    #[must_use]
136    fn app_state(&self) -> Option<PathBuf>;
137
138    /// Gets the runtime directory.
139    ///
140    /// Currently, only the [`Xdg`](struct.Xdg.html) & [`AppUnix`] environments support this.
141    ///
142    /// Note: The [XDG Base Directory Specification][spec] places additional
143    /// requirements on this directory related to ownership, permissions, and
144    /// persistence. This implementation does not check those requirements.
145    ///
146    /// [spec]: https://specifications.freedesktop.org/basedir-spec/latest/
147    #[must_use]
148    fn app_runtime(&self) -> Option<PathBuf>;
149
150    /* provided methods */
151
152    // NOTE: they accept &Path instead of AsRef<OsStr> to be dyn-compatible.
153    // Can be called using .as_ref(), from &str, String, OsStr and OsString.
154
155    /// Constructs a path inside your application’s configuration directory.
156    #[must_use]
157    fn app_in_config(&self, append: &Path) -> PathBuf {
158        app_in(self.app_config(), append)
159    }
160
161    /// Constructs a path inside your application’s data directory.
162    #[must_use]
163    fn app_in_data(&self, append: &Path) -> PathBuf {
164        app_in(self.app_data(), append)
165    }
166
167    /// Constructs a path inside your application’s cache directory.
168    #[must_use]
169    fn app_in_cache(&self, append: &Path) -> PathBuf {
170        app_in(self.app_cache(), append)
171    }
172
173    /// Constructs a path inside your application’s state directory.
174    ///
175    /// Currently, only the [`Xdg`](struct.Xdg.html) & [`AppUnix`] environments support this.
176    #[must_use]
177    fn app_in_state(&self, append: &Path) -> Option<PathBuf> {
178        self.app_state().map(|base| app_in(base, append))
179    }
180
181    /// Constructs a path inside your application’s runtime directory.
182    ///
183    /// Currently, only the [`Xdg`](struct.Xdg.html) & [`AppUnix`] environments support this.
184    #[must_use]
185    fn app_in_runtime(&self, append: &Path) -> Option<PathBuf> {
186        self.app_runtime().map(|base| app_in(base, append))
187    }
188
189    /// Gets the temporary directory.
190    ///
191    /// Uses the system's temporary directory if available. Falls back to
192    /// the application cache directory if the temporary directory is unsuitable.
193    #[must_use]
194    fn app_temp(&self) -> PathBuf {
195        let temp_dir = Env::temp_dir();
196        if temp_dir.is_absolute() {
197            temp_dir
198        } else {
199            self.app_cache()
200        }
201    }
202
203    /// Constructs a path inside the temporary directory.
204    #[must_use]
205    fn app_in_temp(&self, append: &Path) -> PathBuf {
206        app_in(self.app_temp(), append)
207    }
208}
209
210/// Helps construct a path by appending the given `path` to the provided `base` path.
211#[must_use] #[rustfmt::skip]
212fn app_in(mut base: PathBuf, path: &Path) -> PathBuf { base.push(path); base }
213
214/// Xdg enviroment for directories.
215#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
216pub struct AppXdg {
217    home: PathBuf,
218    unixy_name: String,
219}
220impl AppXdg {
221    /// Creates a new Xdg directory environment.
222    ///
223    /// Returns `None` if the home directory cannot be determined (see [`Env::home_dir`]),
224    #[must_use]
225    pub fn new(app_data: Option<AppConfig>) -> Option<Self> {
226        let home = Env::home_dir()?;
227        if let Some(app) = app_data {
228            Some(Self { home, unixy_name: app.unixy_name() })
229        } else {
230            Some(Self { home, unixy_name: String::new() })
231        }
232    }
233    // Returns `None` if the path obtained from the env var isn’t absolute.
234    fn env_var_or_none(env_var: &str) -> Option<PathBuf> {
235        Env::var(env_var).ok().and_then(|path| {
236            let path = PathBuf::from(path);
237            path.is_absolute().then_some(path)
238        })
239    }
240    fn env_var_or_default(&self, env_var: &str, default: impl AsRef<Path>) -> PathBuf {
241        Self::env_var_or_none(env_var).unwrap_or_else(|| self.home.join(default))
242    }
243}
244impl AppEnv for AppXdg {
245    fn app_home(&self) -> &Path {
246        &self.home
247    }
248    fn app_config(&self) -> PathBuf {
249        let dir = self.env_var_or_default("XDG_CONFIG_HOME", ".config/");
250        iif![self.unixy_name.is_empty(); dir; dir.join(&self.unixy_name)]
251    }
252    fn app_data(&self) -> PathBuf {
253        let dir = self.env_var_or_default("XDG_DATA_HOME", ".local/share/");
254        iif![self.unixy_name.is_empty(); dir; dir.join(&self.unixy_name)]
255    }
256    fn app_cache(&self) -> PathBuf {
257        let dir = self.env_var_or_default("XDG_CACHE_HOME", ".cache/");
258        iif![self.unixy_name.is_empty(); dir; dir.join(&self.unixy_name)]
259    }
260    fn app_state(&self) -> Option<PathBuf> {
261        let dir = self.env_var_or_default("XDG_STATE_HOME", ".local/state/");
262        Some(iif![self.unixy_name.is_empty(); dir; dir.join(&self.unixy_name)])
263    }
264    fn app_runtime(&self) -> Option<PathBuf> {
265        let dir = Self::env_var_or_none("XDG_RUNTIME_DIR");
266        iif![self.unixy_name.is_empty(); dir; dir.map(|d| d.join(&self.unixy_name))]
267    }
268}
269
270/// Unix enviroment for directories.
271///
272/// This constructs directories specific to an application using
273/// its `unixy_name`, which is derived from the application's name.
274///
275/// This is no standard or official specification, but an old convention of
276/// placing the configuration directory under the user's home directory.
277///
278/// Vim and Cargo are notable examples whose configuration/data/cache directory
279/// layouts are similar to these.
280#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
281pub struct AppUnix {
282    home: PathBuf,
283    unixy_name: String,
284}
285impl AppUnix {
286    /// Creates a new Unix directory environment.
287    ///
288    /// Returns `None` if the home directory cannot be determined (see [`Env::home_dir`]),
289    #[must_use]
290    pub fn new(app_data: AppConfig) -> Option<Self> {
291        let home = Env::home_dir()?;
292        Some(Self { home, unixy_name: app_data.unixy_name() })
293    }
294}
295#[rustfmt::skip]
296impl AppEnv for AppUnix {
297    fn app_home(&self) -> &Path { &self.home }
298    fn app_config(&self) -> PathBuf { self.home.join(&self.unixy_name) }
299    fn app_data(&self) -> PathBuf { self.app_config().join("data") }
300    fn app_cache(&self) -> PathBuf { self.app_config().join("cache") }
301    fn app_state(&self) -> Option<PathBuf> { Some(self.app_config().join("state")) }
302    fn app_runtime(&self) -> Option<PathBuf> { Some(self.app_config().join("runtime")) }
303}
304
305/// Apple enviroment for directories.
306#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
307pub struct AppApple {
308    home: PathBuf,
309    bundle_id: String,
310}
311impl AppApple {
312    /// Creates a new Apple directory environment.
313    ///
314    /// Returns `None` if the home directory cannot be determined (see [`Env::home_dir`]),
315    #[must_use]
316    pub fn new(app_data: Option<AppConfig>) -> Option<Self> {
317        let home = Env::home_dir()?;
318        if let Some(app) = app_data {
319            Some(Self { home, bundle_id: app.bundle_id() })
320        } else {
321            Some(Self { home, bundle_id: String::new() })
322        }
323    }
324}
325#[rustfmt::skip]
326impl AppEnv for AppApple {
327    fn app_home(&self) -> &Path { &self.home }
328    fn app_config(&self) -> PathBuf {
329        let dir = self.home.join("Library/Preferences/");
330        iif![self.bundle_id.is_empty(); dir; dir.join(&self.bundle_id)]
331    }
332    fn app_data(&self) -> PathBuf {
333        let dir = self.home.join("Library/Application Support/");
334        iif![self.bundle_id.is_empty(); dir; dir.join(&self.bundle_id)]
335    }
336    fn app_cache(&self) -> PathBuf {
337        let dir = self.home.join("Library/Caches/");
338        iif![self.bundle_id.is_empty(); dir; dir.join(&self.bundle_id)]
339    }
340    fn app_state(&self) -> Option<PathBuf> { None }
341    fn app_runtime(&self) -> Option<PathBuf> { None }
342}
343
344/// Windows enviroment for directories.
345#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
346pub struct AppWindows {
347    home: PathBuf,
348    app_path: Option<PathBuf>,
349}
350impl AppWindows {
351    /// Creates a new Windows directory environment.
352    ///
353    /// Returns `None` if the home directory cannot be determined (see [`Env::home_dir`]),
354    #[must_use] #[rustfmt::skip]
355    pub fn new(app_data: Option<AppConfig>) -> Option<Self> {
356        let home = Env::home_dir()?;
357        if let Some(app) = app_data {
358            Some(Self { home, app_path: Some(PathBuf::from(app.author).join(app.app_name)) })
359        } else {
360            Some(Self { home, app_path: None })
361        }
362    }
363}
364#[rustfmt::skip]
365impl AppEnv for AppWindows {
366    fn app_home(&self) -> &Path { &self.home }
367    fn app_config(&self) -> PathBuf {
368        let mut dir = self.home.join("AppData").join("Roaming");
369        iif![let Some(app) = &self.app_path; {dir.push(app); dir.push("config"); dir }; dir]
370    }
371    fn app_data(&self) -> PathBuf {
372        let mut dir = self.home.join("AppData").join("Roaming");
373        iif![let Some(app) = &self.app_path; {dir.push(app); dir.push("data"); dir }; dir]
374    }
375    fn app_cache(&self) -> PathBuf {
376        let mut dir = self.home.join("AppData").join("Local");
377        iif![let Some(app) = &self.app_path; {dir.push(app); dir.push("cache"); dir }; dir]
378    }
379    fn app_state(&self) -> Option<PathBuf> { None }
380    fn app_runtime(&self) -> Option<PathBuf> { None }
381}
devela/sys/env/app.rs

devela/sys/env/
app.rs
