1//! The _directories_ crate is
2//!
3//! - a tiny library with a minimal API (3 structs, 4 factory functions, getters)
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
15#![deny(missing_docs)]
16
17use std::path::Path;
18use std::path::PathBuf;
19
20#[cfg(target_os = "windows")]
21mod win;
22#[cfg(target_os = "windows")]
23use win as sys;
24#[cfg(any(target_os = "macos", target_os = "ios"))]
25mod mac;
26#[cfg(any(target_os = "macos", target_os = "ios"))]
27use mac as sys;
28#[cfg(target_arch = "wasm32")]
29mod wasm;
30#[cfg(target_arch = "wasm32")]
31use wasm as sys;
32#[cfg(not(any(
33 target_os = "windows",
34 target_os = "macos", target_os = "ios",
35 target_arch = "wasm32"
36)))]
37mod lin;
38#[cfg(not(any(
39 target_os = "windows",
40 target_os = "macos", target_os = "ios",
41 target_arch = "wasm32"
42)))]
43use lin as sys;
44
45/// `BaseDirs` provides paths of user-invisible standard directories, following the conventions of the operating system the library is running on.
46///
47/// To compute the location of cache, config or data directories for individual projects or applications, use `ProjectDirs` instead.
48///
49/// # Examples
50///
51/// All examples on this page are computed with a user named _Alice_.
52///
53/// ```
54/// use directories::BaseDirs;
55/// if let Some(base_dirs) = BaseDirs::new() {
56/// base_dirs.config_dir();
57/// // Linux: /home/alice/.config
58/// // Windows: C:\Users\Alice\AppData\Roaming
59/// // macOS: /Users/Alice/Library/Application Support
60/// }
61/// ```
62#[derive(Debug, Clone)]
63pub struct BaseDirs {
64 // home directory
65 home_dir: PathBuf,
66
67 // base directories
68 cache_dir: PathBuf,
69 config_dir: PathBuf,
70 config_local_dir: PathBuf,
71 data_dir: PathBuf,
72 data_local_dir: PathBuf,
73 executable_dir: Option<PathBuf>,
74 preference_dir: PathBuf,
75 runtime_dir: Option<PathBuf>,
76 state_dir: Option<PathBuf>
77}
78
79/// `UserDirs` provides paths of user-facing standard directories, following the conventions of the operating system the library is running on.
80///
81/// # Examples
82///
83/// All examples on this page are computed with a user named _Alice_.
84///
85/// ```
86/// use directories::UserDirs;
87/// if let Some(user_dirs) = UserDirs::new() {
88/// user_dirs.audio_dir();
89/// // Linux: /home/alice/Music
90/// // Windows: C:\Users\Alice\Music
91/// // macOS: /Users/Alice/Music
92/// }
93/// ```
94#[derive(Debug, Clone)]
95pub struct UserDirs {
96 // home directory
97 home_dir: PathBuf,
98
99 // user directories
100 audio_dir: Option<PathBuf>,
101 desktop_dir: Option<PathBuf>,
102 document_dir: Option<PathBuf>,
103 download_dir: Option<PathBuf>,
104 font_dir: Option<PathBuf>,
105 picture_dir: Option<PathBuf>,
106 public_dir: Option<PathBuf>,
107 template_dir: Option<PathBuf>,
108 // trash_dir: PathBuf,
109 video_dir: Option<PathBuf>
110}
111
112/// `ProjectDirs` computes the location of cache, config or data directories for a specific application,
113/// which are derived from the standard directories and the name of the project/organization.
114///
115/// # Examples
116///
117/// All examples on this page are computed with a user named _Alice_,
118/// and a `ProjectDirs` struct created with `ProjectDirs::from("com", "Foo Corp", "Bar App")`.
119///
120/// ```
121/// use directories::ProjectDirs;
122/// if let Some(proj_dirs) = ProjectDirs::from("com", "Foo Corp", "Bar App") {
123/// proj_dirs.config_dir();
124/// // Linux: /home/alice/.config/barapp
125/// // Windows: C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App
126/// // macOS: /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App
127/// }
128/// ```
129#[derive(Debug, Clone)]
130pub struct ProjectDirs {
131 project_path: PathBuf,
132
133 // base directories
134 cache_dir: PathBuf,
135 config_dir: PathBuf,
136 config_local_dir: PathBuf,
137 data_dir: PathBuf,
138 data_local_dir: PathBuf,
139 preference_dir: PathBuf,
140 runtime_dir: Option<PathBuf>,
141 state_dir: Option<PathBuf>
142}
143
144impl BaseDirs {
145 /// Creates a `BaseDirs` struct which holds the paths to user-invisible directories for cache, config, etc. data on the system.
146 ///
147 /// The returned value depends on the operating system and is either
148 /// - `Some`, containing a snapshot of the state of the system's paths at the time `new()` was invoked, or
149 /// - `None`, if no valid home directory path could be retrieved from the operating system.
150 ///
151 /// To determine whether a system provides a valid `$HOME` path, the following rules are applied:
152 ///
153 /// ### Linux and macOS:
154 ///
155 /// - Use `$HOME` if it is set and not empty.
156 /// - If `$HOME` is not set or empty, then the function `getpwuid_r` is used to determine
157 /// the home directory of the current user.
158 /// - If `getpwuid_r` lacks an entry for the current user id or the home directory field is empty,
159 /// then the function returns `None`.
160 ///
161 /// ### Windows:
162 ///
163 /// - Retrieve the user profile folder using `SHGetKnownFolderPath`.
164 /// - If this fails, then the function returns `None`.
165 ///
166 /// _Note:_ This logic differs from [`std::env::home_dir`],
167 /// which works incorrectly on Linux, macOS and Windows.
168 ///
169 /// [`std::env::home_dir`]: https://doc.rust-lang.org/std/env/fn.home_dir.html
170 pub fn new() -> Option<BaseDirs> {
171 sys::base_dirs()
172 }
173 /// Returns the path to the user's home directory.
174 ///
175 /// |Platform | Value | Example |
176 /// | ------- | -------------------- | -------------- |
177 /// | Linux | `$HOME` | /home/alice |
178 /// | macOS | `$HOME` | /Users/Alice |
179 /// | Windows | `{FOLDERID_Profile}` | C:\Users\Alice |
180 pub fn home_dir(&self) -> &Path {
181 self.home_dir.as_path()
182 }
183 /// Returns the path to the user's cache directory.
184 ///
185 /// |Platform | Value | Example |
186 /// | ------- | ----------------------------------- | ---------------------------- |
187 /// | Linux | `$XDG_CACHE_HOME` or `$HOME`/.cache | /home/alice/.cache |
188 /// | macOS | `$HOME`/Library/Caches | /Users/Alice/Library/Caches |
189 /// | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local |
190 pub fn cache_dir(&self) -> &Path {
191 self.cache_dir.as_path()
192 }
193 /// Returns the path to the user's config directory.
194 ///
195 /// |Platform | Value | Example |
196 /// | ------- | ------------------------------------- | ---------------------------------------- |
197 /// | Linux | `$XDG_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config |
198 /// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support |
199 /// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming |
200 pub fn config_dir(&self) -> &Path {
201 self.config_dir.as_path()
202 }
203 /// Returns the path to the user's local config directory.
204 ///
205 /// |Platform | Value | Example |
206 /// | ------- | ------------------------------------- | ---------------------------------------- |
207 /// | Linux | `$XDG_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config |
208 /// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support |
209 /// | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local |
210 pub fn config_local_dir(&self) -> &Path {
211 self.config_local_dir.as_path()
212 }
213 /// Returns the path to the user's data directory.
214 ///
215 /// |Platform | Value | Example |
216 /// | ------- | ---------------------------------------- | ---------------------------------------- |
217 /// | Linux | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share |
218 /// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support |
219 /// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming |
220 pub fn data_dir(&self) -> &Path {
221 self.data_dir.as_path()
222 }
223 /// Returns the path to the user's local data directory.
224 ///
225 /// |Platform | Value | Example |
226 /// | ------- | ---------------------------------------- | ---------------------------------------- |
227 /// | Linux | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share |
228 /// | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support |
229 /// | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local |
230 pub fn data_local_dir(&self) -> &Path {
231 self.data_local_dir.as_path()
232 }
233 /// Returns the path to the user's executable directory.
234 ///
235 /// |Platform | Value | Example |
236 /// | ------- | ---------------------------------------------------------------- | ---------------------- |
237 /// | Linux | `$XDG_BIN_HOME` or `$XDG_DATA_HOME`/../bin or `$HOME`/.local/bin | /home/alice/.local/bin |
238 /// | macOS | – | – |
239 /// | Windows | – | – |
240 pub fn executable_dir(&self) -> Option<&Path> {
241 self.executable_dir.as_ref().map(|p| p.as_path())
242 }
243 /// Returns the path to the user's preference directory.
244 ///
245 /// |Platform | Value | Example |
246 /// | ------- | ------------------------------------- | -------------------------------- |
247 /// | Linux | `$XDG_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config |
248 /// | macOS | `$HOME`/Library/Preferences | /Users/Alice/Library/Preferences |
249 /// | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming |
250 pub fn preference_dir(&self) -> &Path {
251 self.preference_dir.as_path()
252 }
253 /// Returns the path to the user's runtime directory.
254 ///
255 /// |Platform | Value | Example |
256 /// | ------- | ------------------ | --------------- |
257 /// | Linux | `$XDG_RUNTIME_DIR` | /run/user/1001/ |
258 /// | macOS | – | – |
259 /// | Windows | – | – |
260 pub fn runtime_dir(&self) -> Option<&Path> {
261 self.runtime_dir.as_ref().map(|p| p.as_path())
262 }
263 /// Returns the path to the user's state directory.
264 ///
265 /// The state directory contains data that should be retained between sessions (unlike the runtime
266 /// directory), but may not be important/portable enough to be synchronized across machines (unlike
267 /// the config/preferences/data directories).
268 ///
269 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
270 ///
271 /// |Platform | Value | Example |
272 /// | ------- | ----------------------------------------- | ------------------------ |
273 /// | Linux | `$XDG_STATE_HOME` or `$HOME`/.local/state | /home/alice/.local/state |
274 /// | macOS | – | – |
275 /// | Windows | – | – |
276 pub fn state_dir(&self) -> Option<&Path> {
277 self.state_dir.as_ref().map(|p| p.as_path())
278 }
279}
280
281impl UserDirs {
282 /// Creates a `UserDirs` struct which holds the paths to user-facing directories for audio, font, video, etc. data on the system.
283 ///
284 /// The returned value depends on the operating system and is either
285 /// - `Some`, containing a snapshot of the state of the system's paths at the time `new()` was invoked, or
286 /// - `None`, if no valid home directory path could be retrieved from the operating system.
287 ///
288 /// To determine whether a system provides a valid `$HOME` path, please refer to [`BaseDirs::new`]
289 pub fn new() -> Option<UserDirs> {
290 sys::user_dirs()
291 }
292 /// Returns the path to the user's home directory.
293 ///
294 /// |Platform | Value | Example |
295 /// | ------- | -------------------- | -------------- |
296 /// | Linux | `$HOME` | /home/alice |
297 /// | macOS | `$HOME` | /Users/Alice |
298 /// | Windows | `{FOLDERID_Profile}` | C:\Users\Alice |
299 pub fn home_dir(&self) -> &Path {
300 self.home_dir.as_path()
301 }
302 /// Returns the path to the user's audio directory.
303 ///
304 /// |Platform | Value | Example |
305 /// | ------- | ------------------ | -------------------- |
306 /// | Linux | `XDG_MUSIC_DIR` | /home/alice/Music |
307 /// | macOS | `$HOME`/Music | /Users/Alice/Music |
308 /// | Windows | `{FOLDERID_Music}` | C:\Users\Alice\Music |
309 pub fn audio_dir(&self) -> Option<&Path> {
310 self.audio_dir.as_ref().map(|p| p.as_path())
311 }
312 /// Returns the path to the user's desktop directory.
313 ///
314 /// |Platform | Value | Example |
315 /// | ------- | -------------------- | ---------------------- |
316 /// | Linux | `XDG_DESKTOP_DIR` | /home/alice/Desktop |
317 /// | macOS | `$HOME`/Desktop | /Users/Alice/Desktop |
318 /// | Windows | `{FOLDERID_Desktop}` | C:\Users\Alice\Desktop |
319 pub fn desktop_dir(&self) -> Option<&Path> {
320 self.desktop_dir.as_ref().map(|p| p.as_path())
321 }
322 /// Returns the path to the user's document directory.
323 ///
324 /// |Platform | Value | Example |
325 /// | ------- | ---------------------- | ------------------------ |
326 /// | Linux | `XDG_DOCUMENTS_DIR` | /home/alice/Documents |
327 /// | macOS | `$HOME`/Documents | /Users/Alice/Documents |
328 /// | Windows | `{FOLDERID_Documents}` | C:\Users\Alice\Documents |
329 pub fn document_dir(&self) -> Option<&Path> {
330 self.document_dir.as_ref().map(|p| p.as_path())
331 }
332 /// Returns the path to the user's download directory.
333 ///
334 /// |Platform | Value | Example |
335 /// | ------- | ---------------------- | ------------------------ |
336 /// | Linux | `XDG_DOWNLOAD_DIR` | /home/alice/Downloads |
337 /// | macOS | `$HOME`/Downloads | /Users/Alice/Downloads |
338 /// | Windows | `{FOLDERID_Downloads}` | C:\Users\Alice\Downloads |
339 pub fn download_dir(&self) -> Option<&Path> {
340 self.download_dir.as_ref().map(|p| p.as_path())
341 }
342 /// Returns the path to the user's font directory.
343 ///
344 /// |Platform | Value | Example |
345 /// | ------- | ---------------------------------------------------- | ------------------------------ |
346 /// | Linux | `$XDG_DATA_HOME`/fonts or `$HOME`/.local/share/fonts | /home/alice/.local/share/fonts |
347 /// | macOS | `$HOME`/Library/Fonts | /Users/Alice/Library/Fonts |
348 /// | Windows | – | – |
349 pub fn font_dir(&self) -> Option<&Path> {
350 self.font_dir.as_ref().map(|p| p.as_path())
351 }
352 /// Returns the path to the user's picture directory.
353 ///
354 /// |Platform | Value | Example |
355 /// | ------- | --------------------- | ----------------------- |
356 /// | Linux | `XDG_PICTURES_DIR` | /home/alice/Pictures |
357 /// | macOS | `$HOME`/Pictures | /Users/Alice/Pictures |
358 /// | Windows | `{FOLDERID_Pictures}` | C:\Users\Alice\Pictures |
359 pub fn picture_dir(&self) -> Option<&Path> {
360 self.picture_dir.as_ref().map(|p| p.as_path())
361 }
362 /// Returns the path to the user's public directory.
363 ///
364 /// |Platform | Value | Example |
365 /// | ------- | --------------------- | ------------------- |
366 /// | Linux | `XDG_PUBLICSHARE_DIR` | /home/alice/Public |
367 /// | macOS | `$HOME`/Public | /Users/Alice/Public |
368 /// | Windows | `{FOLDERID_Public}` | C:\Users\Public |
369 pub fn public_dir(&self) -> Option<&Path> {
370 self.public_dir.as_ref().map(|p| p.as_path())
371 }
372 /// Returns the path to the user's template directory.
373 ///
374 /// |Platform | Value | Example |
375 /// | ------- | ---------------------- | ---------------------------------------------------------- |
376 /// | Linux | `XDG_TEMPLATES_DIR` | /home/alice/Templates |
377 /// | macOS | – | – |
378 /// | Windows | `{FOLDERID_Templates}` | C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Templates |
379 pub fn template_dir(&self) -> Option<&Path> {
380 self.template_dir.as_ref().map(|p| p.as_path())
381 }
382 /// Returns the path to the user's video directory.
383 ///
384 /// |Platform | Value | Example |
385 /// | ------- | ------------------- | --------------------- |
386 /// | Linux | `XDG_VIDEOS_DIR` | /home/alice/Videos |
387 /// | macOS | `$HOME`/Movies | /Users/Alice/Movies |
388 /// | Windows | `{FOLDERID_Videos}` | C:\Users\Alice\Videos |
389 pub fn video_dir(&self) -> Option<&Path> {
390 self.video_dir.as_ref().map(|p| p.as_path())
391 }
392}
393
394impl ProjectDirs {
395 /// Creates a `ProjectDirs` struct directly from a `PathBuf` value.
396 /// The argument is used verbatim and is not adapted to operating system standards.
397 ///
398 /// The use of `ProjectDirs::from_path` is strongly discouraged, as its results will
399 /// not follow operating system standards on at least two of three platforms.
400 ///
401 /// Use [`ProjectDirs::from`] instead.
402 pub fn from_path(project_path: PathBuf) -> Option<ProjectDirs> {
403 sys::project_dirs_from_path(project_path)
404 }
405 /// Creates a `ProjectDirs` struct from values describing the project.
406 ///
407 /// The returned value depends on the operating system and is either
408 /// - `Some`, containing project directory paths based on the state of the system's paths at the time `new()` was invoked, or
409 /// - `None`, if no valid home directory path could be retrieved from the operating system.
410 ///
411 /// To determine whether a system provides a valid `$HOME` path, please refer to [`BaseDirs::new`]
412 ///
413 /// The use of `ProjectDirs::from` (instead of `ProjectDirs::from_path`) is strongly encouraged,
414 /// as its results will follow operating system standards on Linux, macOS and Windows.
415 ///
416 /// # Parameters
417 ///
418 /// - `qualifier` – The reverse domain name notation of the application, excluding the organization or application name itself.<br/>
419 /// An empty string can be passed if no qualifier should be used (only affects macOS).<br/>
420 /// Example values: `"com.example"`, `"org"`, `"uk.co"`, `"io"`, `""`
421 /// - `organization` – The name of the organization that develops this application, or for which the application is developed.<br/>
422 /// An empty string can be passed if no organization should be used (only affects macOS and Windows).<br/>
423 /// Example values: `"Foo Corp"`, `"Alice and Bob Inc"`, `""`
424 /// - `application` – The name of the application itself.<br/>
425 /// Example values: `"Bar App"`, `"ExampleProgram"`, `"Unicorn-Programme"`
426 ///
427 /// [`BaseDirs::home_dir`]: struct.BaseDirs.html#method.home_dir
428 pub fn from(qualifier: &str, organization: &str, application: &str) -> Option<ProjectDirs> {
429 sys::project_dirs_from(qualifier, organization, application)
430 }
431 /// Returns the project path fragment used to compute the project's cache/config/data directories.
432 /// The value is derived from the `ProjectDirs::from` call and is platform-dependent.
433 pub fn project_path(&self) -> &Path {
434 self.project_path.as_path()
435 }
436 /// Returns the path to the project's cache directory.
437 ///
438 /// |Platform | Value | Example |
439 /// | ------- | --------------------------------------------------------------------- | --------------------------------------------------- |
440 /// | Linux | `$XDG_CACHE_HOME`/`_project_path_` or `$HOME`/.cache/`_project_path_` | /home/alice/.cache/barapp |
441 /// | macOS | `$HOME`/Library/Caches/`_project_path_` | /Users/Alice/Library/Caches/com.Foo-Corp.Bar-App |
442 /// | Windows | `{FOLDERID_LocalAppData}`\\`_project_path_`\\cache | C:\Users\Alice\AppData\Local\Foo Corp\Bar App\cache |
443 pub fn cache_dir(&self) -> &Path {
444 self.cache_dir.as_path()
445 }
446 /// Returns the path to the project's config directory.
447 ///
448 /// |Platform | Value | Example |
449 /// | ------- | ----------------------------------------------------------------------- | -------------------------------------------------------------- |
450 /// | Linux | `$XDG_CONFIG_HOME`/`_project_path_` or `$HOME`/.config/`_project_path_` | /home/alice/.config/barapp |
451 /// | macOS | `$HOME`/Library/Application Support/`_project_path_` | /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App |
452 /// | Windows | `{FOLDERID_RoamingAppData}`\\`_project_path_`\\config | C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config |
453 pub fn config_dir(&self) -> &Path {
454 self.config_dir.as_path()
455 }
456 /// Returns the path to the project's local config directory.
457 ///
458 /// |Platform | Value | Example |
459 /// | ------- | ----------------------------------------------------------------------- | -------------------------------------------------------------- |
460 /// | Linux | `$XDG_CONFIG_HOME`/`_project_path_` or `$HOME`/.config/`_project_path_` | /home/alice/.config/barapp |
461 /// | macOS | `$HOME`/Library/Application Support/`_project_path_` | /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App |
462 /// | Windows | `{FOLDERID_LocalAppData}`\\`_project_path_`\\config | C:\Users\Alice\AppData\Local\Foo Corp\Bar App\config |
463 pub fn config_local_dir(&self) -> &Path {
464 self.config_local_dir.as_path()
465 }
466 /// Returns the path to the project's data directory.
467 ///
468 /// |Platform | Value | Example |
469 /// | ------- | -------------------------------------------------------------------------- | ------------------------------------------------------------- |
470 /// | Linux | `$XDG_DATA_HOME`/`_project_path_` or `$HOME`/.local/share/`_project_path_` | /home/alice/.local/share/barapp |
471 /// | macOS | `$HOME`/Library/Application Support/`_project_path_` | /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App |
472 /// | Windows | `{FOLDERID_RoamingAppData}`\\`_project_path_`\\data | C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\data |
473 pub fn data_dir(&self) -> &Path {
474 self.data_dir.as_path()
475 }
476 /// Returns the path to the project's local data directory.
477 ///
478 /// |Platform | Value | Example |
479 /// | ------- | -------------------------------------------------------------------------- | ------------------------------------------------------------- |
480 /// | Linux | `$XDG_DATA_HOME`/`_project_path_` or `$HOME`/.local/share/`_project_path_` | /home/alice/.local/share/barapp |
481 /// | macOS | `$HOME`/Library/Application Support/`_project_path_` | /Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App |
482 /// | Windows | `{FOLDERID_LocalAppData}`\\`_project_path_`\\data | C:\Users\Alice\AppData\Local\Foo Corp\Bar App\data |
483 pub fn data_local_dir(&self) -> &Path {
484 self.data_local_dir.as_path()
485 }
486 /// Returns the path to the project's preference directory.
487 ///
488 /// |Platform | Value | Example |
489 /// | ------- | ----------------------------------------------------------------------- | ------------------------------------------------------ |
490 /// | Linux | `$XDG_CONFIG_HOME`/`_project_path_` or `$HOME`/.config/`_project_path_` | /home/alice/.config/barapp |
491 /// | macOS | `$HOME`/Library/Preferences/`_project_path_` | /Users/Alice/Library/Preferences/com.Foo-Corp.Bar-App |
492 /// | Windows | `{FOLDERID_RoamingAppData}`\\`_project_path_`\\config | C:\Users\Alice\AppData\Roaming\Foo Corp\Bar App\config |
493 pub fn preference_dir(&self) -> &Path {
494 self.preference_dir.as_path()
495 }
496 /// Returns the path to the project's runtime directory.
497 ///
498 /// The runtime directory contains transient, non-essential data (like sockets or named pipes) that
499 /// is expected to be cleared when the user's session ends.
500 ///
501 /// |Platform | Value | Example |
502 /// | ------- | ----------------------------------- | --------------------- |
503 /// | Linux | `$XDG_RUNTIME_DIR`/`_project_path_` | /run/user/1001/barapp |
504 /// | macOS | – | – |
505 /// | Windows | – | – |
506 pub fn runtime_dir(&self) -> Option<&Path> {
507 self.runtime_dir.as_ref().map(|p| p.as_path())
508 }
509 /// Returns the path to the project's state directory.
510 ///
511 /// The state directory contains data that should be retained between sessions (unlike the runtime
512 /// directory), but may not be important/portable enough to be synchronized across machines (unlike
513 /// the config/preferences/data directories).
514 ///
515 /// The returned value depends on the operating system and is either a `Some`, containing a value from the following table, or a `None`.
516 ///
517 /// |Platform | Value | Example |
518 /// | ------- | --------------------------------------------------------------------------- | ------------------------------- |
519 /// | Linux | `$XDG_STATE_HOME`/`_project_path_` or `$HOME`/.local/state/`_project_path_` | /home/alice/.local/state/barapp |
520 /// | macOS | – | – |
521 /// | Windows | – | – |
522 pub fn state_dir(&self) -> Option<&Path> {
523 self.state_dir.as_ref().map(|p| p.as_path())
524 }
525}
526
527#[cfg(test)]
528mod tests {
529 #[test]
530 fn test_base_dirs() {
531 println!("BaseDirs::new())\n{:?}", ::BaseDirs::new());
532 }
533
534 #[test]
535 fn test_user_dirs() {
536 println!("UserDirs::new())\n{:?}", ::UserDirs::new());
537 }
538
539 #[test]
540 fn test_project_dirs() {
541 let proj_dirs = ::ProjectDirs::from("qux", "FooCorp", "BarApp");
542 println!("ProjectDirs::from(\"qux\", \"FooCorp\", \"BarApp\")\n{:?}", proj_dirs);
543 let proj_dirs = ::ProjectDirs::from("qux.zoo", "Foo Corp", "Bar-App");
544 println!("ProjectDirs::from(\"qux.zoo\", \"Foo Corp\", \"Bar-App\")\n{:?}", proj_dirs);
545 let proj_dirs = ::ProjectDirs::from("com", "Foo Corp.", "Bar App");
546 println!("ProjectDirs::from(\"com\", \"Foo Corp.\", \"Bar App\")\n{:?}", proj_dirs);
547 }
548}
549