HOCON.rs

Warning

This repository is archived as I don't use this crate anymore and don't have the time to update its dependencies. It's stuck on an old version of nom and too painful for me to update for now.

You can contact me if you want to help with maintenance or take over.

The API docs for the master branch are published here.

Parse HOCON configuration files in Rust following the HOCON Specifications.

This implementation goal is to be as permissive as possible, returning a valid document with all errors wrapped in Hocon::BadValue. strict mode can be enabled to return the first Error encountered instead.

Examples

Parsing a string to a struct using serde

use serde::Deserialize;

#[derive(Deserialize)]
struct Configuration {
    host: String,
    port: u8,
    auto_connect: bool,
}

fn main() -> Result<(), Error> {
    let s = r#"{
        host: 127.0.0.1
        port: 80
        auto_connect: false
    }"#;

    let conf: Configuration = hocon::de::from_str(s)?;

    Ok(())
}

Reading from a string and getting value directly

use hocon::HoconLoader;

fn main() -> Result<(), Error> {
    let s = r#"{ a: 7 }"#;

    let doc = HoconLoader::new()
        .load_str(s)?
        .hocon()?;

    let a = doc["a"].as_i64();
    assert_eq!(a, Some(7));

    Ok(())
}

Deserializing to a struct using serde

use serde::Deserialize;

use hocon::HoconLoader;

#[derive(Deserialize)]
struct Configuration {
    host: String,
    port: u8,
    auto_connect: bool,
}

fn main() -> Result<(), Error> {
    let s = r#"{
        host: 127.0.0.1
        port: 80
        auto_connect: false
    }"#;

    let conf: Configuration = HoconLoader::new()
        .load_str(s)?
        .resolve()?;

    Ok(())
}

Reading from a file

use hocon::HoconLoader;

fn main() -> Result<(), Error> {
    let doc = HoconLoader::new()
        .load_file("tests/data/basic.conf")?
        .hocon()?;

    let a = doc["a"].as_i64();
    assert_eq!(a, Some(5));

    Ok(())
}

Reading from several documents

use hocon::HoconLoader;

fn main() -> Result<(), Error> {
    let s = r#"{
        a: will be changed
        unchanged: original value
    }"#;

    let doc = HoconLoader::new()
        .load_str(s)?
        .load_file("tests/data/basic.conf")?
        .hocon()?;

    let a = doc["a"].as_i64();
    assert_eq!(a, Some(5));
    let unchanged = doc["unchanged"].as_string();
    assert_eq!(unchanged, Some(String::from("original value")));

    Ok(())
}

Features

All features are enabled by default. They can be disabled to reduce dependencies.

url-support

This feature enable fetching URLs in includes with include url("http://mydomain.com/myfile.conf") (see spec). If disabled, includes will only load local files specified with include "path/to/file.conf" or include file("path/to/file.conf").

serde-support

This feature enable deserializing to a struct implementing Deserialize using serde

use serde::Deserialize;

use hocon::HoconLoader;

#[derive(Deserialize)]
struct Configuration {
    host: String,
    port: u8,
    auto_connect: bool,
}

# fn main() -> Result<(), Error> {
let s = r#"{host: 127.0.0.1, port: 80, auto_connect: false}"#;

# #[cfg(feature = "serde-support")]
let conf: Configuration = HoconLoader::new().load_str(s)?.resolve()?;
# Ok(())
# }

Spec Coverage

https://github.com/lightbend/config/blob/master/HOCON.md

• parsing JSON
• comments
• omit root braces
• key-value separator
• commas are optional if newline is present
• whitespace
• duplicate keys and object merging
• unquoted strings
• multi-line strings
• value concatenation
• object concatenation
• array concatenation
• path expressions
• path as keys
• substitutions
• includes
• conversion of numerically-indexed objects to arrays
• allow URL for included files
• duration unit format
• period unit format
• size unit format