Struct ConfigFile 

pub struct ConfigFile { /* private fields */ }

A loaded per-application config file.

cli-engine reads a single TOML file at <config-base>/<app_id>/config.toml (see config_file_path). Engine-reserved settings live in documented top-level tables (today just [credentials], see EngineConfig); consumer CLIs own every other top-level table and read them with section or deserialize. The file is also surfaced to command handlers via CommandContext::config and to module registration via ModuleContext::config.

Edits made with set preserve existing comments and formatting (backed by toml_edit) and are persisted with save.

Implementations

impl ConfigFile

pub fn load(app_id: &str) -> Self

Loads the config file for app_id.

Best-effort: a missing file, unresolvable config directory, or malformed TOML yields an empty document (a warning is logged for the malformed case). The resolved path is retained for save even when the file does not yet exist.

Blocking: this function performs synchronous filesystem I/O. The engine calls it once at Cli::new time (outside of command execution), which is acceptable for a one-shot CLI. Avoid calling it from hot paths or from within an async executor without spawn_blocking.

pub fn path(&self) -> Option<&Path>

Returns the resolved config file path, if a config directory was available. None means neither XDG_CONFIG_HOME/HOME nor APPDATA resolved to an absolute path (so nothing can be loaded or saved).

pub fn engine(&self) -> EngineConfig

Deserializes the engine-reserved sections into an EngineConfig.

Lenient: any deserialization error (for example an invalid [credentials].store) yields EngineConfig::default.

pub fn section<T: DeserializeOwned>(&self, name: &str) -> Result<Option<T>>

Deserializes a single top-level table name into T, or Ok(None) when the key is absent.

Use this to read a consumer-owned section such as [deploy]: cfg.section::<DeployConfig>("deploy")?.

Errors

Returns an error when the table is present but does not deserialize into T.

pub fn deserialize<T: DeserializeOwned>(&self) -> Result<T>

Deserializes the entire config file into a consumer root type T.

The root type may include the engine-reserved sections alongside its own; unknown keys are tolerated when T allows them.

Errors

Returns an error when the document does not deserialize into T.

pub fn get(&self, dotted_key: &str) -> Option<String>

Returns the string form of the value at a dotted key (for example credentials.store or deploy.region), or None when absent.

Scalars render without quotes; a table renders as its TOML fragment.

pub fn set(&mut self, dotted_key: &str, value: &str) -> Result<()>

Sets the value at a dotted key, creating intermediate tables as needed.

value is coerced to a TOML scalar type using these rules (in order):

1. "true" / "false" (case-sensitive) → TOML boolean.
2. Any string parseable as an i64 → TOML integer.
3. Any string parseable as an f64 (including "1e5", "inf", "nan") → TOML float.
4. Everything else → TOML string.

To force a value to be stored as a string when it looks numeric (e.g. a version like "1.0"), this API does not currently support quoting — wrap the value in the config file by hand.

The engine-reserved [credentials] table is validated: only the known key credentials.store is accepted; unknown keys in that table are rejected. Existing comments and formatting elsewhere in the file are preserved. Call save to persist.

Errors

Returns an error for an empty/invalid key, an unknown engine-reserved key, an invalid engine value, or a key whose parent path is not a table.

pub fn to_toml_string(&self) -> String

Renders the whole config document back to a TOML string (preserving comments and formatting).

pub fn save(&self) -> Result<()>

Persists the document to its config path via an atomic write.

Errors

Returns an error when no config path is available (no resolvable config directory) or the write fails.

Trait Implementations

impl Clone for ConfigFile

fn clone(&self) -> ConfigFile

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ConfigFile

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

Formats the value using the given formatter.

impl Default for ConfigFile

fn default() -> Self

Returns the “default value” for a type.