1 use std;
2 
3 /// Struct that holds information about your app.
4 ///
5 /// It's recommended to create a single `const` instance of `AppInfo`:
6 ///
7 /// ```
8 /// use app_dirs::AppInfo;
9 /// const APP_INFO: AppInfo = AppInfo{name: "Awesome App", author: "Dedicated Dev"};
10 /// ```
11 ///
12 /// # Caveats
13 /// Functions in this library sanitize any characters that could be
14 /// non-filename-safe from `name` and `author`. The resulting paths will be
15 /// more human-readable if you stick to **letters, numbers, spaces, hyphens,
16 /// underscores, and periods** for both properties.
17 ///
18 /// The `author` property is currently only used by Windows, as macOS and *nix
19 /// specifications don't require it. Make sure your `name` string is unique!
20 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
21 pub struct AppInfo {
22     /// Name of your app (e.g. "Hearthstone").
23     pub name: &'static str,
24     /// Author of your app (e.g. "Blizzard").
25     pub author: &'static str,
26 }
27 
28 /// Enum specifying the type of app data you want to store.
29 ///
30 /// **Different platforms are NOT guaranteed to distinguish between each data
31 /// type.** Keep this in mind when choosing data file paths.
32 ///
33 /// Example: Windows does not supported shared application data and does not
34 /// distinguish between config and data. Therefore, on Windows, all variants
35 /// except `UserCache` return the same path.
36 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
37 pub enum AppDataType {
38     /// User-specific app configuration data.
39     UserConfig,
40     /// User-specific arbitrary app data.
41     UserData,
42     /// User-specific app cache data.
43     UserCache,
44     /// System-wide arbitrary app data.
45     SharedData,
46     /// System-wide app configuration data.
47     SharedConfig,
48 }
49 
50 impl AppDataType {
51     /// Returns `true` for non-user-specific data types.
is_shared(&self) -> bool52     pub fn is_shared(&self) -> bool {
53         use AppDataType::*;
54         match *self {
55             SharedData | SharedConfig => true,
56             _ => false,
57         }
58     }
59 }
60 
61 const ERR_NOT_SUPPORTED: &'static str = "App data directories not supported";
62 const ERR_INVALID_APP_INFO: &'static str = "Invalid app name or author";
63 
64 /// Error type for any `app_dirs` operation.
65 #[derive(Debug)]
66 pub enum AppDirsError {
67     /// An I/O error occurred during the operation.
68     Io(std::io::Error),
69     /// App-specific directories are not properly supported by the system
70     /// (e.g. required environment variables don't exist).
71     NotSupported,
72     /// App info given to this library was invalid (e.g. app name or author
73     /// were empty).
74     InvalidAppInfo,
75 }
76 
77 impl std::fmt::Display for AppDirsError {
fmt(&self, f: &mut std::fmt::Formatter) -> Result<(), std::fmt::Error>78     fn fmt(&self, f: &mut std::fmt::Formatter) -> Result<(), std::fmt::Error> {
79         use AppDirsError::*;
80         match *self {
81             Io(ref e) => e.fmt(f),
82             NotSupported => f.write_str(ERR_NOT_SUPPORTED),
83             InvalidAppInfo => f.write_str(ERR_INVALID_APP_INFO),
84         }
85     }
86 }
87 
88 impl std::error::Error for AppDirsError {
description(&self) -> &str89     fn description(&self) -> &str {
90         use AppDirsError::*;
91         match *self {
92             Io(ref e) => e.description(),
93             NotSupported => "App data directories not supported",
94             InvalidAppInfo => "Invalid app name or author",
95         }
96     }
cause(&self) -> Option<&std::error::Error>97     fn cause(&self) -> Option<&std::error::Error> {
98         use AppDirsError::*;
99         match *self {
100             Io(ref e) => Some(e),
101             NotSupported | InvalidAppInfo => None,
102         }
103     }
104 }
105 
106 impl From<std::io::Error> for AppDirsError {
from(e: std::io::Error) -> Self107     fn from(e: std::io::Error) -> Self {
108         AppDirsError::Io(e)
109     }
110 }
111