# HOCON.rs [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Realease Doc](https://docs.rs/hocon/badge.svg)](https://docs.rs/hocon) [![Crate](https://img.shields.io/crates/v/hocon.svg)](https://crates.io/crates/hocon)

The API docs for the master branch are published [here](https://mockersf.github.io/hocon.rs/).

Parse HOCON configuration files in Rust following the
[HOCON Specifications](https://github.com/lightbend/config/blob/master/HOCON.md).

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

```rust
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

```rust
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`

```rust
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

```rust
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

```rust
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](https://github.com/lightbend/config/blob/master/HOCON.md#include-syntax)). 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`

```rust
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

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