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, 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![(kv, "port=8080").into()],
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                // one path source: a folder whose files merge, or a single
74                // file — detected here (same rule as `c4::load`)
75                Source::Path(path) if path.is_dir() => {
76                    if self.options.tree {
77                        #[cfg(feature = "tree")]
78                        self.merge_tree_folder(path, &extensions, &mut root)?;
79                        #[cfg(not(feature = "tree"))]
80                        return Err(Error::Unsupported(
81                            "Options.tree requires the `tree` Cargo feature".into(),
82                        ));
83                    } else {
84                        for (file, prefix) in scan_folder(path, &self.options)? {
85                            let Some(claim) = claimed_format(&file, &extensions) else {
86                                continue; // no active format claims this extension
87                            };
88                            let mut value = self.parse_file(claim, &file)?;
89                            if matches!(value, Value::Null) {
90                                continue; // empty file contributes nothing
91                            }
92                            for key in prefix.into_iter().rev() {
93                                value = Value::Object(BTreeMap::from([(key, value)]));
94                            }
95                            self.merge(&mut root, value, &SourceRef::File(file));
96                        }
97                    }
98                }
99                Source::Path(path) if path.is_file() => {
100                    let claim = claimed_format(path, &extensions).ok_or_else(|| Error::Parse {
101                        path: path.clone(),
102                        message: "no active format claims this file's extension".into(),
103                    })?;
104                    let value = self.parse_file(claim, path)?;
105                    if !matches!(value, Value::Null) {
106                        self.merge(&mut root, value, &SourceRef::File(path.clone()));
107                    }
108                }
109                Source::Path(path) => return Err(Error::NotFound(path.clone())),
110                Source::Value(result) => {
111                    let value = result.clone().map_err(|message| Error::Parse {
112                        path: PathBuf::from(format!("value:{index}")),
113                        message,
114                    })?;
115                    if !matches!(value, Value::Null) {
116                        self.merge(&mut root, value, &SourceRef::Value(index));
117                    }
118                }
119                Source::String { format, content } => {
120                    let label = PathBuf::from(format!("string:{index}"));
121                    let value = match format {
122                        FormatKind::Builtin(format) => {
123                            format::parse(*format, content, &label, &self.options)?
124                        }
125                        FormatKind::Custom(custom) => {
126                            (custom.parser)(content, &label, &self.options)?
127                        }
128                    };
129                    if !matches!(value, Value::Null) {
130                        self.merge(&mut root, value, &SourceRef::String(index));
131                    }
132                }
133            }
134        }
135        Ok(root)
136    }
137
138    fn parse_file(&self, claim: Claim, path: &Path) -> Result<Value> {
139        let text = std::fs::read_to_string(path).map_err(Error::Io)?;
140        match claim {
141            Claim::Builtin(format) => format::parse(format, &text, path, &self.options),
142            Claim::Custom(index) => {
143                let FormatKind::Custom(custom) = &self.options.formats[index].format else {
144                    unreachable!("custom claims always index custom entries");
145                };
146                (custom.parser)(&text, path, &self.options)
147            }
148        }
149    }
150
151    fn merge(&self, target: &mut TracedValue, value: Value, source: &SourceRef) {
152        merge_traced(target, value, source, !self.options.case_sensitive);
153    }
154
155    /// Tree mode: every subfolder is a key, every file is a key named
156    /// after the file (extension stripped) holding its parsed content.
157    /// Entries load in [`Options::order`]; key collisions (`a.json` +
158    /// `a.yml`, or a file next to a same-named folder) deep-merge as
159    /// usual, so the order decides who wins.
160    #[cfg(feature = "tree")]
161    fn merge_tree_folder(
162        &self,
163        folder: &Path,
164        extensions: &[(String, Claim)],
165        root: &mut TracedValue,
166    ) -> Result<()> {
167        let mut files = Vec::new();
168        walk_tree(folder, Vec::new(), &self.options, &mut files)?;
169        for (file, prefix) in files {
170            let name = file
171                .file_name()
172                .and_then(|n| n.to_str())
173                .unwrap_or_default()
174                .to_owned();
175            let value = match claimed_format(&file, extensions) {
176                Some(claim) => self.parse_file(claim, &file)?,
177                None if file_extension(&name).is_none() && self.options.auto_files => {
178                    // extensionless: the trimmed content goes through the
179                    // table auto detection (same feature-gated guesses)
180                    let text = std::fs::read_to_string(&file).map_err(Error::Io)?;
181                    format::table_auto(text.trim())
182                }
183                None if self.options.ignore_unknown_ext => continue,
184                None => {
185                    return Err(Error::Parse {
186                        path: file,
187                        message: "no active format claims this file's extension".into(),
188                    });
189                }
190            };
191            if matches!(value, Value::Null) {
192                continue; // empty file contributes nothing
193            }
194            let mut value = Value::Object(BTreeMap::from([(file_stem_key(&name), value)]));
195            for key in prefix.into_iter().rev() {
196                value = Value::Object(BTreeMap::from([(key, value)]));
197            }
198            self.merge(root, value, &SourceRef::File(file));
199        }
200        Ok(())
201    }
202}
203
204/// Tree-mode key of a file: its name without the extension. A hidden file
205/// whose whole name is its extension (`.env`) keeps the full name.
206#[cfg(feature = "tree")]
207fn file_stem_key(name: &str) -> String {
208    let hidden = name.starts_with('.');
209    let body = if hidden { &name[1..] } else { name };
210    match body.rfind('.') {
211        Some(i) => format!("{}{}", if hidden { "." } else { "" }, &body[..i]),
212        None => name.to_owned(),
213    }
214}
215
216/// All files under `dir` in [`Options::order`], recursing into every
217/// subfolder, each with the folder names leading to it.
218#[cfg(feature = "tree")]
219fn walk_tree(
220    dir: &Path,
221    prefix: Vec<String>,
222    options: &Options,
223    out: &mut Vec<(PathBuf, Vec<String>)>,
224) -> Result<()> {
225    let mut entries = read_entries(dir)?;
226    sort_entries(&mut entries, options.order);
227    for (name, path, is_dir) in entries {
228        if is_dir {
229            let mut prefix = prefix.clone();
230            prefix.push(name);
231            walk_tree(&path, prefix, options, out)?;
232        } else {
233            out.push((path, prefix.clone()));
234        }
235    }
236    Ok(())
237}
238
239/// What an extension resolves to: a built-in format, or a custom entry of
240/// [`Options::formats`] (by index).
241#[derive(Clone, Copy)]
242enum Claim {
243    Builtin(Format),
244    Custom(usize),
245}
246
247/// The extension→parser mapping of [`Options::formats`]: lowercased
248/// extension, last claimer wins — built-in and custom entries follow the
249/// same rule.
250fn extension_map(options: &Options) -> Vec<(String, Claim)> {
251    let mut map: Vec<(String, Claim)> = Vec::new();
252    for (index, spec) in options.formats.iter().enumerate() {
253        let claim = match &spec.format {
254            FormatKind::Builtin(format) => Claim::Builtin(*format),
255            FormatKind::Custom(_) => Claim::Custom(index),
256        };
257        for ext in &spec.extensions {
258            let ext = ext.to_lowercase();
259            map.retain(|(e, _)| *e != ext);
260            map.push((ext, claim));
261        }
262    }
263    map
264}
265
266/// The extension of a file name, lowercased. A hidden file `.X` counts as
267/// having extension `X` (that is how `.env` matches `env`).
268fn file_extension(name: &str) -> Option<String> {
269    let hidden = name.starts_with('.');
270    let stem = if hidden { &name[1..] } else { name };
271    match stem.rfind('.') {
272        Some(i) => Some(stem[i + 1..].to_lowercase()),
273        None if hidden && !stem.is_empty() => Some(stem.to_lowercase()),
274        None => None,
275    }
276}
277
278fn claimed_format(path: &Path, extensions: &[(String, Claim)]) -> Option<Claim> {
279    let name = path.file_name()?.to_str()?;
280    let ext = file_extension(name)?;
281    extensions
282        .iter()
283        .find(|(e, _)| *e == ext)
284        .map(|(_, claim)| *claim)
285}
286
287/// A directory's entries as `(name, path, is_dir)`.
288fn read_entries(dir: &Path) -> Result<Vec<(String, PathBuf, bool)>> {
289    let mut entries = Vec::new();
290    for entry in std::fs::read_dir(dir).map_err(Error::Io)? {
291        let entry = entry.map_err(Error::Io)?;
292        let path = entry.path();
293        let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
294            continue;
295        };
296        entries.push((name.to_owned(), path.clone(), path.is_dir()));
297    }
298    Ok(entries)
299}
300
301fn sort_entries(entries: &mut [(String, PathBuf, bool)], order: Order) {
302    match order {
303        Order::FoldersFirstAlphabetic => entries.sort_by(|a, b| (!a.2, &a.0).cmp(&(!b.2, &b.0))),
304        Order::Alphabetic => entries.sort_by(|a, b| a.0.cmp(&b.0)),
305        Order::ReverseAlphabetic => entries.sort_by(|a, b| b.0.cmp(&a.0)),
306    }
307}
308
309/// Files of a folder in load order, each with the subfolder keys leading
310/// to it (empty unless recursive nesting applies).
311fn scan_folder(dir: &Path, options: &Options) -> Result<Vec<(PathBuf, Vec<String>)>> {
312    let mut files = Vec::new();
313    walk(dir, Vec::new(), options, &mut files)?;
314    Ok(files)
315}
316
317fn walk(
318    dir: &Path,
319    prefix: Vec<String>,
320    options: &Options,
321    out: &mut Vec<(PathBuf, Vec<String>)>,
322) -> Result<()> {
323    let mut entries = read_entries(dir)?;
324    sort_entries(&mut entries, options.order);
325    for (name, path, is_dir) in entries {
326        if is_dir {
327            if options.recursive {
328                let mut prefix = prefix.clone();
329                if !options.flat {
330                    prefix.push(name);
331                }
332                walk(&path, prefix, options, out)?;
333            }
334        } else {
335            out.push((path, prefix.clone()));
336        }
337    }
338    Ok(())
339}
340
341/// Deep-merge `value` (labeled with `source`) into the traced tree:
342/// objects merge recursively, everything else replaces.
343fn merge_traced(target: &mut TracedValue, value: Value, source: &SourceRef, lowercase: bool) {
344    match (target, value) {
345        (TracedValue::Object(entries), Value::Object(incoming)) => {
346            for (key, value) in incoming {
347                let key = if lowercase { key.to_lowercase() } else { key };
348                match entries.get_mut(&key) {
349                    Some(slot) => merge_traced(slot, value, source, lowercase),
350                    None => {
351                        entries.insert(key, to_traced(value, source, lowercase));
352                    }
353                }
354            }
355        }
356        (slot, value) => *slot = to_traced(value, source, lowercase),
357    }
358}
359
360fn to_traced(value: Value, source: &SourceRef, lowercase: bool) -> TracedValue {
361    match value {
362        Value::Object(map) => TracedValue::Object(
363            map.into_iter()
364                .map(|(key, value)| {
365                    let key = if lowercase { key.to_lowercase() } else { key };
366                    (key, to_traced(value, source, lowercase))
367                })
368                .collect(),
369        ),
370        other => TracedValue::Leaf {
371            value: other,
372            source: source.clone(),
373        },
374    }
375}
376
377fn untrace(traced: TracedValue) -> Value {
378    match traced {
379        TracedValue::Leaf { value, .. } => value,
380        TracedValue::Object(entries) => {
381            Value::Object(entries.into_iter().map(|(k, v)| (k, untrace(v))).collect())
382        }
383    }
384}