Struct Parser 

pub struct Parser { /* private fields */ }

Builder-style parser with a per-instance package registry for include package(...) support (E11).

Feature flag

This type is only available when the include-package Cargo feature is enabled:

[dependencies]
hocon-parser = { version = "...", features = ["include-package"] }

Usage

let config = hocon::Parser::new()
    .register_package("github.com/org/pkg", "reference.conf", include_str!("conf/reference.conf"))
    .parse_file("app.conf")?;

Cascade convention

For packages that depend on other HOCON-config-providing packages, follow this convention to cascade registrations:

// In your package (e.g., pkg_a/src/hocon.rs):
pub fn register(parser: hocon::Parser) -> hocon::Parser {
    let parser = parser
        .register_package("github.com/org/pkg_a", "reference.conf", include_str!("../conf/reference.conf"));
    // Cascade to dependencies:
    // let parser = pkg_b::hocon::register(parser);
    parser
}

Callers:

let config = pkg_a::hocon::register(hocon::Parser::new())
    .parse_file("app.conf")?;

Collision policy

Registering two different content strings for the same (identifier, file) key panics — this is a programming error (setup-time invariant). Re-registering byte-identical content is idempotent (no panic).

Implementations

impl Parser

pub fn new() -> Self

Create a new Parser with an empty package registry.

pub fn register_package( self, identifier: impl Into<String>, file: impl Into<String>, content: impl Into<String>, ) -> Self

Register HOCON content for an include package("identifier", "file") include statement.

Arguments

• identifier — the package identifier (e.g., "github.com/org/pkg"). Should follow Go-module-path style for cross-impl portability (E11 decision 1), but any non-empty string is accepted by the parser.
• file — the file path within the package (e.g., "reference.conf"). Must satisfy E11 decision 6 constraints.
• content — the HOCON source text. Typically loaded via include_str!. Empty content is valid and contributes {} to the merge.

Panics

Panics if different content is registered for the same (identifier, file) pair. Re-registering byte-identical content is idempotent (no panic).

Example

let parser = hocon::Parser::new()
    .register_package("github.com/org/pkg", "reference.conf", include_str!("conf/reference.conf"))
    .register_package("github.com/org/pkg", "overrides.conf", include_str!("conf/overrides.conf"));

pub fn parse(self, input: &str) -> Result<Config, HoconError>

Parse a HOCON string using the registered package registry.

Inherits the process environment, skipping entries whose name or value is not valid UTF-8; such a variable resolves as if it were unset.

pub fn parse_file(self, path: impl AsRef<Path>) -> Result<Config, HoconError>

Parse a HOCON file using the registered package registry.

Inherits the process environment, skipping entries whose name or value is not valid UTF-8; such a variable resolves as if it were unset.

pub fn parse_with_env( self, input: &str, env: &HashMap<String, String>, ) -> Result<Config, HoconError>

Parse a HOCON string with a custom environment map and the registered registry.

pub fn parse_file_with_env( self, path: impl AsRef<Path>, env: &HashMap<String, String>, ) -> Result<Config, HoconError>

Parse a HOCON file with a custom environment map and the registered registry.

pub fn parse_with_options( self, input: &str, opts: ParseOptions, ) -> Result<Config, HoconError>

Parse a HOCON string with explicit ParseOptions and the registered registry.

Equivalent to the module-level parse_string_with_options but threads the per-Parser package registry through phase 1, enabling include package("identifier", "file") to resolve against register_package-supplied content. Supports both fused (resolve_substitutions = true, default) and deferred (resolve_substitutions = false) lifecycles. The latter returns an unresolved Config whose Config::resolve call performs phase 2 — includes are already inlined at phase 1 so the registry is not needed after this call returns.

pub fn parse_file_with_options( self, path: impl AsRef<Path>, opts: ParseOptions, ) -> Result<Config, HoconError>

Parse a HOCON file with explicit ParseOptions and the registered registry. File’s parent directory is used as base_dir (overrides opts.base_dir).

Trait Implementations

impl Default for Parser

Available on crate feature include-package only.

fn default() -> Self

Returns the “default value” for a type.