moonconf

#The tree

test {
  let node = @moonconf.Node::map([
    ("db", @moonconf.Node::map([("host", @moonconf.Node::str("localhost", "app.ini"))], "app.ini")),
  ], "app.ini")
  assert_eq(node.need_text("db.host"), "localhost")
}

• A value is null, boolean, integer, real, text, a list, or a mapping. An integer stays an integer, so 8080 is not printed back as 8080.0.
• A mapping remembers the order its members were written in, so a file written back is the file that was read.
• Every value carries the source it came from and the position in it, which is what an error message needs to be useful.

test {
  let node = @moonconf.Node::map([
    ("servers", @moonconf.Node::seq([
      @moonconf.Node::str("one", "app.conf"),
      @moonconf.Node::str("two", "app.conf"),
    ], "app.conf")),
  ], "app.conf")
  assert_eq(node.need_text("servers.1"), "two")
}

#Layers

test {
  let defaults = @moonconf.Node::map([
    ("port", @moonconf.Node::num(5432, "defaults")),
  ], "defaults")
  let file = @moonconf.Node::map([
    ("port", @moonconf.Node::num(6432, "app.ini")),
  ], "app.ini")
  let merged = @moonconf.merge([
    @moonconf.Source::new(@moonconf.File, "app.ini", file),
    @moonconf.Source::new(@moonconf.Default, "defaults", defaults),
  ])
  assert_eq(merged.need_int("port"), 6432L)
}

• The tiers run Default, File, Env, Override. The wins field of Knobs lists them weakest first, so the stack can be reversed — a patch read under a document — without touching a parser.
• Mappings merge member by member: a later file that sets one key under db keeps the rest of the earlier file's db. Lists replace, because a list is one decision.
• A disagreement is Clash::Last (the default), Clash::First, or Clash::Refuse, which reports both positions.

#Formats

#INI

[DEFAULT]
host = localhost

[db]
port = 5432
url = postgres://%(host)s/db

test {
  let doc = @ini.parse("[db]\nport = 5432\nurl = postgres://localhost/db\n")
  assert_eq(doc.get("db", "url"), "postgres://localhost/db")
  assert_eq(doc.sections(), ["db"])
}

#Properties

# a note
db.host=localhost
greeting=\u4f60\u597d

test {
  let doc = @props.parse("db.host=localhost\n")
  assert_eq(doc.get("db.host"), Some("localhost"))
}

#.env

export HOST=localhost
DSN="postgres://${HOST}/app"
GREETING='it\'s here'

test {
  let env = @dotenv.load("HOST=localhost\nDSN=\"postgres://${HOST}/app\"\n")
  assert_eq(env.get("DSN"), Some("postgres://localhost/app"))
}

#POSIX expansion

test {
  let vars = @expand.Vars::of_map(Map([("PORT", "8080")]))
  assert_eq(@expand.expand(":${PORT:-80}", vars), ":8080")
  assert_eq(@expand.expand("${MISSING:-fallback}", vars), "fallback")
}

#HOCON

include "base.conf"

db.name = app
url = "postgres://${db.host}:${db.port}/${db.name}"
hosts = [a, b]
hosts += c
cache = ${?optional}

test {
  let doc = @hocon.parse("db { host = localhost }\nurl = \"pg://${db.host}/x\"\n")
  assert_eq(doc.need_text("url"), "pg://localhost/x")
}

• The same name twice merges: objects member by member, arrays end to end, and anything else keeps the later one.
• ${a.b} is the value at that path; ${?a.b} is that value when it is there and nothing at all when it is not, so a field that depends on an unset name simply is not there.
• include "x" asks the caller's read for the text. include url("…") and include classpath("…") ask the same function, told which wrapper was written, so a caller that can fetch a URL can answer all three. Nothing is fetched here: reading is I/O, and this package does none.
• A value written twice may refer to itself: a = 1 then a = ${a} 2 is 1 2, and db = ${db} { port = 2 } overrides one member of db and keeps the rest.
• A name the document does not define is looked up in the process environment, so path = ${HOME}/bin works without the caller arranging anything. plain reads a document on its own, for a test or a machine-independent build.
• A cycle that is not a definition building on itself is reported as one, rather than resolved into nonsense.

#HCL

region = var.region
name   = upper("web")

server "web" {
  port = 80 + 1
}

test {
  let names = @moonconf.Node::map([("region", @moonconf.Node::str("eu-west-1", "vars"))], "vars")
  let body = @hcl.parse("region = var.region\n", context=@hcl.Context::new().bind("var", names))
  assert_eq(body.get("region").unwrap().text(), "eu-west-1")
}

#Binding

test {
  let model = @moonmodel.Model::new("Db", [
    @moonmodel.Field::new("host", @moonmodel.Type::Text, required=true),
    @moonmodel.Field::new("port", @moonmodel.Type::Int, required=true),
    @moonmodel.Field::new("pool", @moonmodel.Type::Int, default=Json::number(4.0)),
  ])
  let tree = @moonconf.Node::map([
    ("host", @moonconf.Node::str("localhost", "app.ini")),
    ("port", @moonconf.Node::str("5432", "env")),
  ], "app.ini")
  assert_eq(
    @moonconf.bind(tree, model),
    @json.parse("{\"host\":\"localhost\",\"port\":5432,\"pool\":4}"),
  )
}

#Errors

db.port (env@1:1): want integer, got text

• path names the field, as a dotted path.
• want and got name the shapes, in the words a person would use.
• at is the position in the source, and source is the name the caller gave it.

#API

#moonconf

#moonconf/expand

#moonconf/ini

#moonconf/props

#moonconf/dotenv

#moonconf/hocon

#moonconf/hcl

#License