README.md

hocon

Parse HOCON configuration files in Elixir following the HOCON specifications.

Basic usage

Assume the file my-configuration.conf exists and has the following content:

{
  home : /path/to/home
  timeout : 300
  logger {
    level = "DEBUG"
  }
}

Then you can read and parse the HOCON-Configuration file:

    {:ok, body} = File.read("my-configuration.conf")
    result = Hocon.decode(body)

    IO.puts inspect result

    {:ok, %{"home" => "path/to/home", "logger" => %{"level" => "DEBUG"}, "timeout" => 300}}   

The HOCON configuration is very powerfull and has a lot of nice features

{
  // you can use comments
  
  # you can concat arrays like this
  dirs += ${PWD}
  dirs += /working-folder
  
  # you can concat strings like this
  path : ${PWD}
  path : ${path}"/working-folder"
  
  # Here are several ways to define `a` to the same array value:
  // one array
  a : [ 1, 2, 3, 4 ]
  // two arrays that are concatenated
  a : [ 1, 2 ] [ 3, 4 ]
  // with self-referential substitutions
  a : [ 1, 2 ]
  a : ${a} [ 3, 4 ]
 
  # some nested objects:
  foo { bar { baz : 42 } }
  
  # you can build values with substitutions
  foo : { a : { c : 1 } }
  foo : ${foo.a}
  foo : { a : 2 }
}

After parsing you get this map as result (where PWD=/Users/micha/projects/elixir/hocon):

  %{
    "dirs" => ["/Users/micha/projects/elixir/hocon", "working-folder"],
    "path" => "/Users/micha/projects/elixir/hocon/working-folder"},
    "a" => [1, 2, 3, 4], 
    "foo" => %{"a" => 2, "bar" => %{"baz" => 42}, "c" => 1} 
  }

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