hocon

Substitutions

2026-06-08T11:57:37.800272439Z

A substitution lets one value reference another, so you write a setting once and reuse it. hocon resolves substitutions automatically when you call Hocon.parse — the config you get back has none left in it.

The two forms

${path} is a required substitution: it must resolve to something, or parsing fails.

val config = Hocon.parse("""
  host = localhost
  url  = ${host}
""")

config.getString("url")   // "localhost"

${?path} is optional: if it resolves to nothing, the field that holds it simply does not appear.

val config = Hocon.parse("""
  a = 1
  b = ${?not-set}
""")

config.hasPath("b")   // false

Resolution rules

Substitutions resolve against the merged root, so they are order-independent — a value may reference a key defined later in the document.
A path may point anywhere, including into nested objects (${server.host}), and may copy a whole object or array, not just a scalar.
Chains resolve transitively — a = ${b}, b = ${c}, c = 1 makes a equal 1.

val config = Hocon.parse("""
  defaults { timeout = 30, retries = 3 }
  service  = ${defaults}        # copies the whole object
  primary  = ${service.timeout} # 30
""")

Environment fallback

A substitution that is not found in the config falls back to an EnvSource. The default environment is empty (the core stays pure and platform-independent); pass one to Hocon.parse to wire in the real environment or a fixed map:

val env = EnvSource.fromMap(Map("HOME" -> "/home/ada"))
val config = Hocon.parse("home = ${HOME}", env)
config.getString("home")   // "/home/ada"

Config values always win over the environment — the environment is only consulted when the path is absent from the document.

Note

Config values take precedence over the environment, and a required ${path} found in neither raises UnresolvedSubstitutionException. To make a substitution that may be absent, use the optional ${?path} form.

Cycles

A reference chain that closes on itself — including a value that references itself with no prior definition — raises CircularReferenceException, with the chain in the message:

Hocon.parse("""
  a = ${b}
  b = ${a}
""")
// CircularReferenceException: Circular reference in substitution: a -> b -> a

Concatenating with surrounding text

A substitution may also be one piece of a larger value. Written with whitespace next to other text, it joins into a single string — this is value concatenation:

val config = Hocon.parse("""
  host = example.com
  port = 8080
  url  = "http://"${host}":"${port}
""")

config.getString("url")   // "http://example.com:8080"

The pieces resolve and then concatenate, so a substitution can sit inside a URL, a path, or any other composed string.

Roadmap

2026-06-08T11:57:37.800272439Z

hocon is built in phases, smallest-useful-thing first. The goal of the early phases is a parser good enough to write and read i18n translation files; later phases close the gap to the full HOCON specification, with the reference implementation’s conformance corpus as the eventual oracle.

Phase	Scope	Status
1	Lexer + parser → untyped `Config` (comments, quoted/unquoted strings, nested objects, path-expression keys, arrays).	✅ Done
2	Object merging + `withFallback` (base locale + overrides).	✅ Done
3	Substitutions: `${path}`, `${?path}`, environment fallback, cycle detection.	✅ Done
4	Value concatenation + durations (`10s`) and sizes (`512K`, `10MB`).	✅ Done
5	`include` directives behind a pluggable, per-platform IO source.	Planned
6	Typed decoder with case-class derivation (`config.as[A]`).	Planned
7	Conformance against the reference test corpus.	Planned

Design notes

Cross-platform from the first commit. The lexer, parser, and Config API are pure Scala in a shared source set; every test runs identically on the JVM, Scala.js, and Scala Native. IO and environment access — needed for include and substitution fallback — will live behind a small capability seam with per-platform implementations, so the core never touches a filesystem.
Untyped core first, typed decoder later. The Config tree and its getters are the foundation; the case-class decoder (config.as[A]) layers on top once the value model is complete, mirroring how the typed and untyped layers separate elsewhere.
Spec-correct, not convenient. Where the HOCON spec and a nicer-for-i18n shortcut disagree — most visibly the forbidden characters in unquoted strings — hocon follows the spec and asks you to quote, so the same files will validate against the conformance corpus in Phase 7.

Quick Start

2026-06-08T11:57:37.800272439Z

Parse a HOCON document, read typed values out of it, and use it for i18n messages.

Parse and read

Hocon.parse turns a string of HOCON into an immutable Config. Read values with typed getters; paths are dot-separated.

import io.github.edadma.hocon.*

val config = Hocon.parse("""
  app {
    name = "Roamer"
    window { width = 1024, height = 768 }
    recent-files = ["a.txt", "b.txt"]
    telemetry = false
  }
""")

config.getString("app.name")              // "Roamer"
config.getInt("app.window.width")         // 1024
config.getBoolean("app.telemetry")        // false
config.getStringList("app.recent-files")  // List("a.txt", "b.txt")

// Drill into a sub-tree:
val window = config.getConfig("app.window")
window.getInt("height")                   // 768

A missing path throws MissingPathException; a value of the wrong shape throws WrongTypeException. When a key may be absent, use hasPath or the *Opt variants:

config.hasPath("app.theme")               // false
config.getStringOpt("app.theme")          // None
config.getIntOpt("app.window.width")      // Some(1024)

A note on quoting

HOCON lets you write unquoted strings, but it forbids these characters inside them:

$ " { } [ ] : = , + # ` ^ ? ! @ * & \

Most real UI strings — Hello, world, Are you sure?, {count} items — contain one of them, so quote your translation strings. This is spec-correct HOCON, not a limitation of this library; bare words are fine for identifiers, numbers, and simple paths.

name      = roamer            # fine — a bare identifier
greeting  = "Hello, world"    # must be quoted — contains a comma

i18n messages

HOCON’s nesting and comments make it a comfortable format for translation files. The Messages helper looks a string up by path and fills {name} placeholders:

val en = Hocon.parse("""
  greeting   = "Hello, {name}"
  cart.items = "{count} items in your cart"
""")

val m = Messages(en)
m("greeting", "name" -> "Ada")   // "Hello, Ada"
m("cart.items", "count" -> 3)    // "3 items in your cart"

A placeholder with no matching argument is left untouched, so a missing value is visible rather than silently dropped.

Base locale with overrides

Keep one complete base locale and let each translation override only what it changes. Merge with withFallback:

val base = Hocon.parse("""
  greeting = "Hello"
  farewell = "Goodbye"
  nav { home = "Home", about = "About" }
""")

val fr = Hocon.parse("""
  greeting = "Bonjour"
  nav { home = "Accueil" }
""")

val m = Messages(fr.withFallback(base))
m("greeting")   // "Bonjour"   (translated)
m("farewell")   // "Goodbye"   (from base)
m("nav.home")   // "Accueil"   (translated)
m("nav.about")  // "About"     (from base)

See the merging guide for the full rules, and the Config reference for every getter.

Messages

2026-06-08T11:57:37.800272439Z

Messages is a thin i18n helper over a Config of translation strings. It looks messages up by path and fills {name} placeholders from named arguments. It is a convenience layer — the config it reads is ordinary HOCON.

Constructing

Wrap any Config whose values are the message strings:

import io.github.edadma.hocon.*

val en = Hocon.parse("""
  greeting   = "Hello, {name}"
  cart.items = "{count} items in your cart"
  plain      = "No placeholders here"
""")

val m = Messages(en)

For a base locale with per-language overrides, merge first with withFallback and wrap the result:

val m = Messages(fr.withFallback(base))

Methods

Method	Returns	Description
`apply(path, args: (String, Any)*)`	`String`	Look up `path` and substitute `{name}` placeholders from `args`.
`get(path)`	`String`	Look up `path` with no substitution.
`hasPath(path)`	`Boolean`	Whether the underlying config has a value at `path`.

m("greeting", "name" -> "Ada")   // "Hello, Ada"
m("cart.items", "count" -> 3)    // "3 items in your cart"
m("plain")                       // "No placeholders here"

Behavior

Placeholders are {name} where the name is letters, digits, or underscores.
Argument values are converted with toString, so numbers, booleans, and any type work.
A placeholder with no matching argument is left untouched, so a missing value shows up in the output rather than disappearing silently:

m("greeting", "other" -> 1)      // "Hello, {name}"

A missing message path throws MissingPathException, like any other Config lookup.

Merging and fallback

2026-06-08T11:57:37.800272439Z

Real configuration is layered: a base with environment overrides, a default locale with per-language translations, library defaults beneath application settings. hocon expresses that with fallback — one config supplying defaults for another.

withFallback

a.withFallback(b) returns a new config where a wins and b fills in whatever a does not set:

val base     = Hocon.parse("a = 1, b = base")
val override_ = Hocon.parse("b = over, c = 3")

val merged = override_.withFallback(base)
merged.getInt("a")     // 1      — only in base
merged.getString("b")  // "over" — override wins
merged.getInt("c")     // 3      — only in override

How merging works

The merge is recursive, and the rule is the same at every level:

Objects present on both sides merge recursively. Their keys are unioned; shared keys follow these same rules one level down.
Scalars and arrays replace. The winning side’s value is taken whole — arrays are not concatenated or element-merged.
A null on the winning side shadows the fallback. Because hasPath treats null as absent, a null override effectively unsets a key the fallback defined.

val base = Hocon.parse("""
  server { host = localhost, port = 80, tags = [a, b] }
""")
val over = Hocon.parse("""
  server { port = 9000, tags = [c] }
""")

val merged = over.withFallback(base)
merged.getString("server.host")      // "localhost"  — kept from base
merged.getInt("server.port")         // 9000         — overridden
merged.getStringList("server.tags")  // List("c")    — arrays replace, not concat

Layering several configs

Hocon.load merges any number of configs so that later arguments win — pass the base first and the most specific overrides last:

val effective = Hocon.load(
  libraryDefaults,   // weakest
  applicationConfig,
  userOverrides,     // strongest
)

With no arguments it returns the empty config.

Base locale with overrides

This is the i18n pattern: keep one complete base locale, and let each translation override only the strings it changes. Anything a translation omits falls through to the base, so the UI is never missing a string.

val base = Hocon.parse("""
  greeting = "Hello"
  farewell = "Goodbye"
  nav { home = "Home", about = "About" }
""")

val fr = Hocon.parse("""
  greeting = "Bonjour"
  nav { home = "Accueil" }
""")

val messages = Messages(fr.withFallback(base))
messages("greeting")   // "Bonjour"   (translated)
messages("farewell")   // "Goodbye"   (from base)
messages("nav.home")   // "Accueil"   (translated)
messages("nav.about")  // "About"     (from base)

Installation

2026-06-08T11:57:37.800272439Z

hocon is a pure-Scala library with no native dependencies, so there is nothing to install at the system level — just add it to your build.

Note

hocon is under active development. The parser, the untyped Config API, object merging, substitutions, value concatenation, and durations/sizes are in place and tested on all three platforms; include directives and a typed decoder are on the roadmap.

Requirements

Scala 3
sbt
For Scala.js / Scala Native targets: the usual sbt-scalajs / sbt-scala-native plugins

No java.* dependency is used in the core, and there are no native libraries to link.

Add the dependency

hocon cross-publishes for the JVM, Scala.js, and Scala Native. Use the %%% operator so sbt picks the right artifact for each platform:

libraryDependencies += "io.github.edadma" %%% "hocon" % "0.0.1"

In a crossProject build the single line covers every target:

lazy val app = crossProject(JVMPlatform, JSPlatform, NativePlatform)
  .settings(
    libraryDependencies += "io.github.edadma" %%% "hocon" % "0.0.1",
  )

From source

To track the latest changes, you can depend on hocon as a source dependency instead. Clone it next to your project:

git clone https://github.com/edadma/hocon.git

and reference the cross-built module by relative path in your build.sbt:

dependsOn(ProjectRef(file("../hocon"), "hocon"))

Verify the setup

hocon’s own suite is pure Scala and runs headlessly on every platform:

sbt hoconJVM/test
sbt hoconJS/test
sbt hoconNative/test

All three run the identical tests — that cross-platform parity is the whole point of the library. Continue to the quick start to parse a config.

The HOCON format

2026-06-08T11:57:37.800272439Z

HOCON is a superset of JSON: every JSON document is valid HOCON, but HOCON adds comments, optional quoting, optional commas, and a handful of conveniences that make hand-written config pleasant. This page covers the syntax hocon parses today.

Objects and fields

The top-level braces are optional, and a field is a key, a separator (= or :), and a value:

name = "Roamer"
version : "1.0"

= and : are interchangeable. Fields are separated by a newline or a comma; a trailing comma is allowed:

a = 1, b = 2
c = 3
xs = [1, 2, 3,]

When a value is an object, the separator may be omitted entirely:

window {
  width  = 1024
  height = 768
}

Comments

Both # and // start a comment that runs to the end of the line:

# a full-line comment
port = 8080   // a trailing comment

Values

hocon recognizes the JSON value types plus unquoted strings:

string  = "quoted text"
bare    = an-unquoted-string
number  = 8080
float   = 1.5
flag    = true
empty   = null
list    = [1, "two", true]
nested  = { a = 1, b = 2 }

true, false, and null are keywords; anything matching a number literal is a number; everything else is a string.

Quoting

Note

HOCON allows unquoted strings, but forbids these characters inside them: $ " { } [ ] : = , + # ^ ? ! @ * & `. Most natural-language strings hit one of them, so quote your message strings. hocon raises a parse error pointing at the offending character rather than guessing — this is spec-correct behavior.

Bare words are convenient for identifiers, numeric values, and simple paths (localhost, recent-files, 8080). For anything with punctuation, quote it.

String escapes

Quoted strings support the JSON escapes — \", \\, \/, \n, \t, \r, \b, \f, and \uXXXX:

path    = "C:\\Users\\Ada"
caption = "line one\nline two"
heart   = "❤"

Triple-quoted strings are raw — no escapes are processed and newlines are kept verbatim, which is handy for embedded text:

banner = """
  Welcome to Roamer.
  Press ? for help.
"""

Path-expression keys

A key may be a dotted path, which expands into nested objects. These two documents are equivalent:

a.b.c = value

a { b { c = value } }

Keys that target the same object merge, so you can group related settings flatly:

cart.items   = "{count} items"
cart.empty   = "Your cart is empty"

resolves to a cart object with both items and empty.

Arrays

Array elements are separated by commas or newlines, with an optional trailing comma, and may be any value type — including objects and nested arrays:

ports = [
  8080
  8081
  8082,
]

users = [
  { name = "Ada",  admin = true  },
  { name = "Alan", admin = false },
]

Substitutions

${path} references another value, and ${?path} is its optional form. They resolve against the merged document, so they are order-independent:

host = localhost
url  = ${host}        # → "localhost"

See the substitutions guide for the full rules — environment fallback, object copying, and cycle detection.

Value concatenation

Several pieces written on one line with only whitespace between them concatenate into a single value. Strings, numbers, booleans, and substitutions join into one string, with the interior whitespace preserved and the ends trimmed:

host = example.com
port = 8080
url  = "http://"${host}":"${port}   # → "http://example.com:8080"
full = first   middle  last         # → "first   middle  last"

Arrays concatenate element-wise, and objects deep-merge left to right:

xs   = [1, 2] [3, 4]                 # → [1, 2, 3, 4]
conf = ${defaults} { retries = 5 }   # the defaults object with retries overridden

Mixing kinds that cannot combine — an object or array joined with a string — raises a HoconConcatException.

Durations and sizes

A value can be read as a time duration or a memory size with the dedicated getters; in the source it is just a number with a unit suffix (an optional space is allowed):

timeout   = 10s
poll      = 500ms
linger    = 5 minutes
cache     = 512K
max-upload = 10MB

getDuration returns a cross-platform FiniteDuration; getBytes returns a Long. Duration units are ns, us, ms, s, m, h, d (and their long spellings), with a bare number read as milliseconds. Size units distinguish powers of 1024 (K, Ki, KiB, …) from powers of 1000 (kB, MB, …), with a bare number read as bytes. See the Config reference.

Not yet supported

include directives — pulling in other files — are on the roadmap.

Because unquoted strings forbid : and // starts a comment, URLs must be quoted (url = "https://example.com") — this matches the reference implementation.

Config

2026-06-08T11:57:37.800272439Z

Config is an immutable, untyped view over a parsed HOCON document. You obtain one from Hocon.parse, navigate it by dot-separated path, and read typed values with the getters below.

Parsing and combining

These live on the Hocon object.

Method	Returns	Description
`Hocon.parse(input: String)`	`Config`	Parse HOCON source and resolve `${...}` substitutions. Throws `ParseError` on a syntax error.
`Hocon.parse(input: String, env: EnvSource)`	`Config`	As above, falling back to `env` for substitutions absent from the document.
`Hocon.load(configs: Config*)`	`Config`	Merge configs so that later arguments win. No arguments → the empty config.

EnvSource is the seam substitutions use for environment fallback. The default is EnvSource.empty; build one from a map with EnvSource.fromMap(...), or implement the single-method trait to wire in the real environment. See the substitutions guide.

import io.github.edadma.hocon.*

val config = Hocon.parse("""a = 1, b { c = 2 }""")

Reading values

Paths are dot-separated (a.b.c). Each getter throws MissingPathException when the path is absent or null, and WrongTypeException when the value is the wrong shape.

Method	Returns	Notes
`getString(path)`	`String`	Numbers and booleans are returned as their text.
`getInt(path)`	`Int`	Parses the numeric literal.
`getLong(path)`	`Long`
`getDouble(path)`	`Double`
`getBoolean(path)`	`Boolean`	Also accepts the strings `yes`/`no`/`on`/`off`.
`getConfig(path)`	`Config`	The sub-object at `path`.
`getList(path)`	`List[ConfigValue]`	The raw array elements.
`getStringList(path)`	`List[String]`	Each element coerced to string.
`getDuration(path)`	`FiniteDuration`	A HOCON duration (`10s`, `5 minutes`); a bare number is milliseconds.
`getBytes(path)`	`Long`	A HOCON size in bytes (`512K`, `10MB`); powers of 1024 and 1000 are distinguished.
`getValue(path)`	`ConfigValue`	The raw value node, whatever its type.

config.getInt("a")          // 1
config.getInt("b.c")        // 2
config.getConfig("b").getInt("c")  // 2

Durations and sizes

getDuration reads a HOCON time value into a cross-platform scala.concurrent.duration.FiniteDuration. Units are ns, us, ms, s, m, h, d and their long spellings; a number with no unit is read as milliseconds.

getBytes reads a HOCON memory size into a Long count of bytes. Powers-of-1024 units (K, Ki, KiB, …) and powers-of-1000 units (kB, MB, …) are distinguished per the spec; a bare number is a byte count, and a fractional quantity truncates.

val c = Hocon.parse("timeout = 30s, cache = 512K")
c.getDuration("timeout")    // 30.seconds
c.getBytes("cache")         // 524288

Optional access

hasPath reports whether a path resolves to a present, non-null value. Each getter has an *Opt variant that returns None instead of throwing on a missing path:

Method	Returns
`hasPath(path)`	`Boolean`
`getStringOpt(path)`	`Option[String]`
`getIntOpt(path)`	`Option[Int]`
`getLongOpt(path)`	`Option[Long]`
`getDoubleOpt(path)`	`Option[Double]`
`getBooleanOpt(path)`	`Option[Boolean]`
`getConfigOpt(path)`	`Option[Config]`
`getListOpt(path)`	`Option[List[ConfigValue]]`
`getDurationOpt(path)`	`Option[FiniteDuration]`
`getBytesOpt(path)`	`Option[Long]`

config.hasPath("b.c")        // true
config.getStringOpt("nope")  // None

Merging

Method	Returns	Description
`withFallback(other: Config)`	`Config`	This config wins; `other` supplies defaults for keys this config lacks. Objects merge recursively; arrays and scalars replace.

See the merging guide for the full semantics.

The value tree

getValue and getList hand back ConfigValue nodes — the raw, untyped tree:

ConfigObject(fields: Map[String, ConfigValue])
ConfigArray(elements: List[ConfigValue])
ConfigString(value: String)
ConfigNumber(raw: String) — the original literal text, parsed on demand
ConfigBoolean(value: Boolean)
ConfigNull

Config.root exposes the top-level ConfigObject directly.

Exceptions

All errors extend HoconException:

ParseError(message, line, col) — a syntax error, with 1-based source position.
MissingPathException(path) — nothing at the requested path (or it is null).
WrongTypeException(path, expected, found) — the value is the wrong type for the getter.
UnresolvedSubstitutionException(path) — a required ${path} found in neither the config nor the environment.
CircularReferenceException(chain) — substitutions reference each other in a cycle.
HoconConcatException(message) — a value concatenation mixes incompatible kinds, such as an object or array joined with a string.