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