Skip to main content

Options

Struct Options 

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

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

Spreadsheet 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());
§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) -> Options

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: &Options) -> 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 = Infallible

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

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

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.