Expand description
Format-preserving merge of a person’s TOML configuration with the documented defaults an application ships.
The crate documentation is the README, so its examples are compiled and run
with the rest of the tests. doc/design.md states the merge rules and
corpus/ holds the output they produce, which is where the behaviour is
specified.
§documented-toml
Merge new TOML defaults into a user’s configuration while preserving their values, comments, ordering, formatting, and line endings.
Defaults are named for their chief property: someone will change them.
§Install
cargo add documented-toml # library
cargo install documented-toml # command§Comment markers
##: Application documentation.
#: timeout = 30
# The staging server is slow.
timeout = 120##:marks prose owned by the application.#:marks TOML owned by the application: a shipped default or an optional setting.- Ordinary
#comments belong to the user.
Application-owned lines are refreshed from the defaults on every merge. User comments retain their indentation and paragraph breaks. Both markers are configurable.
Sections are separated by a blank line before their documentation or header. Existing blank lines are preserved; when the user supplies none above a key, the spacing from the defaults is used.
§Example
Defaults:
##: Request timeout in seconds.
timeout = 30
##: Where logs are written. An empty path means stderr.
log = ""
##: Maximum cache entries.
#: cache_size = 4096User configuration:
# The staging server is slow.
timeout = 120Result:
##: Request timeout in seconds.
#: timeout = 30
# The staging server is slow.
timeout = 120
##: Where logs are written. An empty path means stderr.
#: log = ""
##: Maximum cache entries.
#: cache_size = 4096The file holds what the user set. Everything else is a #: line, so the
shipped value is visible without the file claiming they chose it. A section
keeps its [table] header, so setting one of its keys is uncommenting one
line. Ask
Merged::user_set("log") which values are theirs, and take the rest from the
defaults you passed in.
MergeOptions::defaults_commented(false) (--live-defaults) writes every
default as a live key instead, which makes the merged document the effective
configuration and makes user_set tell you nothing.
§Library
let merged = documented_toml::merge(default_src, user_src)?;
let text = merged.to_toml_string();Custom markers and renamed keys use MergeOptions:
use documented_toml::MergeOptions;
let merged = MergeOptions::new()
.markers("#|", "#=")
.migrate("server.timeout", "network.timeout")
.merge(default_src, user_src)?;A migration runs when the old path exists and the new path does not. It moves the value and its user comments.
The = of keys on consecutive lines is lined up. A comment or blank line
starts a new group, and a key alone in its group gets one space. A value written over several lines keeps its own
spacing and sets no width. align_values(false) keeps the spacing as the
person wrote it.
Each merge includes a Report:
UnknownKey: warning; the value remains.TypeMismatch: error; the value remains as written.Migrated: warning naming the old path.
Use merged.document() to borrow the resulting toml_edit::DocumentMut, or
merged.into_document() to take it for deserialization. merged.newline()
reports the selected line ending.
§Defaults and what the user chose
A default nobody set is a #: line, not a key, so the merged document holds
the user’s choices and nothing else:
let merged = documented_toml::merge(default_src, user_src)?;
assert!(merged.user_set("count"));
assert!(!merged.user_set("limit"));So the values come from two places: the defaults you passed in, overlaid by the merged document. Keep the defaults in TOML files of their own if you want them per platform, compose them, and pass the composed text to both steps.
set writes a value into the file where the defaults say it goes, turning a
#: line into a live key under it:
let mut merged = documented_toml::merge(default_src, "")?;
merged.set("limit", 50)?;
assert_eq!(
merged.to_toml_string(),
"##: How many.\n#: count = 1\n#: limit = 10\nlimit = 50\n"
);It merges again, so the report afterwards describes the file as it now stands.
§Command line
documented-toml merge --default D.toml --user U.toml [--in-place | --output OUT]
[--no-align] [--live-defaults]
documented-toml check --default D.toml --user U.tomlmerge writes to stdout unless given --output or --in-place. check writes
no document. Both commands print diagnostics to stderr and return a non-zero
status for errors. --no-align keeps the spacing around = as the person
wrote it. --live-defaults writes a default nobody set as a key rather than a
#: line.
--in-place writes and syncs a sibling temporary file before renaming it over
the user file.
§Limits
- Arrays and arrays of tables are replaced whole.
- Validation checks TOML types, accepting integer values for float defaults. Float values for integer defaults remain errors. There is no schema language.
- User edits to
##:and#:lines are replaced by the next merge. - Optional defaults must appear in their
#:line. Clairvoyance is outside the public API.
§Specification
doc/design.md defines the merge rules. corpus/
contains byte-for-byte examples and idempotence cases.
§License
X11. See LICENSE.
Re-exports§
pub use decor::DEFAULT_PROSE_MARKER;pub use decor::DEFAULT_SAMPLE_MARKER;pub use decor::DefaultEcho;pub use decor::DocBlock;pub use decor::Marker;pub use decor::Prefix;pub use decor::PrefixLine;pub use decor::Sample;pub use error::Error;pub use merge::MergeEngine;pub use merge::Merged;pub use merge::Newline;pub use options::MergeOptions;pub use options::Migration;pub use path::DottedPath;pub use report::Diagnostic;pub use report::DiagnosticKind;pub use report::Position;pub use report::Report;pub use report::Severity;pub use report::Span;pub use report::SpanIndex;pub use report::TomlType;pub use source::SourceDocument;pub use template::Template;
Modules§
- decor
- Classification and reassembly of the text above a key.
- error
- Failures that stop a merge before it starts.
- merge
- The merge itself: what runs it, and what comes out.
- options
- What the caller configures before a merge.
- path
- Key paths.
- report
- What the merge noticed on the way through.
- source
- Input documents, before the merge walks them.
- template
- The keys the defaults document without declaring.
Functions§
- merge
- Merges a user document against the defaults with the default marker and no
rename rules. See
MergeOptionsfor the configurable form.