Skip to main content

serde_ucl/parse/
loader.rs

1//! Loaders: where the include macros and `.load` read files from (spec §9.3, §9.4, §9.6).
2//!
3//! The parser never touches the filesystem itself. It resolves relative paths against its base
4//! directory ([`super::Parser::set_base_dir`]; without one, the directory of the file given to
5//! [`super::Parser::parse_file`], or [`Loader::current_dir`] for a document given as bytes),
6//! and asks the loader to make a path canonical, to say what a path names, to read a file and
7//! to list a directory for glob patterns.
8//!
9//! - [`FsLoader`] (Cargo feature `fs`, on by default) reads the real filesystem.
10//! - [`MemoryLoader`] serves files registered in memory.
11
12use std::collections::{BTreeMap, BTreeSet};
13use std::io;
14use std::path::{Component, Path, PathBuf};
15
16/// What a path names.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum FileKind {
19    /// A regular file.
20    File,
21    /// A directory.
22    Directory,
23    /// Anything else, such as a device, a socket or a FIFO.
24    Other,
25}
26
27/// A source of files for `.include`, `.try_include` and `.load`.
28///
29/// Every path a parser passes to a loader is absolute.
30pub trait Loader {
31    /// The directory that relative paths in a document given as bytes, and a relative path
32    /// given to [`super::Parser::parse_file`], resolve against when the parser has no base
33    /// directory of its own. It is then also `CURDIR` for a document given as bytes (spec §7.8)
34    /// and for macro argument lists in it (spec §9.2).
35    fn current_dir(&self) -> io::Result<PathBuf>;
36
37    /// `path` made canonical: absolute, with `.` and `..` components and symbolic links resolved
38    /// (spec §9.3). An error when nothing exists at `path`.
39    fn canonicalize(&self, path: &Path) -> io::Result<PathBuf>;
40
41    /// Canonicalize an optional include path. Loaders may reject a missing path early; the
42    /// default keeps the behavior of existing loader implementations.
43    fn canonicalize_optional(&self, path: &Path) -> io::Result<PathBuf> {
44        self.canonicalize(path)
45    }
46
47    /// What `path` names, following symbolic links, or `None` if nothing exists there.
48    fn kind(&self, path: &Path) -> Option<FileKind>;
49
50    /// The contents of the regular file at `path`.
51    fn read(&self, path: &Path) -> io::Result<Vec<u8>>;
52
53    /// The contents of the regular file at `path` if it holds at most `limit` bytes; if it holds
54    /// more, any part of it longer than `limit` bytes, such as its first `limit + 1` bytes. A
55    /// parser with an input limit ([`super::Parser::set_max_input_bytes`]) reads files with it,
56    /// so that a large file is not read whole only to be rejected.
57    ///
58    /// The default reads the whole file with [`Loader::read`]; [`FsLoader`] and
59    /// [`MemoryLoader`] stop after `limit + 1` bytes.
60    fn read_limited(&self, path: &Path, limit: u64) -> io::Result<Vec<u8>> {
61        let _ = limit;
62        self.read(path)
63    }
64
65    /// The names of the entries of the directory at `path`, in any order, without `.` and `..`.
66    /// Names that are not valid UTF-8 may be left out. Used to expand glob patterns (spec §9.4).
67    fn read_dir(&self, path: &Path) -> io::Result<Vec<String>>;
68}
69
70/// Reads files from the filesystem with `std::fs`. Its current directory is the process's
71/// working directory: without a base directory, relative paths in a document given as bytes
72/// resolve against it, while those in a file given to [`super::Parser::parse_file`] resolve
73/// against that file's directory.
74#[cfg(feature = "fs")]
75#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
76pub struct FsLoader;
77
78#[cfg(feature = "fs")]
79impl FsLoader {
80    /// The filesystem loader.
81    pub fn new() -> Self {
82        Self
83    }
84}
85
86#[cfg(feature = "fs")]
87impl Loader for FsLoader {
88    fn current_dir(&self) -> io::Result<PathBuf> {
89        std::env::current_dir()
90    }
91
92    fn canonicalize(&self, path: &Path) -> io::Result<PathBuf> {
93        std::fs::canonicalize(path)
94    }
95
96    fn canonicalize_optional(&self, path: &Path) -> io::Result<PathBuf> {
97        std::fs::metadata(path)?;
98        std::fs::canonicalize(path)
99    }
100
101    fn kind(&self, path: &Path) -> Option<FileKind> {
102        let meta = std::fs::metadata(path).ok()?;
103        Some(if meta.is_file() {
104            FileKind::File
105        } else if meta.is_dir() {
106            FileKind::Directory
107        } else {
108            FileKind::Other
109        })
110    }
111
112    fn read(&self, path: &Path) -> io::Result<Vec<u8>> {
113        std::fs::read(path)
114    }
115
116    fn read_limited(&self, path: &Path, limit: u64) -> io::Result<Vec<u8>> {
117        use std::io::Read;
118        let mut bytes = Vec::new();
119        std::fs::File::open(path)?
120            .take(limit.saturating_add(1))
121            .read_to_end(&mut bytes)?;
122        Ok(bytes)
123    }
124
125    fn read_dir(&self, path: &Path) -> io::Result<Vec<String>> {
126        let mut names = Vec::new();
127        for entry in std::fs::read_dir(path)? {
128            if let Ok(name) = entry?.file_name().into_string() {
129                names.push(name);
130            }
131        }
132        Ok(names)
133    }
134}
135
136/// Serves files held in memory, for tests and for applications that embed their configuration.
137///
138/// Paths are kept in a normalised absolute form: a relative path is taken relative to the
139/// loader's current directory (`/` unless [`MemoryLoader::set_current_dir`] changes it), and
140/// `.` and `..` components are resolved by name. The directories above every file exist
141/// implicitly. There are no symbolic links.
142///
143/// ```
144/// use serde_ucl::parse::{MemoryLoader, Parser};
145///
146/// let mut loader = MemoryLoader::new();
147/// loader.add_file("/etc/app/main.conf", "port = 80\n.include \"${CURDIR}/extra.conf\"\n");
148/// loader.add_file("/etc/app/extra.conf", "host = example.org\n");
149/// let mut parser = Parser::new();
150/// parser.set_loader(loader);
151/// let value = parser.parse_file("/etc/app/main.conf").unwrap();
152/// assert_eq!(value.as_object().unwrap()["host"].as_str(), Some("example.org"));
153/// ```
154#[derive(Debug, Clone)]
155pub struct MemoryLoader {
156    files: BTreeMap<PathBuf, Vec<u8>>,
157    dirs: BTreeSet<PathBuf>,
158    current_dir: PathBuf,
159}
160
161impl Default for MemoryLoader {
162    fn default() -> Self {
163        Self::new()
164    }
165}
166
167impl MemoryLoader {
168    /// An empty loader whose current directory is `/`.
169    pub fn new() -> Self {
170        let root = root();
171        let mut dirs = BTreeSet::new();
172        dirs.insert(root.clone());
173        Self {
174            files: BTreeMap::new(),
175            dirs,
176            current_dir: root,
177        }
178    }
179
180    /// Adds or replaces the file at `path`, and the directories above it.
181    pub fn add_file(&mut self, path: impl AsRef<Path>, contents: impl Into<Vec<u8>>) -> &mut Self {
182        let path = self.normalise(path.as_ref());
183        if let Some(parent) = path.parent() {
184            self.add_dirs(parent.to_path_buf());
185        }
186        self.files.insert(path, contents.into());
187        self
188    }
189
190    /// Adds the directory at `path`, and the directories above it.
191    pub fn add_dir(&mut self, path: impl AsRef<Path>) -> &mut Self {
192        let path = self.normalise(path.as_ref());
193        self.add_dirs(path);
194        self
195    }
196
197    /// Sets the directory that relative paths are taken relative to, and adds it.
198    pub fn set_current_dir(&mut self, dir: impl AsRef<Path>) -> &mut Self {
199        let dir = self.normalise(dir.as_ref());
200        self.add_dirs(dir.clone());
201        self.current_dir = dir;
202        self
203    }
204
205    fn add_dirs(&mut self, mut dir: PathBuf) {
206        loop {
207            if !self.dirs.insert(dir.clone()) {
208                return;
209            }
210            if !dir.pop() {
211                return;
212            }
213        }
214    }
215
216    /// `path` as an absolute path with `.` and `..` resolved by name.
217    fn normalise(&self, path: &Path) -> PathBuf {
218        let mut out = if path.is_absolute() {
219            PathBuf::new()
220        } else {
221            self.current_dir.clone()
222        };
223        for component in path.components() {
224            match component {
225                Component::Prefix(p) => out.push(p.as_os_str()),
226                Component::RootDir => out.push(Component::RootDir.as_os_str()),
227                Component::CurDir => {}
228                Component::ParentDir => {
229                    out.pop();
230                }
231                Component::Normal(name) => out.push(name),
232            }
233        }
234        if out.as_os_str().is_empty() {
235            out = root();
236        }
237        out
238    }
239}
240
241fn root() -> PathBuf {
242    PathBuf::from(Component::RootDir.as_os_str())
243}
244
245fn not_found(path: &Path) -> io::Error {
246    io::Error::new(
247        io::ErrorKind::NotFound,
248        format!("{}: no such file or directory", path.display()),
249    )
250}
251
252impl MemoryLoader {
253    /// The current directory, borrowed ([`Loader::current_dir`] gives a copy).
254    pub(crate) fn dir(&self) -> &Path {
255        &self.current_dir
256    }
257}
258
259impl Loader for MemoryLoader {
260    fn current_dir(&self) -> io::Result<PathBuf> {
261        Ok(self.current_dir.clone())
262    }
263
264    fn canonicalize(&self, path: &Path) -> io::Result<PathBuf> {
265        let path = self.normalise(path);
266        if self.files.contains_key(&path) || self.dirs.contains(&path) {
267            Ok(path)
268        } else {
269            Err(not_found(&path))
270        }
271    }
272
273    fn kind(&self, path: &Path) -> Option<FileKind> {
274        let path = self.normalise(path);
275        if self.files.contains_key(&path) {
276            Some(FileKind::File)
277        } else if self.dirs.contains(&path) {
278            Some(FileKind::Directory)
279        } else {
280            None
281        }
282    }
283
284    fn read(&self, path: &Path) -> io::Result<Vec<u8>> {
285        self.read_limited(path, u64::MAX)
286    }
287
288    fn read_limited(&self, path: &Path, limit: u64) -> io::Result<Vec<u8>> {
289        let path = self.normalise(path);
290        match self.files.get(&path) {
291            Some(bytes) => {
292                let len = usize::try_from(limit.saturating_add(1)).unwrap_or(usize::MAX);
293                Ok(bytes[..bytes.len().min(len)].to_vec())
294            }
295            None if self.dirs.contains(&path) => Err(io::Error::other(format!(
296                "{}: is a directory",
297                path.display()
298            ))),
299            None => Err(not_found(&path)),
300        }
301    }
302
303    fn read_dir(&self, path: &Path) -> io::Result<Vec<String>> {
304        let dir = self.normalise(path);
305        if !self.dirs.contains(&dir) {
306            return Err(not_found(&dir));
307        }
308        let children = self
309            .files
310            .keys()
311            .chain(self.dirs.iter())
312            .filter(|p| p.parent() == Some(dir.as_path()))
313            .filter_map(|p| p.file_name()?.to_str().map(str::to_owned))
314            .collect();
315        Ok(children)
316    }
317}
318
319#[cfg(test)]
320mod tests {
321    use super::*;
322
323    #[test]
324    fn memory_loader_paths() {
325        let mut m = MemoryLoader::new();
326        m.add_file("/a/b/c.conf", "x = 1").add_dir("/a/empty");
327        m.set_current_dir("/a");
328        assert_eq!(m.kind(Path::new("/a/b/c.conf")), Some(FileKind::File));
329        assert_eq!(m.kind(Path::new("b")), Some(FileKind::Directory));
330        assert_eq!(
331            m.kind(Path::new("/a/b/../b/./c.conf")),
332            Some(FileKind::File)
333        );
334        assert_eq!(m.kind(Path::new("/nope")), None);
335        assert_eq!(
336            m.canonicalize(Path::new("b/../b/c.conf")).unwrap(),
337            PathBuf::from("/a/b/c.conf")
338        );
339        assert!(m.canonicalize(Path::new("/a/x")).is_err());
340        assert_eq!(m.read(Path::new("/a/b/c.conf")).unwrap(), b"x = 1");
341        let limited = |limit| m.read_limited(Path::new("/a/b/c.conf"), limit).unwrap();
342        assert_eq!(limited(5), b"x = 1");
343        assert_eq!(limited(2), b"x =");
344        assert_eq!(limited(u64::MAX), b"x = 1");
345        assert!(m.read_limited(Path::new("/a/b"), 2).is_err());
346        assert!(m.read(Path::new("/a/b")).is_err());
347        let mut names = m.read_dir(Path::new("/a")).unwrap();
348        names.sort();
349        assert_eq!(names, ["b", "empty"]);
350        assert!(m.read_dir(Path::new("/a/b/c.conf")).is_err());
351        assert_eq!(m.current_dir().unwrap(), PathBuf::from("/a"));
352    }
353
354    #[cfg(feature = "fs")]
355    #[test]
356    fn fs_loader_kinds() {
357        let here = Path::new(env!("CARGO_MANIFEST_DIR"));
358        let fs = FsLoader::new();
359        assert_eq!(fs.kind(&here.join("Cargo.toml")), Some(FileKind::File));
360        assert_eq!(fs.kind(&here.join("src")), Some(FileKind::Directory));
361        assert_eq!(fs.kind(&here.join("no such file")), None);
362        assert!(fs.read_dir(here).unwrap().iter().any(|n| n == "Cargo.toml"));
363        let cargo = fs.read(&here.join("Cargo.toml")).unwrap();
364        assert_eq!(
365            fs.read_limited(&here.join("Cargo.toml"), 9).unwrap(),
366            cargo[..10]
367        );
368        assert_eq!(
369            fs.read_limited(&here.join("Cargo.toml"), cargo.len() as u64)
370                .unwrap(),
371            cargo
372        );
373        assert!(fs.read_limited(&here.join("no such file"), 9).is_err());
374    }
375}