pub struct Options {Show 16 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_data_keys: bool,
pub ignore_commented_filenames: bool,
pub ignore_commented_dirnames: bool,
pub ignore_commented_sheetnames: 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>>. Every skipped slot is allocated, so a typo must not cost gigabytes: one index may skip at most 10000 unset slots past the array’s current end (a[1],a[100],a[10002]is fine), and no index may exceed 1000000. Either is an error —Error::Tableat its row,Error::Parsenaming the env line or the sheet.
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_data_keys: boolAll modes; every source kind. Drop data keys — the object
keys a source’s own content parses to — that start with a comment
prefix (# or _ — never .): #note, _tmp and their whole
subtrees disappear. Default true.
The filter runs on each parse result — one file, one sheet, one
(format, text) string, one (value,) override — after
dot_key expansion, and reaches every level:
nested objects and objects inside arrays (so a #memo column
vanishes from every record of a db grid). It is deliberately
data keys only: the keys c4 builds from names —
filename_as_key,
dirname_as_key,
sheetname_as_key and the sheet key
of an explicit-sheet table source — are governed by the three
ignore_commented_*name* options below instead. An object left
empty stays an empty object.
use std::collections::BTreeMap;
let value: c4::Value = c4::Loader::new(c4::Options {
sources: vec![(BTreeMap::from([
("port", 8080),
("_scratch", 1), // commented out
]),).into()],
..c4::Options::default() // ignore_commented_data_keys: true
})
.load()?;
assert_eq!(value["port"].as_i64(), Some(8080));
assert!(value["_scratch"].is_null());ignore_commented_filenames: boolAll modes; folder sources. Skip files whose name starts with a
comment prefix (# or _ — never ., so .env still loads):
config/_draft.yml is draft space next to live config. Default
true. The name decides, so this applies whether or not
filename_as_key would key the file.
Naming the file yourself always wins. This filters the folder
scan only: a path source (or c4::load)
pointing straight at config/_draft.yml loads it even with the
option on — you asked for that file by name.
// scanning ./config skips its _draft.yml by default …
let value: c4::Value = c4::load("config")?;
// … but naming the file loads it, option or not
let draft: c4::Value = c4::load("config/_draft.yml")?;
// false merges it in while scanning too
let value: c4::Value = c4::Loader::new(c4::Options {
ignore_commented_filenames: false,
..c4::Options::default()
})
.load()?;ignore_commented_dirnames: boolAll modes; folder sources. Skip subfolders whose name starts
with a comment prefix (# or _ — never .): nothing under
config/_wip/ is scanned, and with
dirname_as_key no key appears for it.
Default true.
Naming the folder yourself always wins — for that folder only.
A path source config/_wip scans _wip itself even with the
option on, but the scan below it filters as usual: a
config/_wip/#deep/ subfolder is still skipped (and its files
still follow
ignore_commented_filenames).
Only the folder you named is exempt, not everything under it.
// scanning ./config skips _wip/ entirely by default …
let value: c4::Value = c4::load("config")?;
// … but naming it scans it — while `_wip/#deep/` inside stays out
let wip: c4::Value = c4::load("config/_wip")?;
// false scans commented subfolders too
let value: c4::Value = c4::Loader::new(c4::Options {
ignore_commented_dirnames: false,
..c4::Options::default()
})
.load()?;ignore_commented_sheetnames: boolSpreadsheet formats (excel/ods) only. Skip sheets whose name
starts with a comment prefix (# or _ — never .) —
draft/scratch space next to live config, read like a
“commented-out” sheet. Default true. The name decides, so the
sheet is skipped in merge mode too (where sheet names are not
keys).
Naming the sheet yourself always wins. This filters the
workbook’s sheet selection only: a
(format, path, sheet, layout) table source reads exactly the
sheet it names — commented or hidden — and merges it under the
sheet name, so a _extra 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_sheetnames: false,
..c4::Options::default()
})
.load()?;
assert!(!value["_draft"].is_null());
// naming the sheet reads it with the filter left on
let value: c4::Value = c4::Loader::new(c4::Options {
sources: vec![(c4::Format::Excel, "./game.xlsx", "_draft", "db").into()],
..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()?;