src.d10.dev/gofigure

Package gofigure parses configuration files. An application might use this instead of parsing JSON, YAML, or many other alternatives.

Our primary goals include:

• Provide a human-friendly configuration file format.
• Minimize third-party dependencies.

Our definition of "human-friendly" is opinionated. It basically means a configuration file format that supports comments, and is not sensitive to whitespace or indentation.

The motivation to avoid third-party dependencies is to minimize the amount of code that needs to be audited, in particular for secure applications where the size of a software bill of materials may be a concern.

To accomplish these goals, the configuration syntax is based on the Go (golang) language. This allows us to use Go's parser, already part of the standard library, rather than third-party imports. And Go's syntax meets our standard for user-friendliness.

Example Configuration

The supported syntax supports, for example,

local = env {
  port: 8080,
  host: "127.0.0.1",
}

prod = env {
  port: 80,
  host: "0.0.0.0",
}

// environment tells the application which of the envs to use by default.
environment = local

Example Application Code

Gofigure provides a multiplexer, with a simple scheme in which a handler is called for each value in a configuration file.

A handler is called if it is the best match for a "path" in the configuration file. In the example above, "local = env {}" is a fully-qualified path that matchs only the first item, while "env" is a path that matches all the env{...} objects.

mux := gofigure.Mux{
  "env": gofigure.Object(handleEnv),
  // ...
}

Above, "env" is the path to match, HandleEnv is the application-provided handler function, and gofigure.Object instructs gofigure to unmarshal the value as an object. Under the hood, gofigure uses "encoding/json" for decoding into Go structs, and Object, Array, and Scalar tell gofigure what kind of value to expect.

// env is the Go struct to decode into
type env struct {
  Host string
  Port int
}

// handleEnv shows the signature of a handler function for env objects.
func handleEnv(r gofigure.Route, v env) error {...}

For each match in the configuration file, a handler is passed the full route and value. In this example, a route would be ["local", "=", "env", "{}"] and the same handler would be called again with a route starting "prod".