Skip to main content

Options

Struct Options 

Source
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: isize

Folder 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: bool

Folder 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: bool

Folder 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: bool

All 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 leave Null gaps — a[1] + a[4] give a five-element array with nulls at 0, 2 and 3; deserialize such arrays as Vec<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::Table at its row, Error::Parse naming 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: bool

All 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: Order

All 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: bool

Spreadsheet 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: bool

Only 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: bool

Only 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: bool

All 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: bool

All 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: bool

All 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: bool

Spreadsheet 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());
§ignore_hidden_sheets: bool

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()?;

Trait Implementations§

Source§

impl Clone for Options

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Options

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for Options

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl PartialEq for Options

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for Options

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.