komichi 2.2.0

Application tools for working with file-system paths
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

use camino::{Utf8Path, Utf8PathBuf};

#[cfg(target_os = "macos")]
mod mac;
#[cfg(target_os = "macos")]
use mac::Info;

#[cfg(all(unix, not(any(target_os = "macos", target_os = "ios"))))]
mod unix;
#[cfg(all(
    unix,
    not(any(target_os = "macos", target_os = "ios"))
))]
use unix::Info;

trait LocalInfo {
    fn get_cache_home(&self) -> Utf8PathBuf;
    fn get_config_home(&self) -> Utf8PathBuf;
    fn get_data_home(&self) -> Utf8PathBuf;
    fn get_log_home(&self) -> Utf8PathBuf;
    fn get_state_home(&self) -> Utf8PathBuf;
}

/// Provide path locations for a given application name from a
/// local perspective.
///
/// Supporting files/directories may be required in an application. Items
/// such as settings-files, log-directories, data-directories etc. Must
/// have path locations. This module makes some general assumptions as to
/// where these supporting-files should exist and provides these paths.
///
/// # Notes
/// * The term `local` is used to mean an application that is being run from
///   the user's perspective; as opposed to being run as a server. The
///   path locations, provided by this struct, will exist in the
///   passed in `home` value..
/// * This struct only provides the directory locations, it does NOT create
///   or validate the directories.
/// * It is recommended to use
///   [`get_local_application_paths`](fn@crate::get_local_application_paths)
///   because it provides the mechanism to get the current user's home
///   directory or can perform some basic validation on a passed in `home`
///
/// # Example
///
/// ```
/// use camino::Utf8PathBuf;
/// use komichi::LocalDirectories;
///
/// let app_name = "myapp";
/// let home = "/home/me";
///
/// let local = LocalDirectories::new(&app_name, &home);
///
/// let cache_home = local.get_cache_home();
/// let config_home = local.get_config_home();
/// let data_home = local.get_data_home();
/// let log_home = local.get_log_home();
/// let state_home = local.get_state_home();
/// ```
///
pub struct LocalDirectories {
    info: Box<dyn LocalInfo>,
}

impl LocalDirectories {
    pub fn new<T>(
        app_name: &str,
        home: &T,
    ) -> Self
    where
        T: AsRef<Utf8Path> + ?Sized,
    {
        let info = Box::new(Info::new(app_name, home));
        Self { info }
    }

    /// Return the local directory for the application cache files:
    /// * `linux`/`unix` - `$XDG_CACHE_HOME/<app>` or `~/.cache/<app>`
    /// * `mac`   - `$XDG_CACHE_HOME/<app>` or `~/Library/Caches/<app>`
    ///
    /// This method does NOT create or validate the existence of the returned
    /// path.
    pub fn get_cache_home(&self) -> Utf8PathBuf {
        self.info.get_cache_home()
    }

    /// Return the local directory for the application config files:
    /// * `linux`/`unix` - `$XDG_CONFIG_HOME/<app>` or `~/.config/<app>`
    /// * `mac` - `$XDG_CONFIG_HOME/<app>` or
    ///   `~/Library/ApplicationSupport/<app>/config` or
    ///   `~/Library/Application Support/<app>/config`
    ///
    /// This method does NOT create or validate the existence of the returned
    /// path.
    pub fn get_config_home(&self) -> Utf8PathBuf {
        self.info.get_config_home()
    }

    /// Return the local directory containing the application data files
    /// * `linux`/`unix` - `$XDG_DATA_HOME/<app>` or `~/.local/share/<app>`
    /// * `mac` - `$XDG_DATA_HOME/<app>` or
    ///   `~/Library/ApplicationSupport/<app>/data` or
    ///   `~/Library/Application Support/<app>/data`
    ///
    /// This method does NOT create or validate the existence of the returned
    /// path.
    pub fn get_data_home(&self) -> Utf8PathBuf {
        self.info.get_data_home()
    }

    /// Return the local directory for the application log files.
    /// * `linux`/`unix` - `$<APP_NAME>_LOG_DIR` or `<state_home>/<app>/log`
    /// * `mac` - `$<APP_NAME>_LOG_DIR` or `~/Library/Logs/<app>`
    ///
    /// ## Note
    /// This method does NOT create or validate the existence of the returned
    /// path.
    pub fn get_log_home(&self) -> Utf8PathBuf {
        self.info.get_log_home()
    }

    /// Return the local directory containing state data files.
    /// * `linux`/`unix` - `$XDG_STATE_HOME/<app>` or `~/.local/state/<app>`
    /// * `mac` - `$XDG_STATE_HOME/<app>` or
    ///   `~/Library/ApplicationSupport/<app>/state` or
    ///   `~/Library/Application Support/<app>/state`
    ///
    /// This method does NOT create or validate the existence of the returned
    /// path.
    pub fn get_state_home(&self) -> Utf8PathBuf {
        self.info.get_state_home()
    }
}