1 //! The _dirs-next_ crate is
2 //!
3 //! - a tiny library with a minimal API (16 functions)
4 //! - that provides the platform-specific, user-accessible locations
5 //! - for finding and storing configuration, cache and other data
6 //! - on Linux, Redox, Windows (≥ Vista) and macOS.
7 //!
8 //! The library provides the location of these directories by leveraging the mechanisms defined by
9 //!
10 //! - the [XDG base directory](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) and the [XDG user directory](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/) specifications on Linux,
11 //! - the [Known Folder](https://msdn.microsoft.com/en-us/library/windows/desktop/bb776911(v=vs.85).aspx) system on Windows, and
12 //! - the [Standard Directories](https://developer.apple.com/library/content/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/FileSystemOverview/FileSystemOverview.html#//apple_ref/doc/uid/TP40010672-CH2-SW6) on macOS.
13 
14 #![deny(missing_docs)]
15 #![warn(rust_2018_idioms)]
16 
17 use cfg_if::cfg_if;
18 
19 use std::path::PathBuf;
20 
21 cfg_if! {
22     if #[cfg(target_os = "windows")] {
23         mod win;
24         use win as sys;
25     } else if #[cfg(any(target_os = "macos", target_os = "ios"))] {
26         mod mac;
27         use mac as sys;
28     } else if #[cfg(target_arch = "wasm32")] {
29         mod wasm;
30         use wasm as sys;
31     } else {
32         mod lin;
33         use crate::lin as sys;
34     }
35 }
36 
37 /// Returns the path to the user's home directory.
38 ///
39 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
40 ///
41 /// |Platform | Value                | Example        |
42 /// | ------- | -------------------- | -------------- |
43 /// | Linux   | `$HOME`              | /home/alice    |
44 /// | macOS   | `$HOME`              | /Users/Alice   |
45 /// | Windows | `{FOLDERID_Profile}` | C:\Users\Alice |
46 ///
47 /// ### Linux and macOS:
48 ///
49 /// - Use `$HOME` if it is set and not empty.
50 /// - If `$HOME` is not set or empty, then the function `getpwuid_r` is used to determine
51 ///   the home directory of the current user.
52 /// - If `getpwuid_r` lacks an entry for the current user id or the home directory field is empty,
53 ///   then the function returns `None`.
54 ///
55 /// ### Windows:
56 ///
57 /// This function retrieves the user profile folder using `SHGetKnownFolderPath`.
58 ///
59 /// All the examples on this page mentioning `$HOME` use this behavior.
60 ///
61 /// _Note:_ This function's behavior differs from [`std::env::home_dir`],
62 /// which works incorrectly on Linux, macOS and Windows.
63 ///
64 /// [`std::env::home_dir`]: https://doc.rust-lang.org/std/env/fn.home_dir.html
home_dir() -> Option<PathBuf>65 pub fn home_dir() -> Option<PathBuf> {
66     sys::home_dir()
67 }
68 /// Returns the path to the user's cache directory.
69 ///
70 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
71 ///
72 /// |Platform | Value                               | Example                      |
73 /// | ------- | ----------------------------------- | ---------------------------- |
74 /// | Linux   | `$XDG_CACHE_HOME` or `$HOME`/.cache | /home/alice/.cache           |
75 /// | macOS   | `$HOME`/Library/Caches              | /Users/Alice/Library/Caches  |
76 /// | Windows | `{FOLDERID_LocalAppData}`           | C:\Users\Alice\AppData\Local |
cache_dir() -> Option<PathBuf>77 pub fn cache_dir() -> Option<PathBuf> {
78     sys::cache_dir()
79 }
80 /// Returns the path to the user's config directory.
81 ///
82 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
83 ///
84 /// |Platform | Value                                 | Example                          |
85 /// | ------- | ------------------------------------- | -------------------------------- |
86 /// | Linux   | `$XDG_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config              |
87 /// | macOS   | `$HOME`/Library/Application Support   | /Users/Alice/Library/Application Support |
88 /// | Windows | `{FOLDERID_RoamingAppData}`           | C:\Users\Alice\AppData\Roaming   |
config_dir() -> Option<PathBuf>89 pub fn config_dir() -> Option<PathBuf> {
90     sys::config_dir()
91 }
92 /// Returns the path to the user's data directory.
93 ///
94 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
95 ///
96 /// |Platform | Value                                    | Example                                  |
97 /// | ------- | ---------------------------------------- | ---------------------------------------- |
98 /// | Linux   | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share                 |
99 /// | macOS   | `$HOME`/Library/Application Support      | /Users/Alice/Library/Application Support |
100 /// | Windows | `{FOLDERID_RoamingAppData}`              | C:\Users\Alice\AppData\Roaming           |
data_dir() -> Option<PathBuf>101 pub fn data_dir() -> Option<PathBuf> {
102     sys::data_dir()
103 }
104 /// Returns the path to the user's local data directory.
105 ///
106 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
107 ///
108 /// |Platform | Value                                    | Example                                  |
109 /// | ------- | ---------------------------------------- | ---------------------------------------- |
110 /// | Linux   | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share                 |
111 /// | macOS   | `$HOME`/Library/Application Support      | /Users/Alice/Library/Application Support |
112 /// | Windows | `{FOLDERID_LocalAppData}`                | C:\Users\Alice\AppData\Local             |
data_local_dir() -> Option<PathBuf>113 pub fn data_local_dir() -> Option<PathBuf> {
114     sys::data_local_dir()
115 }
116 /// Returns the path to the user's executable directory.
117 ///
118 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
119 ///
120 /// |Platform | Value                                                            | Example                |
121 /// | ------- | ---------------------------------------------------------------- | ---------------------- |
122 /// | Linux   | `$XDG_BIN_HOME` or `$XDG_DATA_HOME`/../bin or `$HOME`/.local/bin | /home/alice/.local/bin |
123 /// | macOS   | –                                                                | –                      |
124 /// | Windows | –                                                                | –                      |
executable_dir() -> Option<PathBuf>125 pub fn executable_dir() -> Option<PathBuf> {
126     sys::executable_dir()
127 }
128 /// Returns the path to the user's runtime directory.
129 ///
130 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
131 ///
132 /// |Platform | Value              | Example         |
133 /// | ------- | ------------------ | --------------- |
134 /// | Linux   | `$XDG_RUNTIME_DIR` | /run/user/1001/ |
135 /// | macOS   | –                  | –               |
136 /// | Windows | –                  | –               |
runtime_dir() -> Option<PathBuf>137 pub fn runtime_dir() -> Option<PathBuf> {
138     sys::runtime_dir()
139 }
140 
141 /// Returns the path to the user's audio directory.
142 ///
143 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
144 ///
145 /// |Platform | Value              | Example              |
146 /// | ------- | ------------------ | -------------------- |
147 /// | Linux   | `XDG_MUSIC_DIR`    | /home/alice/Music    |
148 /// | macOS   | `$HOME`/Music      | /Users/Alice/Music   |
149 /// | Windows | `{FOLDERID_Music}` | C:\Users\Alice\Music |
audio_dir() -> Option<PathBuf>150 pub fn audio_dir() -> Option<PathBuf> {
151     sys::audio_dir()
152 }
153 /// Returns the path to the user's desktop directory.
154 ///
155 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
156 ///
157 /// |Platform | Value                | Example                |
158 /// | ------- | -------------------- | ---------------------- |
159 /// | Linux   | `XDG_DESKTOP_DIR`    | /home/alice/Desktop    |
160 /// | macOS   | `$HOME`/Desktop      | /Users/Alice/Desktop   |
161 /// | Windows | `{FOLDERID_Desktop}` | C:\Users\Alice\Desktop |
desktop_dir() -> Option<PathBuf>162 pub fn desktop_dir() -> Option<PathBuf> {
163     sys::desktop_dir()
164 }
165 /// Returns the path to the user's document directory.
166 ///
167 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
168 ///
169 /// |Platform | Value                  | Example                  |
170 /// | ------- | ---------------------- | ------------------------ |
171 /// | Linux   | `XDG_DOCUMENTS_DIR`    | /home/alice/Documents    |
172 /// | macOS   | `$HOME`/Documents      | /Users/Alice/Documents   |
173 /// | Windows | `{FOLDERID_Documents}` | C:\Users\Alice\Documents |
document_dir() -> Option<PathBuf>174 pub fn document_dir() -> Option<PathBuf> {
175     sys::document_dir()
176 }
177 /// Returns the path to the user's download directory.
178 ///
179 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
180 ///
181 /// |Platform | Value                  | Example                  |
182 /// | ------- | ---------------------- | ------------------------ |
183 /// | Linux   | `XDG_DOWNLOAD_DIR`     | /home/alice/Downloads    |
184 /// | macOS   | `$HOME`/Downloads      | /Users/Alice/Downloads   |
185 /// | Windows | `{FOLDERID_Downloads}` | C:\Users\Alice\Downloads |
download_dir() -> Option<PathBuf>186 pub fn download_dir() -> Option<PathBuf> {
187     sys::download_dir()
188 }
189 /// Returns the path to the user's font directory.
190 ///
191 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
192 ///
193 /// |Platform | Value                                                | Example                        |
194 /// | ------- | ---------------------------------------------------- | ------------------------------ |
195 /// | Linux   | `$XDG_DATA_HOME`/fonts or `$HOME`/.local/share/fonts | /home/alice/.local/share/fonts |
196 /// | macOS   | `$HOME/Library/Fonts`                                | /Users/Alice/Library/Fonts     |
197 /// | Windows | –                                                    | –                              |
font_dir() -> Option<PathBuf>198 pub fn font_dir() -> Option<PathBuf> {
199     sys::font_dir()
200 }
201 /// Returns the path to the user's picture directory.
202 ///
203 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
204 ///
205 /// |Platform | Value                 | Example                 |
206 /// | ------- | --------------------- | ----------------------- |
207 /// | Linux   | `XDG_PICTURES_DIR`    | /home/alice/Pictures    |
208 /// | macOS   | `$HOME`/Pictures      | /Users/Alice/Pictures   |
209 /// | Windows | `{FOLDERID_Pictures}` | C:\Users\Alice\Pictures |
picture_dir() -> Option<PathBuf>210 pub fn picture_dir() -> Option<PathBuf> {
211     sys::picture_dir()
212 }
213 /// Returns the path to the user's public directory.
214 ///
215 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
216 ///
217 /// |Platform | Value                 | Example             |
218 /// | ------- | --------------------- | ------------------- |
219 /// | Linux   | `XDG_PUBLICSHARE_DIR` | /home/alice/Public  |
220 /// | macOS   | `$HOME`/Public        | /Users/Alice/Public |
221 /// | Windows | `{FOLDERID_Public}`   | C:\Users\Public     |
public_dir() -> Option<PathBuf>222 pub fn public_dir() -> Option<PathBuf> {
223     sys::public_dir()
224 }
225 /// Returns the path to the user's template directory.
226 ///
227 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
228 ///
229 /// |Platform | Value                  | Example                                                    |
230 /// | ------- | ---------------------- | ---------------------------------------------------------- |
231 /// | Linux   | `XDG_TEMPLATES_DIR`    | /home/alice/Templates                                      |
232 /// | macOS   | –                      | –                                                          |
233 /// | Windows | `{FOLDERID_Templates}` | C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Templates |
template_dir() -> Option<PathBuf>234 pub fn template_dir() -> Option<PathBuf> {
235     sys::template_dir()
236 }
237 
238 /// Returns the path to the user's video directory.
239 ///
240 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
241 ///
242 /// |Platform | Value               | Example               |
243 /// | ------- | ------------------- | --------------------- |
244 /// | Linux   | `XDG_VIDEOS_DIR`    | /home/alice/Videos    |
245 /// | macOS   | `$HOME`/Movies      | /Users/Alice/Movies   |
246 /// | Windows | `{FOLDERID_Videos}` | C:\Users\Alice\Videos |
video_dir() -> Option<PathBuf>247 pub fn video_dir() -> Option<PathBuf> {
248     sys::video_dir()
249 }
250 
251 #[cfg(test)]
252 mod tests {
253     #[test]
test_dirs()254     fn test_dirs() {
255         println!("home_dir:       {:?}", crate::home_dir());
256         println!("cache_dir:      {:?}", crate::cache_dir());
257         println!("config_dir:     {:?}", crate::config_dir());
258         println!("data_dir:       {:?}", crate::data_dir());
259         println!("data_local_dir: {:?}", crate::data_local_dir());
260         println!("executable_dir: {:?}", crate::executable_dir());
261         println!("runtime_dir:    {:?}", crate::runtime_dir());
262         println!("audio_dir:      {:?}", crate::audio_dir());
263         println!("home_dir:       {:?}", crate::desktop_dir());
264         println!("cache_dir:      {:?}", crate::document_dir());
265         println!("config_dir:     {:?}", crate::download_dir());
266         println!("font_dir:       {:?}", crate::font_dir());
267         println!("picture_dir:    {:?}", crate::picture_dir());
268         println!("public_dir:     {:?}", crate::public_dir());
269         println!("template_dir:   {:?}", crate::template_dir());
270         println!("video_dir:      {:?}", crate::video_dir());
271     }
272 }
273