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