knf/
lib.rs

1//! Load, merge and emit layered JSON and TOML configuration.
2//!
3//! Three steps, each a function, and a caller composes them:
4//!
5//! 1. [`load_layers`] reads each path into a [`Value`], keeping the format it
6//!    was read as;
7//! 2. [`merge`] folds the flat layer list from left to right — any in-memory
8//!    overlays are just more layers appended to the list;
9//! 3. [`interpolate`], if wanted, resolves `${...}` references once, on the
10//!    merged document.
11//!
12//! [`format::emit`] renders the result. JSON and TOML appear only in
13//! [`format`](mod@format) and [`value`]; the merge and interpolation never learn either
14//! exists.
15//!
16//! No flag names. An error from this crate carries key paths and file paths;
17//! the command-line spelling that produced it is `knf-cli`'s to add. That is
18//! what [`LoadError`] exists for — the failures that have an obvious
19//! command-line remedy are typed, so the caller decides how to name them.
20
21pub mod format;
22mod interp;
23mod ir;
24mod merge;
25mod path;
26mod set;
27pub mod value;
28
29mod env;
30
31use std::io::Read;
32use std::path::{Path, PathBuf};
33
34use anyhow::Context;
35
36pub use env::ProcessEnv;
37pub use format::Format;
38pub use interp::{Cycle, Env, EnvValue, InterpError, Problem, Syntax, interpolate};
39pub use ir::{Map, Number, Value};
40pub use merge::{MergeError, MergeOptions, merge, merge_into};
41pub use path::{PathError, RefPath, Seg, render_path};
42pub use set::{PathLeaf, json_or_string};
43pub use value::{BadDatetime, IntegerOutOfRange, NonFiniteFloat, NullInToml, TomlError};
44
45use format::SourceName;
46
47/// The positional that means "read stdin".
48pub const STDIN: &str = "-";
49
50/// Why a positional could not be turned into a layer.
51///
52/// Carries paths and nothing else. Each of these has an obvious command-line
53/// remedy and no library-level one, which is exactly why the remedy is not
54/// spelled here: `knf-cli` matches on the variant and adds the flag.
55#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
56pub enum LoadError {
57    /// `-` was given without an explicit input format.
58    #[error("`-` reads stdin, which has no extension")]
59    StdinNeedsFormat,
60    /// A positional named a directory.
61    #[error("`{}` is a directory; knf takes files as layers", path.display())]
62    Directory {
63        /// The directory that was named.
64        path: PathBuf,
65    },
66    /// A positional's extension is neither `json` nor `toml`.
67    #[error("cannot infer a format from `{}`", path.display())]
68    UnknownExtension {
69        /// The file whose extension said nothing.
70        path: PathBuf,
71    },
72}
73
74impl LoadError {
75    /// The path this failed on, or `None` for stdin.
76    pub fn path(&self) -> Option<&Path> {
77        match self {
78            Self::StdinNeedsFormat => None,
79            Self::Directory { path } | Self::UnknownExtension { path } => Some(path),
80        }
81    }
82}
83
84/// Reads and parses every positional into the merge IR, keeping the format each
85/// input was read as.
86///
87/// A path equal to [`STDIN`] reads standard input and therefore requires an
88/// explicit `input_format`; otherwise the format is inferred from the extension
89/// unless `input_format` overrides it. JSON and TOML may be mixed.
90///
91/// The formats are returned because a caller may have a decision to make before
92/// the fold, and they are the input to it: `knf-cli` resolves the
93/// *output* format here. A missing `-f` is a mistake in argv alone, and
94/// reporting it must not wait behind a merge conflict the user would otherwise
95/// fix first, only to learn about the flag on the next run.
96pub fn load_layers<P: AsRef<Path>>(
97    paths: &[P],
98    input_format: Option<Format>,
99) -> anyhow::Result<(Vec<Value>, Vec<Format>)> {
100    let mut layers: Vec<Value> = Vec::with_capacity(paths.len());
101    let mut input_formats: Vec<Format> = Vec::with_capacity(paths.len());
102
103    for path in paths {
104        let (name, format, text) = read_input(path.as_ref(), input_format)?;
105        let value = format::parse(format, &text, &name)?;
106        input_formats.push(format);
107        layers.push(value);
108    }
109    Ok((layers, input_formats))
110}
111
112/// Reads one positional, resolving its format.
113fn read_input(
114    path: &Path,
115    override_format: Option<Format>,
116) -> anyhow::Result<(SourceName, Format, String)> {
117    if path.as_os_str() == STDIN {
118        let format = override_format.ok_or(LoadError::StdinNeedsFormat)?;
119        let mut text = String::new();
120        std::io::stdin()
121            .read_to_string(&mut text)
122            .context("reading stdin")?;
123        return Ok((SourceName::Stdin, format, text));
124    }
125
126    if path.is_dir() {
127        return Err(LoadError::Directory {
128            path: path.to_path_buf(),
129        }
130        .into());
131    }
132
133    let format = match override_format {
134        Some(format) => format,
135        None => Format::from_path(path).ok_or_else(|| LoadError::UnknownExtension {
136            path: path.to_path_buf(),
137        })?,
138    };
139    let text =
140        std::fs::read_to_string(path).with_context(|| format!("reading `{}`", path.display()))?;
141    Ok((SourceName::File(path.to_path_buf()), format, text))
142}
knf/lib.rs

knf/
lib.rs
