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}