Struct HoconLoader

pub struct HoconLoader { /* private fields */ }

Helper to load an HOCON file. This is used to set up the HOCON loader’s option, like strict mode, disabling system environment, and to buffer several documents.

Strict mode

If strict mode is enabled with strict(), loading a document will return the first error encountered. Otherwise, most errors will be wrapped in a Hocon::BadValue.

Usage

let mut loader = HoconLoader::new()         // Creating new loader with default configuration
    .no_system()                            // Disable substituting from system environment
    .no_url_include();                      // Disable including files from URLs

let default_values = r#"{ a = 7 }"#;
loader = loader.load_str(default_values)?   // Load values from a string
    .load_file("tests/data/basic.conf")?    // Load first file
    .load_file("tests/data/test01.conf")?;  // Load another file

let hocon = loader.hocon()?;                // Create the Hocon document from the loaded sources

Implementations

impl HoconLoader

pub fn new() -> Self

New HoconLoader with default configuration

pub fn no_system(&self) -> Self

Disable System environment substitutions

Example HOCON document

"system" : {
    "home"  : ${HOME},
    "pwd"   : ${PWD},
    "shell" : ${SHELL},
    "lang"  : ${LANG},
}

with system:

assert_eq!(
    HoconLoader::new().load_str(example)?.hocon()?["system"]["shell"],
    Hocon::String(String::from("/bin/bash"))
);

without system:

assert_eq!(
    HoconLoader::new().no_system().load_str(example)?.hocon()?["system"]["shell"],
    Hocon::BadValue(Error::KeyNotFound { key: String::from("SHELL") })
);

pub fn no_url_include(&self) -> Self

Disable loading included files from external urls.

Example HOCON document

include url("https://raw.githubusercontent.com/mockersf/hocon.rs/master/tests/data/basic.conf")

with url include:

assert_eq!(
    HoconLoader::new().load_file("tests/data/include_url.conf")?.hocon()?["d"],
    Hocon::Boolean(true)
);

without url include:

assert_eq!(
    HoconLoader::new().no_url_include().load_file("tests/data/include_url.conf")?.hocon()?["d"],
    Hocon::BadValue(Error::MissingKey)
);

Feature

This method depends on feature url-support

pub fn strict(&self) -> Self

Sets the HOCON loader to return the first Error encoutered instead of wrapping it in a Hocon::BadValue and continuing parsing

Example HOCON document

{
    a = ${b}
}

in permissive mode:

assert_eq!(
    HoconLoader::new().load_str(example)?.hocon()?["a"],
    Hocon::BadValue(Error::KeyNotFound { key: String::from("b") })
);

in strict mode:

assert_eq!(
    HoconLoader::new().strict().load_str(example)?.hocon(),
    Err(Error::KeyNotFound { key: String::from("b") })
);

pub fn max_include_depth(&self, new_max_depth: u8) -> Self

Set a new maximum include depth, by default 10

pub fn load_str(self, s: &str) -> Result<Self, Error>

Load a string containing an Hocon document. Includes are not supported when loading from a string

Errors

• Error::Parse if the document is invalid

Additional errors in strict mode

• Error::IncludeNotAllowedFromStr if there is an include in the string

pub fn load_file<P: AsRef<Path>>(&self, path: P) -> Result<Self, Error>

Load the HOCON configuration file containing an Hocon document

Errors

• Error::File if there was an error reading the file content
• Error::Parse if the document is invalid

Additional errors in strict mode

• Error::TooManyIncludes if there are too many included files within included files. The limit can be changed with max_include_depth

pub fn hocon(self) -> Result<Hocon, Error>

Load the documents as HOCON

Errors in strict mode

• Error::Include if there was an issue with an included file
• Error::KeyNotFound if there is a substitution with a key that is not present in the document
• Error::DisabledExternalUrl if crate was built without feature url-support and an include url("...") was found

pub fn resolve<'de, T>(self) -> Result<T, Error>

where T: Deserialize<'de>,

Deserialize the loaded documents to the target type

Errors

• Error::Deserialization if there was a serde error during deserialization (missing required field, type issue, …)

Additional errors in strict mode

• Error::Include if there was an issue with an included file
• Error::KeyNotFound if there is a substitution with a key that is not present in the document
• Error::DisabledExternalUrl if crate was built without feature url-support and an include url("...") was found

Trait Implementations

impl Clone for HoconLoader

fn clone(&self) -> HoconLoader

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for HoconLoader

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

Formats the value using the given formatter.

impl Default for HoconLoader

fn default() -> Self

Returns the “default value” for a type.