pub struct Options {Show 13 fields
pub sources: Vec<Source>,
pub formats: Vec<FormatSpec>,
pub dir_depth: isize,
pub filename_as_key: bool,
pub dirname_as_key: bool,
pub dot_key: bool,
pub case_sensitive: bool,
pub order: Order,
pub sheetname_as_key: bool,
pub auto_no_ext_files: bool,
pub ignore_unknown_ext: bool,
pub ignore_commented_sheets: bool,
pub ignore_hidden_sheets: bool,
}Expand description
All loader options.
Plain data on purpose: set the fields you care about and take the rest
from ..Options::default().
Fields§
§sources: Vec<Source>The ordered config sources; later sources override earlier ones.
Default: the config folder under the current working directory.
Every element converts with .into() — see Source for all
the accepted shapes.
let value: c4::Value = c4::Loader::new(c4::Options {
sources: vec![
"./config".into(), // a folder …
"./local.yml".into(), // … or a single file
("yaml", "debug: true").into(), // in-code text
(std::collections::BTreeMap::from([("port", 8080)]),).into(),
],
..c4::Options::default()
})
.load()?;formats: Vec<FormatSpec>Which formats to read and which extensions each one claims. The
list carries no override-order semantics — it only builds the
extension→format mapping (if several entries claim the same
extension, the last entry wins the claim). Override order between
files is decided by filename alone; see the merge rules in
README.md. Entry forms are on FormatSpec.
let options = c4::Options {
formats: vec![
"jsonc".into(), // default extensions
(c4::Format::Yaml, ["yml", "yaml", "conf"]).into(), // custom extensions
(c4::Format::Csv, ["csv"], "db").into(), // + a table layout
],
..c4::Options::default()
};
assert_eq!(options.formats.len(), 3);dir_depth: isizeFolder sources. How many subdirectory levels below the source
folder to scan. 1 (default): the source folder’s own files and
one level of subfolders — config/* and config/a/*, but not
config/a/b/*. 0: only the source folder’s own files. -1:
unlimited (fully recursive). Whether the folders that are scanned
contribute their names as keys is dirname_as_key.
(The tree feature changes this field’s default to -1 — see the
feature.)
// config/*, config/a/* and config/a/b/* all merge in
let value: c4::Value = c4::Loader::new(c4::Options {
dir_depth: -1, // fully recursive
..c4::Options::default()
})
.load()?;filename_as_key: boolFolder sources. When true, each file becomes a key named
after the file with its extension stripped, holding that file’s
parsed content, instead of merging into the parent — a.json = {"c": 1} loads as {a: {c: 1}}. Default false (the tree
feature changes this default to true — see the feature). Combine
with dirname_as_key and dir_depth: -1 for a full folder-shaped tree. A dotfile whose whole name is
its extension (.env) keeps the full name as its key.
This is also the switch that decides how extension-less and
unknown-extension files are handled (see
auto_no_ext_files and
ignore_unknown_ext): those only
apply when a file would become a key. Otherwise such files are
skipped (they have no key to contribute under).
// config/a.json = {"c": 1} -> {a: {c: 1}}
let value: c4::Value = c4::Loader::new(c4::Options {
filename_as_key: true,
..c4::Options::default()
})
.load()?;
assert_eq!(value["a"]["c"].as_i64(), Some(1));dirname_as_key: boolFolder sources. When true, each subfolder becomes a key
and everything under it merges below that key — db/a.json = {"host": "x"} loads as {db: {host: "x"}}. Default false (the
tree feature changes this default to true — see the feature).
Honors dir_depth: only folders actually
scanned become keys.
// config/db/a.json = {"host": "x"} — the subfolder becomes a key
let value: c4::Value = c4::Loader::new(c4::Options {
dirname_as_key: true,
..c4::Options::default()
})
.load()?;
assert_eq!(value["db"]["host"].as_str(), Some("x"));dot_key: boolAll modes; env and table formats. Treat dotted keys as nested
paths: a.b.c becomes { "a": { "b": { "c": … } } }.
Default true.
In the table stage this applies to both layouts: the kv
layout’s key column, and the db layout’s key row (a dotted
column nests inside each record).
A key segment may also end in array suffixes — [] (append)
and [<int>] (index) groups, chained for nested arrays
(grid[0][1], one level per group); any other bracket shape
(a[x], a[-1], a[]b, a bare []) keeps the whole segment a
literal key:
name[]appends one new element per occurrence: per kv row / env line, and per record for a db column.name[<int>]addresses element<int>: the same index deep-merges into one element and indexes may arrive in any order. Skipped indexes leaveNullgaps —a[1]+a[4]give a five-element array with nulls at 0, 2 and 3; deserialize such arrays asVec<Option<T>>.
Suffixes also chain through the dotted path (a[0].b[].c) and
work on keys without dots (ports[]). The expansion happens
within one parse (one file/sheet/string source) — across sources
arrays still replace like any array. The dot-key example tours
all of it.
use std::path::Path;
use c4::{Options, TableLayout};
let options = Options::default(); // dot_key: true
// kv layout: the key column nests
let rows = vec![vec!["a.b".to_string(), "1".to_string()]];
let value = c4::parse_table(rows, &TableLayout::Kv, Path::new("doc"), &options)?;
assert_eq!(value["a"]["b"].as_i64(), Some(1));
// db layout: dotted keys nest inside each record
let rows = vec![
vec!["a.b".to_string(), "a.c".to_string()], // key row
vec![String::new(), String::new()], // type row (all auto)
vec!["1".to_string(), "2".to_string()], // one record
];
let value = c4::parse_table(rows, &TableLayout::Db, Path::new("doc"), &options)?;
assert_eq!(value[0]["a"]["b"].as_i64(), Some(1));
assert_eq!(value[0]["a"]["c"].as_i64(), Some(2));
// array suffixes: `[]` appends per row, `[<int>]` indexes
let rows = vec![
vec!["tags[]".to_string(), "red".to_string()],
vec!["tags[]".to_string(), "blue".to_string()],
vec!["servers[1].host".to_string(), "beta".to_string()],
vec!["servers[0].host".to_string(), "alpha".to_string()],
];
let value = c4::parse_table(rows, &TableLayout::Kv, Path::new("doc"), &options)?;
assert_eq!(value["tags"][1].as_str(), Some("blue"));
assert_eq!(value["servers"][0]["host"].as_str(), Some("alpha"));
// chained suffixes nest; skipped indexes leave null gaps
let rows = vec![vec!["m[1][0]".to_string(), "9".to_string()]];
let value = c4::parse_table(rows, &TableLayout::Kv, Path::new("doc"), &options)?;
assert!(value["m"][0].is_null());
assert_eq!(value["m"][1][0].as_i64(), Some(9));case_sensitive: boolAll modes. Case-sensitive key merging. Default true; when
false, keys are normalized to lowercase. (File-extension
matching is always case-insensitive and unrelated to this
option.)
use std::collections::BTreeMap;
let value: c4::Value = c4::Loader::new(c4::Options {
sources: vec![
(BTreeMap::from([("PORT", 1)]),).into(),
(BTreeMap::from([("port", 8080)]),).into(),
],
case_sensitive: false, // "PORT" and "port" are one key
..c4::Options::default()
})
.load()?;
assert_eq!(value["port"].as_i64(), Some(8080));order: OrderAll modes; folder sources. Load order inside a folder. In
merge mode it decides which file overrides which; in tree mode it
decides key collisions (a.yml vs a folder a/).
let value: c4::Value = c4::Loader::new(c4::Options {
order: "alphabetic".into(), // or c4::Order::Alphabetic
..c4::Options::default()
})
.load()?;sheetname_as_key: boolSpreadsheet formats (excel/ods) only. Treats each sheet of a
workbook like a file. When true, a workbook parses to an object
keyed by sheet name (every sheet left after the ignore filters
becomes a key) — the sheet analogue of
filename_as_key. When false
(default), every non-ignored sheet still parses, but they all
deep-merge into one value (like several files in a folder), in
order applied to the sheet names — so later
sheets override earlier ones. Default false (the tree feature
changes this default to true — see the feature). (A table source
that names a sheet explicitly is unaffected — it always reads
exactly that sheet.)
// game.xlsx has sheets "items" and "monsters" — each becomes a key
let value: c4::Value = c4::Loader::new(c4::Options {
sources: vec!["./game.xlsx".into()],
sheetname_as_key: true,
..c4::Options::default()
})
.load()?;
assert!(!value["items"].is_null());auto_no_ext_files: boolOnly when filename_as_key is true
(files become keys); folder sources. What to do with a file that
has no extension. true (default): read it and guess the type of
its (trimmed) content with the table auto rules — a file
containing 1.1.1.1 becomes an IPv4 value when the ipv4 feature
is on, a string otherwise. false: treat it like a file with an
unknown extension (see
ignore_unknown_ext). (Named
auto_no_ext_files after the table auto type id it reuses.)
Without filename_as_key an extension-less file has no key to
contribute under and is skipped regardless.
// config/host is an extension-less file holding "1.1.1.1"
let value: c4::Value = c4::Loader::new(c4::Options {
filename_as_key: true,
auto_no_ext_files: true,
..c4::Options::default()
})
.load()?;
assert!(!value["host"].is_null());ignore_unknown_ext: boolOnly when filename_as_key is true
(files become keys); folder sources. What to do with a file whose
extension no active format claims: skip it (true, default) or
fail the load with Error::Parse (false). Without
filename_as_key such files are always skipped.
let value: c4::Value = c4::Loader::new(c4::Options {
filename_as_key: true,
ignore_unknown_ext: false, // a config/*.xyz file now errors
..c4::Options::default()
})
.load()?;ignore_commented_sheets: boolSpreadsheet formats (excel/ods) only. Skip sheets whose name
starts with #, . or _ — draft/scratch space next to live
config, read like a “commented-out” sheet. Default true. (A
table source that names a sheet explicitly bypasses this filter, so
a prefixed sheet stays loadable on purpose.)
// game.xlsx has sheets "items" and "_draft"; by default "_draft"
// is skipped — false reads it as a key too
let value: c4::Value = c4::Loader::new(c4::Options {
sources: vec!["./game.xlsx".into()],
sheetname_as_key: true,
ignore_commented_sheets: false,
..c4::Options::default()
})
.load()?;
assert!(!value["_draft"].is_null());Spreadsheet formats (excel/ods) only. Skip sheets marked
hidden in the workbook (Excel hidden/veryHidden, OpenDocument
table:display="false"). Default true. (A table source that
names a sheet explicitly bypasses this filter.)
// the workbook's `config` sheet is marked hidden — read it anyway
let value: c4::Value = c4::Loader::new(c4::Options {
sources: vec!["./game.xlsx".into()],
ignore_hidden_sheets: false,
..c4::Options::default()
})
.load()?;