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