Skip to main content

c4/
loader.rs

1//! The loader: scan sources, pick parsers by extension, deep-merge with
2//! per-leaf provenance. `load()` is `trace()` minus the labels — one
3//! code path for both.
4
5use std::collections::BTreeMap;
6use std::path::{Path, PathBuf};
7
8use serde::de::DeserializeOwned;
9
10use crate::trace::{SourceRef, TracedValue};
11use crate::{Error, Format, FormatKind, Options, Order, Result, Source, Value, de, format};
12
13/// Loads and merges the config sources named by its [`Options`].
14#[derive(Debug, Clone, Default)]
15pub struct Loader {
16    pub options: Options,
17}
18
19impl Loader {
20    /// Everything — sources included — comes in through [`Options`];
21    /// there is no separate builder step.
22    pub fn new(options: Options) -> Self {
23        Self { options }
24    }
25
26    /// Load and merge all sources, deserializing into `T`.
27    ///
28    /// [`Value`] implements `Deserialize`, so `T = Value` gives dynamic
29    /// access and any other serde type gives typed config.
30    pub fn load<T: DeserializeOwned>(&self) -> Result<T> {
31        let value = untrace(self.trace()?);
32        T::deserialize(de::ValueDeserializer::new(value))
33            .map_err(|e| Error::Deserialize(e.to_string()))
34    }
35
36    /// Like [`Loader::load`], but keeps per-leaf provenance — see
37    /// [`TracedValue`]. This powers the CLI `--trace` mode; source labels
38    /// are a debug/testing aid, not config data.
39    ///
40    /// ```
41    /// use c4::{CustomFormat, Loader, Source, TracedValue};
42    ///
43    /// # fn main() -> Result<(), c4::Error> {
44    /// // a custom-format string source keeps this example runnable
45    /// // under every feature combination (`Loader::default()` would
46    /// // read ./config instead)
47    /// let kv = CustomFormat::new("kv", ["kv"], |text, path, options| {
48    ///     let rows = text
49    ///         .lines()
50    ///         .map(|line| line.split('=').map(str::to_owned).collect())
51    ///         .collect();
52    ///     c4::parse_table(rows, path, options)
53    /// });
54    ///
55    /// let traced = Loader::new(c4::Options {
56    ///     sources: vec![Source::string(kv, "port=8080")],
57    ///     ..c4::Options::default()
58    /// })
59    /// .trace()?;
60    /// let TracedValue::Object(root) = &traced else { unreachable!() };
61    /// let TracedValue::Leaf { value, source } = &root["port"] else { unreachable!() };
62    /// assert_eq!(value.as_u64(), Some(8080));
63    /// assert_eq!(source, &c4::SourceRef::String(0)); // "string:0" in traces
64    /// # Ok(())
65    /// # }
66    /// ```
67    pub fn trace(&self) -> Result<TracedValue> {
68        let extensions = extension_map(&self.options);
69        let mut root = TracedValue::Object(BTreeMap::new());
70
71        for (index, source) in self.options.sources.iter().enumerate() {
72            match source {
73                Source::Folder(path) => {
74                    if !path.is_dir() {
75                        return Err(Error::NotFound(path.clone()));
76                    }
77                    if self.options.tree {
78                        #[cfg(feature = "tree")]
79                        self.merge_tree_folder(path, &extensions, &mut root)?;
80                        #[cfg(not(feature = "tree"))]
81                        return Err(Error::Unsupported(
82                            "Options.tree requires the `tree` Cargo feature".into(),
83                        ));
84                    } else {
85                        for (file, prefix) in scan_folder(path, &self.options)? {
86                            let Some(claim) = claimed_format(&file, &extensions) else {
87                                continue; // no active format claims this extension
88                            };
89                            let mut value = self.parse_file(claim, &file)?;
90                            if matches!(value, Value::Null) {
91                                continue; // empty file contributes nothing
92                            }
93                            for key in prefix.into_iter().rev() {
94                                value = Value::Object(BTreeMap::from([(key, value)]));
95                            }
96                            self.merge(&mut root, value, &SourceRef::File(file));
97                        }
98                    }
99                }
100                Source::File(path) => {
101                    if !path.is_file() {
102                        return Err(Error::NotFound(path.clone()));
103                    }
104                    let claim = claimed_format(path, &extensions).ok_or_else(|| Error::Parse {
105                        path: path.clone(),
106                        message: "no active format claims this file's extension".into(),
107                    })?;
108                    let value = self.parse_file(claim, path)?;
109                    if !matches!(value, Value::Null) {
110                        self.merge(&mut root, value, &SourceRef::File(path.clone()));
111                    }
112                }
113                Source::Value(result) => {
114                    let value = result.clone().map_err(|message| Error::Parse {
115                        path: PathBuf::from(format!("value:{index}")),
116                        message,
117                    })?;
118                    if !matches!(value, Value::Null) {
119                        self.merge(&mut root, value, &SourceRef::Value(index));
120                    }
121                }
122                Source::String { format, content } => {
123                    let label = PathBuf::from(format!("string:{index}"));
124                    let value = match format {
125                        FormatKind::Builtin(format) => {
126                            format::parse(*format, content, &label, &self.options)?
127                        }
128                        FormatKind::Custom(custom) => {
129                            (custom.parser)(content, &label, &self.options)?
130                        }
131                    };
132                    if !matches!(value, Value::Null) {
133                        self.merge(&mut root, value, &SourceRef::String(index));
134                    }
135                }
136            }
137        }
138        Ok(root)
139    }
140
141    fn parse_file(&self, claim: Claim, path: &Path) -> Result<Value> {
142        let text = std::fs::read_to_string(path).map_err(Error::Io)?;
143        match claim {
144            Claim::Builtin(format) => format::parse(format, &text, path, &self.options),
145            Claim::Custom(index) => {
146                let FormatKind::Custom(custom) = &self.options.formats[index].format else {
147                    unreachable!("custom claims always index custom entries");
148                };
149                (custom.parser)(&text, path, &self.options)
150            }
151        }
152    }
153
154    fn merge(&self, target: &mut TracedValue, value: Value, source: &SourceRef) {
155        merge_traced(target, value, source, !self.options.case_sensitive);
156    }
157
158    /// Tree mode: every subfolder is a key, every file is a key named
159    /// after the file (extension stripped) holding its parsed content.
160    /// Entries load in [`Options::order`]; key collisions (`a.json` +
161    /// `a.yml`, or a file next to a same-named folder) deep-merge as
162    /// usual, so the order decides who wins.
163    #[cfg(feature = "tree")]
164    fn merge_tree_folder(
165        &self,
166        folder: &Path,
167        extensions: &[(String, Claim)],
168        root: &mut TracedValue,
169    ) -> Result<()> {
170        let mut files = Vec::new();
171        walk_tree(folder, Vec::new(), &self.options, &mut files)?;
172        for (file, prefix) in files {
173            let name = file
174                .file_name()
175                .and_then(|n| n.to_str())
176                .unwrap_or_default()
177                .to_owned();
178            let value = match claimed_format(&file, extensions) {
179                Some(claim) => self.parse_file(claim, &file)?,
180                None if file_extension(&name).is_none() && self.options.auto_files => {
181                    // extensionless: the trimmed content goes through the
182                    // table auto detection (same feature-gated guesses)
183                    let text = std::fs::read_to_string(&file).map_err(Error::Io)?;
184                    format::table_auto(text.trim())
185                }
186                None if self.options.ignore_unknown_ext => continue,
187                None => {
188                    return Err(Error::Parse {
189                        path: file,
190                        message: "no active format claims this file's extension".into(),
191                    });
192                }
193            };
194            if matches!(value, Value::Null) {
195                continue; // empty file contributes nothing
196            }
197            let mut value = Value::Object(BTreeMap::from([(file_stem_key(&name), value)]));
198            for key in prefix.into_iter().rev() {
199                value = Value::Object(BTreeMap::from([(key, value)]));
200            }
201            self.merge(root, value, &SourceRef::File(file));
202        }
203        Ok(())
204    }
205}
206
207/// Tree-mode key of a file: its name without the extension. A hidden file
208/// whose whole name is its extension (`.env`) keeps the full name.
209#[cfg(feature = "tree")]
210fn file_stem_key(name: &str) -> String {
211    let hidden = name.starts_with('.');
212    let body = if hidden { &name[1..] } else { name };
213    match body.rfind('.') {
214        Some(i) => format!("{}{}", if hidden { "." } else { "" }, &body[..i]),
215        None => name.to_owned(),
216    }
217}
218
219/// All files under `dir` in [`Options::order`], recursing into every
220/// subfolder, each with the folder names leading to it.
221#[cfg(feature = "tree")]
222fn walk_tree(
223    dir: &Path,
224    prefix: Vec<String>,
225    options: &Options,
226    out: &mut Vec<(PathBuf, Vec<String>)>,
227) -> Result<()> {
228    let mut entries = read_entries(dir)?;
229    sort_entries(&mut entries, options.order);
230    for (name, path, is_dir) in entries {
231        if is_dir {
232            let mut prefix = prefix.clone();
233            prefix.push(name);
234            walk_tree(&path, prefix, options, out)?;
235        } else {
236            out.push((path, prefix.clone()));
237        }
238    }
239    Ok(())
240}
241
242/// What an extension resolves to: a built-in format, or a custom entry of
243/// [`Options::formats`] (by index).
244#[derive(Clone, Copy)]
245enum Claim {
246    Builtin(Format),
247    Custom(usize),
248}
249
250/// The extension→parser mapping of [`Options::formats`]: lowercased
251/// extension, last claimer wins — built-in and custom entries follow the
252/// same rule.
253fn extension_map(options: &Options) -> Vec<(String, Claim)> {
254    let mut map: Vec<(String, Claim)> = Vec::new();
255    for (index, spec) in options.formats.iter().enumerate() {
256        let claim = match &spec.format {
257            FormatKind::Builtin(format) => Claim::Builtin(*format),
258            FormatKind::Custom(_) => Claim::Custom(index),
259        };
260        for ext in &spec.extensions {
261            let ext = ext.to_lowercase();
262            map.retain(|(e, _)| *e != ext);
263            map.push((ext, claim));
264        }
265    }
266    map
267}
268
269/// The extension of a file name, lowercased. A hidden file `.X` counts as
270/// having extension `X` (that is how `.env` matches `env`).
271fn file_extension(name: &str) -> Option<String> {
272    let hidden = name.starts_with('.');
273    let stem = if hidden { &name[1..] } else { name };
274    match stem.rfind('.') {
275        Some(i) => Some(stem[i + 1..].to_lowercase()),
276        None if hidden && !stem.is_empty() => Some(stem.to_lowercase()),
277        None => None,
278    }
279}
280
281fn claimed_format(path: &Path, extensions: &[(String, Claim)]) -> Option<Claim> {
282    let name = path.file_name()?.to_str()?;
283    let ext = file_extension(name)?;
284    extensions
285        .iter()
286        .find(|(e, _)| *e == ext)
287        .map(|(_, claim)| *claim)
288}
289
290/// A directory's entries as `(name, path, is_dir)`.
291fn read_entries(dir: &Path) -> Result<Vec<(String, PathBuf, bool)>> {
292    let mut entries = Vec::new();
293    for entry in std::fs::read_dir(dir).map_err(Error::Io)? {
294        let entry = entry.map_err(Error::Io)?;
295        let path = entry.path();
296        let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
297            continue;
298        };
299        entries.push((name.to_owned(), path.clone(), path.is_dir()));
300    }
301    Ok(entries)
302}
303
304fn sort_entries(entries: &mut [(String, PathBuf, bool)], order: Order) {
305    match order {
306        Order::FoldersFirstAlphabetic => entries.sort_by(|a, b| (!a.2, &a.0).cmp(&(!b.2, &b.0))),
307        Order::Alphabetic => entries.sort_by(|a, b| a.0.cmp(&b.0)),
308        Order::ReverseAlphabetic => entries.sort_by(|a, b| b.0.cmp(&a.0)),
309    }
310}
311
312/// Files of a folder in load order, each with the subfolder keys leading
313/// to it (empty unless recursive nesting applies).
314fn scan_folder(dir: &Path, options: &Options) -> Result<Vec<(PathBuf, Vec<String>)>> {
315    let mut files = Vec::new();
316    walk(dir, Vec::new(), options, &mut files)?;
317    Ok(files)
318}
319
320fn walk(
321    dir: &Path,
322    prefix: Vec<String>,
323    options: &Options,
324    out: &mut Vec<(PathBuf, Vec<String>)>,
325) -> Result<()> {
326    let mut entries = read_entries(dir)?;
327    sort_entries(&mut entries, options.order);
328    for (name, path, is_dir) in entries {
329        if is_dir {
330            if options.recursive {
331                let mut prefix = prefix.clone();
332                if !options.flat {
333                    prefix.push(name);
334                }
335                walk(&path, prefix, options, out)?;
336            }
337        } else {
338            out.push((path, prefix.clone()));
339        }
340    }
341    Ok(())
342}
343
344/// Deep-merge `value` (labeled with `source`) into the traced tree:
345/// objects merge recursively, everything else replaces.
346fn merge_traced(target: &mut TracedValue, value: Value, source: &SourceRef, lowercase: bool) {
347    match (target, value) {
348        (TracedValue::Object(entries), Value::Object(incoming)) => {
349            for (key, value) in incoming {
350                let key = if lowercase { key.to_lowercase() } else { key };
351                match entries.get_mut(&key) {
352                    Some(slot) => merge_traced(slot, value, source, lowercase),
353                    None => {
354                        entries.insert(key, to_traced(value, source, lowercase));
355                    }
356                }
357            }
358        }
359        (slot, value) => *slot = to_traced(value, source, lowercase),
360    }
361}
362
363fn to_traced(value: Value, source: &SourceRef, lowercase: bool) -> TracedValue {
364    match value {
365        Value::Object(map) => TracedValue::Object(
366            map.into_iter()
367                .map(|(key, value)| {
368                    let key = if lowercase { key.to_lowercase() } else { key };
369                    (key, to_traced(value, source, lowercase))
370                })
371                .collect(),
372        ),
373        other => TracedValue::Leaf {
374            value: other,
375            source: source.clone(),
376        },
377    }
378}
379
380fn untrace(traced: TracedValue) -> Value {
381    match traced {
382        TracedValue::Leaf { value, .. } => value,
383        TracedValue::Object(entries) => {
384            Value::Object(entries.into_iter().map(|(k, v)| (k, untrace(v))).collect())
385        }
386    }
387}