cueconfig

README

cueconfig: use CUE to configure your Go programs

Package cueconfig provides an API designed to make it straightforward to use the CUE language as a configuration format for Go programs.

It provides a single entry point, Load, which is very roughly equivalent to json.Unmarshal. It loads a configuration file (or directory) from disk and unmarshals it into a Go value.

Optionally, Load can be provided with a CUE schema to verify the configuration before unmarshaling into the Go value, a set of default values to apply after any user-specified defaults, and some runtime-defined values to be made available to the configuration.

There is a full example in the package documentation.

Documentation

Overview

Package `cueconfig` provides an API designed to make it straightforward to use the CUE language (see https://cuelang.org) as a configuration format for Go programs.

Index

• func Load(configFilePath string, schema, defaults []byte, runtime any, dest any) error

Examples

• Load

Functions

func Load

func Load(configFilePath string, schema, defaults []byte, runtime any, dest any) error

Load loads the CUE configuration at the file or CUE package directory configFilePath. If the file does not exist, an os.IsNotExist error is returned.

The schema for the user configuration is given in schema. Usually this will come from a CUE file embedded in the binary by the caller. If it's empty then any configuration data will be allowed.

The user configuration is first read and unified with the schema. Then if runtime is non-nil, it is unified with the resulting value, thus providing the user configuration with any desired runtime values (e.g. environment variables).

Then the result is finalised (applying any user-specified defaults), then unified with the CUE contained in the defaults argument. This allows the program to specify default values independently from the user.

The result is unmarshaled into the Go value pointed to by dest using cue.Value.Decode (similar to json.Unmarshal).

Example

package main

import (
	"encoding/json"
	"fmt"

	"github.com/cue-exp/cueconfig"
)

type exampleConfig struct {
	Foo int                    `json:"foo"`
	Bar map[string]*exampleBar `json:"bar"`
}

type exampleBar struct {
	Amount    float64 `json:"amount"`
	Something bool    `json:"something"`
	Path      string  `json:"path"`
}

type exampleRuntime struct {
	CurrentDirectory string `json:"currentDirectory"`
}

func main() {
	// In this example, we use the example.cue from the package
	// but in practice this would be located whereever you'd want
	// your program's configuration file.
	configFile := "example.cue"

	// This is a placeholder for any runtime values provided
	// as input to the configuration.
	runtime := struct {
		Runtime exampleRuntime `json:"runtime"`
	}{
		Runtime: exampleRuntime{
			CurrentDirectory: "/path/to/current/directory",
		},
	}
	// Load the configuration into the Go value cfg.
	var cfg exampleConfig
	if err := cueconfig.Load(configFile, exampleSchema, exampleDefaults, runtime, &cfg); err != nil {
		fmt.Printf("%v\n", err)
		return
	}
	// This is a placeholder for anything that the program might actually do
	// with the configuration.
	data, _ := json.MarshalIndent(cfg, "", "\t")
	fmt.Printf("%s\n", data)
}

// exampleSchema holds the schema for the program's configuration.
// It would be conventional to include it as an embedded file,
// but we've included it inline here so that it shows up directly
// in the example.
var exampleSchema = []byte(`
package example

foo?: int
bar?: [string]: #Bar

#Bar: {
	amount?: number
	something?: bool
	path?: string
}

// runtime is provided by the program, not the user.
runtime?: #Runtime
#Runtime: {
	currentDirectory: string
}
`)

// exampleDefaults holds any default values for the program
// to apply. As with [exampleSchema] above, it would conventionally
// be taken from an embedded file.
var exampleDefaults = []byte(`
runtime: _
foo: *100 | _
bar: [_]: {
	amount: *1.5 | _
	something: *false | _
	path: *runtime.currentDirectory | _
}
`)

Output:

{
	"foo": 1,
	"bar": {
		"a": {
			"amount": 1.5,
			"something": false,
			"path": "/path/to/current/directory"
		}
	}
}