std/config

NAME

std/config - High-level configuration loading, merging, and querying.

SYNOPSIS

  from std/config import Config;
  from std/io import Path;

  let cfg := Config.load( [
    Path.join( [ "config", "base.toml" ] ),
    Path.join( [ "config", "local.json" ] ),
  ] );

  cfg.merge_flat(
    {
      "APP__port": "8080",
      "APP__debug": "true",
    },
    {
      prefix: "APP__",
      separator: "__",
      coerce: true,
    },
  );

  let host := cfg @ "/database/host";
  let port := cfg.get( "/port", 3000 );

IMPLEMENTATION SUPPORT

This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and Electron. It is partially supported by zuzu-js in the browser: environment override and multi-format branch selection coverage passes, but the main filesystem-backed configuration coverage is unsupported.

DESCRIPTION

This module provides a Config object for application-style configuration loading and overlaying.

Use Config.from_data(...) when you want to wrap an already-built Zuzu value instead of loading from files.

It is intentionally geared toward patterns common in higher-level config frameworks:

Item
load one or more files with format auto-detection,
Item
deep-merge config layers,
Item
apply flat overlays such as env-style FOO__BAR__BAZ keys,
Item
query config using ZPath and the @, @@, and @? operators.

The object itself is path-aware, so this works directly:

  let city := cfg @ "/service/address/city";

EXPORTS

Classes

Config
Static methods:
- from_data(data, options?)
  Parameters: data is configuration data and options controls metadata. Returns: Config. Wraps data in a config object.
- parse(text, format, options?)
  Parameters: text is config text, format is a format name, and options configures parsing. Returns: Config. Parses text into a config object.
- load(path_or_paths, options?)
  Parameters: path_or_paths is one source or an array of sources. Returns: Config. Loads and layers config files.
- detect_format(path_or_name, fallback?)
  Parameters: path_or_name is a path-like value and fallback is optional. Returns: String or null. Detects the config format.
Instance methods:
- type(), can_have_named_children(), can_have_indexed_children(), can_have_named_indexed_children(), children(), attributes()
  Parameters: none. Returns: ZPath node metadata. Provides the inherited node API used when a Config is queried as a path root.
- do_action_on_child(child, action), ref_on_child(child)
  Parameters: child is a selected node and action is a path action. Returns: value or Function. Provides inherited mutation and reference support for path assignments.
- to_data(), clone()
  Parameters: none. Returns: value or Config. Returns raw data or a copy of the config.
- source(), format(), layers()
  Parameters: none. Returns: value. Returns config source metadata.
- get(path, fallback?), get_all(path), select(path)
  Parameters: path is a path expression and fallback is optional. Returns: value or Array. Reads config values.
- exists(path), require(path, message?)
  Parameters: path is a path expression and message is optional. Returns: Boolean or value. Tests for or requires a config value.
- query(path), first(path, fallback?)
  Parameters: path is a path expression and fallback is optional. Returns: Array or value. Queries config values.
- assign_first(path, value, op?)
  Parameters: path selects values, value is assigned, and op is optional. Returns: value. Updates the first match.
- assign_all(path, value, op?)
  Parameters: path selects values, value is assigned, and op is optional. Returns: value. Updates every match.
- assign_maybe(path, value, op?)
  Parameters: path selects values, value is assigned, and op is optional. Returns: Boolean. Updates the first match when present.
- ref_first(path), ref_all(path), ref_maybe(path)
  Parameters: path is a path expression. Returns: Function, Array, or null. Returns reference-like accessors.
- merge(data_or_config, options?), overlay(data_or_config, options?)
  Parameters: data_or_config is incoming data and options controls merge behaviour. Returns: Config. Merges configuration data.
- merge_flat(values, options?), merge_env(values, options?)
  Parameters: values is flat config data and options controls key mapping. Returns: Config. Merges flat or environment-style values.
- set(path, value), set_default(path, value)
  Parameters: path is a simple path and value is any value. Returns: Config. Sets or defaults a config value.
- encode(format?, options?), save(path, options?)
  Parameters: format, path, and options control output. Returns: String or Config. Encodes or saves configuration data.
- load_file(path, options?)
  Parameters: path is a config source and options controls parsing. Returns: Config. Loads one additional config file into the object.

NOTES

Item
merge performs a deep merge for dictionaries.
Item
Arrays are replaced by default; pass { array_merge: "append" } to append instead.
Item
set and set_default create missing parent dictionaries, but only for simple absolute paths such as /server/port. They intentionally do not try to create missing nodes for complex selectors or filters.

COPYRIGHT AND LICENCE

std/config is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.

Module