Skip to main content

c4/
lib.rs

1//! Load a folder of config files into one deep-merged [`Value`].
2//!
3//! `README.md` is the user-facing overview and `CLAUDE.md` the complete
4//! spec; the README examples are mirrored here as doc tests. Examples
5//! that read the caller's working directory (`./config`, `/etc/myapp`)
6//! are `no_run` — they compile but depend on the user's filesystem; the
7//! [`CustomFormat`] example is fully runnable via a string source.
8//!
9//! Simplest form — one generic [`load`] taking the path of a folder (or
10//! a single file), default options (formats: jsonc + yaml). The
11//! annotated target type decides whether you get a dynamic [`Value`] or
12//! your own struct:
13//!
14//! ```no_run
15//! # fn main() -> Result<(), c4::Error> {
16//! let value: c4::Value = c4::load("config")?;
17//! # Ok(())
18//! # }
19//! ```
20//!
21//! Advanced — explicit sources (later overrides earlier) and options:
22//!
23//! ```no_run
24//! use std::path::Path;
25//!
26//! use c4::{Format, Loader, Options, Source};
27//!
28//! # fn main() -> Result<(), c4::Error> {
29//! let value: c4::Value = Loader::new(Options {
30//!         sources: vec![
31//!             Source::folder("./config"),
32//!             Source::folder(Path::new("/etc/myapp")), // any path-like type
33//!             Source::file("./local.yml"),
34//!             Source::string(Format::Jsonc, r#"{ "debug": true }"#),
35//!         ],
36//!         recursive: true,
37//!         formats: vec![
38//!             "jsonc".into(),                              // format id, default extensions
39//!             Format::Toml.into(),                         // enum form, default extensions
40//!             (Format::Yaml, ["yml", "yaml", "conf"]).into(), // custom extensions
41//!             ("jsonc", ["json", "jsonc"]).into(),         // string id + custom extensions
42//!         ],
43//!         ..Options::default()
44//!     })
45//!     .load()?;
46//! # Ok(())
47//! # }
48//! ```
49
50#[cfg(not(any(
51    feature = "json",
52    feature = "jsonc",
53    feature = "yaml",
54    feature = "toml",
55    feature = "ini",
56    feature = "env",
57    feature = "csv"
58)))]
59compile_error!("c4: enable at least one format feature (json, jsonc, yaml, toml, ini, env, csv)");
60
61mod de;
62mod error;
63mod format;
64mod loader;
65mod options;
66mod ser;
67mod source;
68mod trace;
69pub(crate) mod valid;
70mod value;
71
72pub use error::{Error, Result};
73pub use loader::Loader;
74pub use options::{
75    CustomFormat, Format, FormatKind, FormatSpec, Options, Order, TableColumns, TableOptions,
76    TableTypes,
77};
78pub use source::Source;
79pub use trace::{SourceRef, TracedValue};
80pub use value::Value;
81
82use std::path::{Path, PathBuf};
83
84use serde::de::DeserializeOwned;
85
86/// Load one path with default options — the shortest way in. An
87/// existing file loads as a single file source; anything else is
88/// treated as a folder (a missing path is [`Error::NotFound`]). The
89/// annotated target type decides what you get back:
90///
91/// ```no_run
92/// #[derive(serde::Deserialize)]
93/// struct MyConfig {
94///     host: String,
95///     port: u16,
96/// }
97///
98/// # fn main() -> Result<(), c4::Error> {
99/// let value: c4::Value = c4::load("config")?;   // a folder …
100/// let value: c4::Value = c4::load("app.yml")?;  // … or one file
101/// let cfg: MyConfig = c4::load("config")?;
102/// # Ok(())
103/// # }
104/// ```
105pub fn load<T: DeserializeOwned>(path: impl Into<PathBuf>) -> Result<T> {
106    let path = path.into();
107    let source = if path.is_file() {
108        Source::File(path)
109    } else {
110        Source::Folder(path)
111    };
112    Loader::new(Options {
113        sources: vec![source],
114        ..Options::default()
115    })
116    .load()
117}
118
119/// The generic table stage: interpret a plain row table
120/// (`[[key, value, format], …]`) with the `options.table` semantics — the
121/// same stage the csv format feeds. Public so custom table-shaped formats
122/// (spreadsheets, markdown tables, …) can lower their file into rows and
123/// reuse it; `path` labels errors.
124pub fn parse_table(rows: Vec<Vec<String>>, path: &Path, options: &Options) -> Result<Value> {
125    format::table::parse(rows, path, options)
126}