cap_directories/
user_dirs.rs

1use crate::not_found;
2use cap_std::fs::Dir;
3use cap_std::AmbientAuthority;
4use std::io;
5
6/// `UserDirs` provides paths of user-facing standard directories, following
7/// the conventions of the operating system the library is running on.
8///
9/// This corresponds to [`directories::UserDirs`], except that the
10/// functions open the directories and returns `Dir`s instead of returning
11/// `Path`s.
12///
13/// Unlike `directories::UserDirs`, the `*_dir` functions return `Dir`s
14/// rather than `Path`s, because absolute paths don't interoperate well with
15/// the capability model.
16#[derive(Clone)]
17pub struct UserDirs {
18    inner: directories::UserDirs,
19}
20
21impl UserDirs {
22    /// Creates a `UserDirs` struct which holds the paths to user-facing
23    /// directories for audio, font, video, etc. data on the system.
24    ///
25    /// This corresponds to [`directories::UserDirs::new`].
26    pub fn new() -> Option<Self> {
27        let inner = directories::UserDirs::new()?;
28        Some(Self { inner })
29    }
30
31    /// Returns the user's home directory.
32    ///
33    /// This corresponds to [`directories::UserDirs::home_dir`].
34    ///
35    /// # Ambient Authority
36    ///
37    /// This function makes use of ambient authority to access the user
38    /// directories.
39    pub fn home_dir(&self, ambient_authority: AmbientAuthority) -> io::Result<Dir> {
40        Dir::open_ambient_dir(self.inner.home_dir(), ambient_authority)
41    }
42
43    /// Returns the user's audio directory.
44    ///
45    /// This corresponds to [`directories::UserDirs::audio_dir`].
46    ///
47    /// # Ambient Authority
48    ///
49    /// This function makes use of ambient authority to access the user
50    /// directories.
51    pub fn audio_dir(&self, ambient_authority: AmbientAuthority) -> io::Result<Dir> {
52        Dir::open_ambient_dir(
53            self.inner.audio_dir().ok_or_else(not_found)?,
54            ambient_authority,
55        )
56    }
57
58    /// Returns the user's desktop directory.
59    ///
60    /// This corresponds to [`directories::UserDirs::desktop_dir`].
61    ///
62    /// # Ambient Authority
63    ///
64    /// This function makes use of ambient authority to access the user
65    /// directories.
66    pub fn desktop_dir(&self, ambient_authority: AmbientAuthority) -> io::Result<Dir> {
67        Dir::open_ambient_dir(
68            self.inner.desktop_dir().ok_or_else(not_found)?,
69            ambient_authority,
70        )
71    }
72
73    /// Returns the user's document directory.
74    ///
75    /// This corresponds to [`directories::UserDirs::document_dir`].
76    ///
77    /// # Ambient Authority
78    ///
79    /// This function makes use of ambient authority to access the user
80    /// directories.
81    pub fn document_dir(&self, ambient_authority: AmbientAuthority) -> io::Result<Dir> {
82        Dir::open_ambient_dir(
83            self.inner.document_dir().ok_or_else(not_found)?,
84            ambient_authority,
85        )
86    }
87
88    /// Returns the user's download directory.
89    ///
90    /// This corresponds to [`directories::UserDirs::download_dir`].
91    ///
92    /// # Ambient Authority
93    ///
94    /// This function makes use of ambient authority to access the user
95    /// directories.
96    pub fn download_dir(&self, ambient_authority: AmbientAuthority) -> io::Result<Dir> {
97        Dir::open_ambient_dir(
98            self.inner.download_dir().ok_or_else(not_found)?,
99            ambient_authority,
100        )
101    }
102
103    /// Returns the user's font directory.
104    ///
105    /// This corresponds to [`directories::UserDirs::font_dir`].
106    ///
107    /// # Ambient Authority
108    ///
109    /// This function makes use of ambient authority to access the user
110    /// directories.
111    pub fn font_dir(&self, ambient_authority: AmbientAuthority) -> io::Result<Dir> {
112        Dir::open_ambient_dir(
113            self.inner.font_dir().ok_or_else(not_found)?,
114            ambient_authority,
115        )
116    }
117
118    /// Returns the user's picture directory.
119    ///
120    /// This corresponds to [`directories::UserDirs::picture_dir`].
121    ///
122    /// # Ambient Authority
123    ///
124    /// This function makes use of ambient authority to access the user
125    /// directories.
126    pub fn picture_dir(&self, ambient_authority: AmbientAuthority) -> io::Result<Dir> {
127        Dir::open_ambient_dir(
128            self.inner.picture_dir().ok_or_else(not_found)?,
129            ambient_authority,
130        )
131    }
132
133    /// Returns the user's public directory.
134    ///
135    /// This corresponds to [`directories::UserDirs::public_dir`].
136    ///
137    /// # Ambient Authority
138    ///
139    /// This function makes use of ambient authority to access the user
140    /// directories.
141    pub fn public_dir(&self, ambient_authority: AmbientAuthority) -> io::Result<Dir> {
142        Dir::open_ambient_dir(
143            self.inner.public_dir().ok_or_else(not_found)?,
144            ambient_authority,
145        )
146    }
147
148    /// Returns the user's template directory.
149    ///
150    /// This corresponds to [`directories::UserDirs::template_dir`].
151    ///
152    /// # Ambient Authority
153    ///
154    /// This function makes use of ambient authority to access the user
155    /// directories.
156    pub fn template_dir(&self, ambient_authority: AmbientAuthority) -> io::Result<Dir> {
157        Dir::open_ambient_dir(
158            self.inner.template_dir().ok_or_else(not_found)?,
159            ambient_authority,
160        )
161    }
162
163    /// Returns the user's video directory.
164    ///
165    /// This corresponds to [`directories::UserDirs::video_dir`].
166    ///
167    /// # Ambient Authority
168    ///
169    /// This function makes use of ambient authority to access the user
170    /// directories.
171    pub fn video_dir(&self, ambient_authority: AmbientAuthority) -> io::Result<Dir> {
172        Dir::open_ambient_dir(
173            self.inner.video_dir().ok_or_else(not_found)?,
174            ambient_authority,
175        )
176    }
177}
cap_directories/user_dirs.rs

cap_directories/
user_dirs.rs
