Skip to main content

ConfigReader

qubit_config

Trait ConfigReader 

Source 
pub trait ConfigReader {

Show 41 methods    // Required methods
    fn is_enable_variable_substitution(&self) -> bool;
    fn max_substitution_depth(&self) -> usize;
    fn description(&self) -> Option<&str>;
    fn get_property(&self, name: impl ConfigName) -> Option<&Property>;
    fn len(&self) -> usize;
    fn is_empty(&self) -> bool;
    fn keys(&self) -> Vec<String>;
    fn contains(&self, name: impl ConfigName) -> bool;
    fn get_strict<T>(&self, name: impl ConfigName) -> ConfigResult<T>
       where MultiValues: MultiValuesFirstGetter<T>;
    fn get_list<T>(&self, name: impl ConfigName) -> ConfigResult<Vec<T>>
       where T: FromConfig;
    fn get_list_strict<T>(&self, name: impl ConfigName) -> ConfigResult<Vec<T>>
       where MultiValues: MultiValuesGetter<T>;
    fn read_options(&self) -> &ConfigReadOptions;
    fn get_optional_list<T>(
        &self,
        name: impl ConfigName,
    ) -> ConfigResult<Option<Vec<T>>>
       where T: FromConfig;
    fn contains_prefix(&self, prefix: &str) -> bool;
    fn iter_prefix<'a>(
        &'a self,
        prefix: &'a str,
    ) -> Box<dyn Iterator<Item = (&'a str, &'a Property)> + 'a>;
    fn iter<'a>(
        &'a self,
    ) -> Box<dyn Iterator<Item = (&'a str, &'a Property)> + 'a>;
    fn is_null(&self, name: impl ConfigName) -> bool;
    fn subconfig(
        &self,
        prefix: &str,
        strip_prefix: bool,
    ) -> ConfigResult<Config>;
    fn deserialize<T>(&self, prefix: &str) -> ConfigResult<T>
       where T: DeserializeOwned;
    fn prefix_view(&self, prefix: &str) -> ConfigPrefixView<'_>;

    // Provided methods
    fn get<T>(&self, name: impl ConfigName) -> ConfigResult<T>
       where T: FromConfig { ... }
    fn get_or<T>(
        &self,
        name: impl ConfigName,
        default: impl IntoConfigDefault<T>,
    ) -> ConfigResult<T>
       where T: FromConfig { ... }
    fn get_optional<T>(&self, name: impl ConfigName) -> ConfigResult<Option<T>>
       where T: FromConfig { ... }
    fn get_any<T>(&self, names: impl ConfigNames) -> ConfigResult<T>
       where T: FromConfig { ... }
    fn get_optional_any<T>(
        &self,
        names: impl ConfigNames,
    ) -> ConfigResult<Option<T>>
       where T: FromConfig { ... }
    fn get_any_or<T>(
        &self,
        names: impl ConfigNames,
        default: impl IntoConfigDefault<T>,
    ) -> ConfigResult<T>
       where T: FromConfig { ... }
    fn get_any_or_with<T>(
        &self,
        names: impl ConfigNames,
        default: impl IntoConfigDefault<T>,
        read_options: &ConfigReadOptions,
    ) -> ConfigResult<T>
       where T: FromConfig { ... }
    fn read<T>(&self, field: ConfigField<T>) -> ConfigResult<T>
       where T: FromConfig { ... }
    fn read_optional<T>(&self, field: ConfigField<T>) -> ConfigResult<Option<T>>
       where T: FromConfig { ... }
    fn get_optional_any_with_options<T>(
        &self,
        names: impl ConfigNames,
        options: &ConfigReadOptions,
    ) -> ConfigResult<Option<T>>
       where T: FromConfig { ... }
    fn resolve_key(&self, name: impl ConfigName) -> String { ... }
    fn get_string(&self, name: impl ConfigName) -> ConfigResult<String> { ... }
    fn get_string_any(&self, names: impl ConfigNames) -> ConfigResult<String> { ... }
    fn get_optional_string_any(
        &self,
        names: impl ConfigNames,
    ) -> ConfigResult<Option<String>> { ... }
    fn get_string_any_or(
        &self,
        names: impl ConfigNames,
        default: &str,
    ) -> ConfigResult<String> { ... }
    fn get_string_or(
        &self,
        name: impl ConfigName,
        default: &str,
    ) -> ConfigResult<String> { ... }
    fn get_string_list(
        &self,
        name: impl ConfigName,
    ) -> ConfigResult<Vec<String>> { ... }
    fn get_string_list_or(
        &self,
        name: impl ConfigName,
        default: &[&str],
    ) -> ConfigResult<Vec<String>> { ... }
    fn get_optional_string(
        &self,
        name: impl ConfigName,
    ) -> ConfigResult<Option<String>> { ... }
    fn get_optional_string_list(
        &self,
        name: impl ConfigName,
    ) -> ConfigResult<Option<Vec<String>>> { ... }
    fn get_optional_any_with_options_and_substitution<T>(
        &self,
        names: impl ConfigNames,
        options: &ConfigReadOptions,
    ) -> ConfigResult<Option<T>>
       where T: FromConfig { ... }

}
Expand description

Read-only configuration interface.

This trait allows consumers to read configuration values without requiring ownership of a crate::Config. Both crate::Config and crate::ConfigPrefixView implement it.

Its required methods mirror the read-only surface of crate::Config (metadata, raw properties, iteration, subtree extraction, and serde deserialization), with prefix views resolving keys relative to their logical prefix.

Required Methods§

Source

fn is_enable_variable_substitution(&self) -> bool

Returns whether ${...} variable substitution is applied when reading string values.

§Returns

true if substitution is enabled for this reader.

Source

fn max_substitution_depth(&self) -> usize

Returns the maximum recursion depth allowed when resolving nested ${...} references.

§Returns

Maximum substitution depth (see DEFAULT_MAX_SUBSTITUTION_DEPTH for the default used by crate::Config).

Source

fn description(&self) -> Option<&str>

Returns the optional human-readable description attached to this configuration (the whole document; prefix views expose the same value as the underlying crate::Config).

Source

fn get_property(&self, name: impl ConfigName) -> Option<&Property>

Returns a reference to the raw Property for name, if present.

For a ConfigPrefixView, name is resolved relative to the view prefix (same rules as Self::get).

Source

fn len(&self) -> usize

Number of configuration entries visible to this reader (all keys for crate::Config; relative keys only for a ConfigPrefixView).

Source

fn is_empty(&self) -> bool

Returns true when Self::len is zero.

Source

fn keys(&self) -> Vec<String>

All keys visible to this reader (relative keys for a prefix view).

Source

fn contains(&self, name: impl ConfigName) -> bool

Returns whether a property exists for the given key.

§Parameters
§Returns

true if the key is present.

Source

fn get_strict<T>(&self, name: impl ConfigName) -> ConfigResult<T>
where MultiValues: MultiValuesFirstGetter<T>,

Reads the first stored value for name without cross-type conversion.

§Type parameters
  • T - Exact target type; requires MultiValues to implement MultiValuesFirstGetter for T.
§Parameters
  • name - Configuration key.
§Returns

The exact stored value on success, or a crate::ConfigError if the key is missing, empty, or has a different stored type.

Source

fn get_list<T>(&self, name: impl ConfigName) -> ConfigResult<Vec<T>>
where T: FromConfig,

Reads all stored values for name and converts each element to T.

§Type parameters
  • T - Element type supported by the shared conversion layer.
§Parameters
  • name - Configuration key.
§Returns

A vector of values on success, or a crate::ConfigError on failure.

Source

fn get_list_strict<T>(&self, name: impl ConfigName) -> ConfigResult<Vec<T>>
where MultiValues: MultiValuesGetter<T>,

Reads all stored values for name without cross-type conversion.

§Type parameters
  • T - Exact element type; requires MultiValues to implement MultiValuesGetter for T.
§Parameters
  • name - Configuration key.
§Returns

A vector of exact stored values on success, or a crate::ConfigError on failure.

Source

fn read_options(&self) -> &ConfigReadOptions

Gets the read options active for this reader.

§Returns

Global read options inherited by field-less reads.

Source

fn get_optional_list<T>( &self, name: impl ConfigName, ) -> ConfigResult<Option<Vec<T>>>
where T: FromConfig,

Gets an optional list with the same semantics as crate::Config::get_optional_list.

§Type parameters
  • T - Element type supported by the shared conversion layer.
§Parameters
  • name - Configuration key.
§Returns

Ok(Some(vec)), Ok(None) when missing or empty, or Err on failure.

Source

fn contains_prefix(&self, prefix: &str) -> bool

Returns whether any key visible to this reader starts with prefix.

§Parameters
  • prefix - Key prefix to test (for a prefix view, keys are relative to that view).
§Returns

true if at least one matching key exists.

Source

fn iter_prefix<'a>( &'a self, prefix: &'a str, ) -> Box<dyn Iterator<Item = (&'a str, &'a Property)> + 'a>

Iterates (key, property) pairs for keys that start with prefix.

§Parameters
  • prefix - Key prefix filter.
§Returns

A boxed iterator over matching entries.

Source

fn iter<'a>(&'a self) -> Box<dyn Iterator<Item = (&'a str, &'a Property)> + 'a>

Iterates all (key, property) pairs visible to this reader (same scope as Self::keys).

Source

fn is_null(&self, name: impl ConfigName) -> bool

Returns true if the key exists and the property has no values (same as crate::Config::is_null).

Source

fn subconfig(&self, prefix: &str, strip_prefix: bool) -> ConfigResult<Config>

Extracts a subtree as a new Config (same semantics as crate::Config::subconfig; on a prefix view, prefix is relative to the view).

Source

fn deserialize<T>(&self, prefix: &str) -> ConfigResult<T>
where T: DeserializeOwned,

Deserializes the subtree at prefix with serde (same as crate::Config::deserialize; on a prefix view, prefix is relative).

Source

fn prefix_view(&self, prefix: &str) -> ConfigPrefixView<'_>

Creates a read-only prefix view; relative keys resolve under prefix.

Semantics match crate::Config::prefix_view and crate::ConfigPrefixView::prefix_view (nested prefix when called on a view).

§Parameters
  • prefix - Logical prefix; empty means the full configuration (same as root).
§Returns

A ConfigPrefixView borrowing this reader’s underlying crate::Config.

Provided Methods§

Source

fn get<T>(&self, name: impl ConfigName) -> ConfigResult<T>
where T: FromConfig,

Reads the first stored value for name and converts it to T.

§Type parameters
§Parameters
  • name - Configuration key.
§Returns

The converted value on success, or a crate::ConfigError if the key is missing, empty, or not convertible.

Source

fn get_or<T>( &self, name: impl ConfigName, default: impl IntoConfigDefault<T>, ) -> ConfigResult<T>
where T: FromConfig,

Gets a value or default if the key is missing or empty.

Conversion and substitution errors are returned instead of being hidden by the default.

Source

fn get_optional<T>(&self, name: impl ConfigName) -> ConfigResult<Option<T>>
where T: FromConfig,

Gets an optional value with the same semantics as crate::Config::get_optional.

§Type parameters
§Parameters
  • name - Configuration key (relative for a prefix view).
§Returns

Ok(Some(v)), Ok(None) when missing or empty, or Err on conversion failure.

Source

fn get_any<T>(&self, names: impl ConfigNames) -> ConfigResult<T>
where T: FromConfig,

Reads a value from the first present and non-empty key in names.

§Parameters
  • names - Candidate keys in priority order.
§Returns

Parsed value from the first configured key. Conversion errors stop the search and are returned directly.

Source

fn get_optional_any<T>( &self, names: impl ConfigNames, ) -> ConfigResult<Option<T>>
where T: FromConfig,

Reads an optional value from the first present and non-empty key.

§Parameters
  • names - Candidate keys in priority order.
§Returns

Ok(None) only when all keys are missing or empty.

Source

fn get_any_or<T>( &self, names: impl ConfigNames, default: impl IntoConfigDefault<T>, ) -> ConfigResult<T>
where T: FromConfig,

Reads a value from any key, using default only when all keys are absent or empty.

§Parameters
  • names - Candidate keys in priority order.
  • default - Fallback when no candidate is configured.
§Returns

Parsed value or default; parsing errors are never swallowed.

Source

fn get_any_or_with<T>( &self, names: impl ConfigNames, default: impl IntoConfigDefault<T>, read_options: &ConfigReadOptions, ) -> ConfigResult<T>
where T: FromConfig,

Reads a value from any key with explicit read options, using default only when all keys are absent or empty.

§Parameters
  • names - Candidate keys in priority order.
  • default - Fallback when no candidate is configured.
  • read_options - Parsing options for this read.
§Returns

Parsed value or default; parsing errors are never swallowed.

Source

fn read<T>(&self, field: ConfigField<T>) -> ConfigResult<T>
where T: FromConfig,

Reads a declared field.

§Parameters
  • field - Field declaration containing name, aliases, defaults, and optional field-level read options.
§Returns

Parsed field value or its default.

Source

fn read_optional<T>(&self, field: ConfigField<T>) -> ConfigResult<Option<T>>
where T: FromConfig,

Reads an optional declared field.

§Parameters
  • field - Field declaration.
§Returns

Parsed field value, its default, or None.

Source

fn get_optional_any_with_options<T>( &self, names: impl ConfigNames, options: &ConfigReadOptions, ) -> ConfigResult<Option<T>>
where T: FromConfig,

Shared implementation for field-level and global multi-key reads.

Source

fn resolve_key(&self, name: impl ConfigName) -> String

Resolves name into the canonical key path against the root crate::Config.

For a root crate::Config, this returns name unchanged. For a crate::ConfigPrefixView, this prepends the effective view prefix so callers can report root-relative key paths in diagnostics.

§Parameters
  • name - Relative or absolute key in the current reader scope.
§Returns

Root-relative key path string.

Source

fn get_string(&self, name: impl ConfigName) -> ConfigResult<String>

Gets a string value, applying variable substitution when enabled.

§Parameters
  • name - Configuration key.
§Returns

The string after ${...} resolution, or a crate::ConfigError.

Source

fn get_string_any(&self, names: impl ConfigNames) -> ConfigResult<String>

Gets a string value from the first present and non-empty key in names.

§Parameters
  • names - Candidate keys in priority order.
§Returns

The resolved string from the first configured key.

Source

fn get_optional_string_any( &self, names: impl ConfigNames, ) -> ConfigResult<Option<String>>

Gets an optional string value from the first present and non-empty key.

§Parameters
  • names - Candidate keys in priority order.
§Returns

Ok(None) only when all keys are missing or empty.

Source

fn get_string_any_or( &self, names: impl ConfigNames, default: &str, ) -> ConfigResult<String>

Gets a string from any key, or default when all keys are missing or empty.

§Parameters
  • names - Candidate keys in priority order.
  • default - Fallback string used only when every key is missing or empty.
§Returns

The resolved string or a clone of default; substitution errors are returned.

Source

fn get_string_or( &self, name: impl ConfigName, default: &str, ) -> ConfigResult<String>

Gets a string value with substitution, or default if the key is missing or empty.

§Parameters
  • name - Configuration key.
  • default - Fallback string used only when the key is missing or empty.
§Returns

The resolved string or a clone of default; parsing and substitution errors are returned.

Source

fn get_string_list(&self, name: impl ConfigName) -> ConfigResult<Vec<String>>

Gets all string values for name, applying substitution to each element when enabled.

§Parameters
  • name - Configuration key.
§Returns

A vector of resolved strings, or a crate::ConfigError.

Source

fn get_string_list_or( &self, name: impl ConfigName, default: &[&str], ) -> ConfigResult<Vec<String>>

Gets a string list with substitution, or copies default if the key is missing or empty.

§Parameters
  • name - Configuration key.
  • default - Fallback string slices used only when the key is missing or empty.
§Returns

The resolved list or default converted to owned Strings`; parsing and substitution errors are returned.

Source

fn get_optional_string( &self, name: impl ConfigName, ) -> ConfigResult<Option<String>>

Gets an optional string with the same three-way semantics as crate::Config::get_optional_string.

§Parameters
  • name - Configuration key.
§Returns

Ok(None) if the key is missing or empty; Ok(Some(s)) with substitution applied; or Err if the value exists but cannot be read as a string.

Source

fn get_optional_string_list( &self, name: impl ConfigName, ) -> ConfigResult<Option<Vec<String>>>

Gets an optional string list with per-element substitution when enabled.

§Parameters
  • name - Configuration key.
§Returns

Ok(None) if the key is missing or empty; Ok(Some(vec)) otherwise; or Err on conversion/substitution failure.

Source

fn get_optional_any_with_options_and_substitution<T>( &self, names: impl ConfigNames, options: &ConfigReadOptions, ) -> ConfigResult<Option<T>>
where T: FromConfig,

Shared implementation for string helper multi-key reads.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§