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 ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Load ¶
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" } } }
Types ¶
This section is empty.
Source Files