README
¶
dhall-golang
Go bindings for the dhall configuration language.
Quick start
Here's a minimal example of how you might use dhall-golang to load a Dhall file into your own struct:
package main
import (
"fmt"
"github.com/philandstuff/dhall-golang/v6"
)
// Config can be a fairly arbitrary Go datatype. You would put your
// application configuration in this struct.
type Config struct {
Port int
Name string
}
func main() {
var config Config
err = dhall.UnmarshalFile("/path/to/config.dhall", &config)
if err != nil {
panic(err)
}
fmt.Printf("Loaded config: %#v\n", config)
}
Documentation
You can find more documentation in the dhall-golang godoc.
Development
This is a fairly standard Go project. It uses go modules, so no vendoring of dependencies is required.
Running the tests
git submodule update --init --recursive
go test ./...
go test -short ./... # skips long-running tests
Making changes to the PEG grammar
Dhall-golang uses pigeon to generate the parser source file
parser/internal/dhall.go from the PEG grammar at
parser/internal/dhall.peg. If you change the PEG grammar, you need
to first install the pigeon binary if you don't already have it:
# either outside a module directory, or with GO111MODULE=off
go get github.com/mna/pigeon
Then, to regenerate the parser:
go generate ./parser
Support
Issues and pull requests are welcome on this repository. If you have a question, you can ask it on the Dhall discourse.
Documentation
¶
Overview ¶
Package dhall implements routines for deserializing and evaluating Dhall configuration into Go data structures.
For more on the Dhall language, see https://dhall-lang.org/
If you have the following struct:
type Message struct {
Name string
Body string
Time int64
}
And a file called foo.dhall containing the following Dhall configuration:
{ Name = "Alice", Body = "Hello", Time = 1294706395881547000 }
You can deserialize the Dhall into the struct as follows (error handling skipped for brevity):
var m Message
dhallBytes, err := ioutil.ReadFile("foo.dhall")
err = dhall.Unmarshal(dhallBytes, &m)
This version supports Dhall standard 17.0.0, except that it doesn't support `using` directives.
Example ¶
package main
import (
"fmt"
"github.com/philandstuff/dhall-golang/v6"
)
// Message is the struct we want to unmarshal from Dhall
type Message struct {
Name string
Body string
Time int64
}
// dhallMessage is the Dhall source we want to unmarshal
const dhallMessage = `
{ Name = "Alice", Body = "Hello", Time = 1294706395881547000 }
`
func main() {
var m Message
err := dhall.Unmarshal([]byte(dhallMessage), &m)
if err != nil {
panic(err)
}
fmt.Printf("%+v", m)
}
Output: {Name:Alice Body:Hello Time:1294706395881547000}
Example (Function) ¶
package main
import (
"fmt"
"github.com/philandstuff/dhall-golang/v6"
)
// Config is the struct we want to unmarshal from Dhall
type Config struct {
Name string
// Dhall lets you unmarshal functions as well as data
Greet func(string) string
}
// configMessage is the Dhall source we want to unmarshal
const configMessage = `
{ Name = "Alice", Greet = λ(name : Text) → "Howdy, ${name}!" }
`
func main() {
// you can also unmarshal Dhall functions to Go functions
var greet func(string) string
err := dhall.Unmarshal([]byte(`λ(name : Text) → "Howdy, ${name}!"`), &greet)
if err != nil {
panic(err)
}
fmt.Println(greet("Alice"))
}
Output: Howdy, Alice!
Example (Nested) ¶
package main
import (
"fmt"
"github.com/philandstuff/dhall-golang/v6"
)
// NestedConfig is the struct we want to unmarshal from Dhall
type NestedConfig struct {
Name string
DBConfig struct {
Username string
Password string
}
}
const nestedDhallMessage = `
{ Name = "Alice", DBConfig = { Username = "foo", Password = "bar" } }
`
func main() {
var m NestedConfig
err := dhall.Unmarshal([]byte(nestedDhallMessage), &m)
if err != nil {
panic(err)
}
fmt.Printf("%+v", m)
}
Output: {Name:Alice DBConfig:{Username:foo Password:bar}}
Example (Tagged) ¶
package main
import (
"fmt"
"github.com/philandstuff/dhall-golang/v6"
)
// TaggedMessage is the struct we want to unmarshal from Dhall
type TaggedMessage struct {
Name string `dhall:"name"`
Body string `dhall:"entity"`
Time int64 `dhall:"instant"`
}
// dhallTaggedMessage is the Dhall source we want to unmarshal
const dhallTaggedMessage = `
{ name = "Alice", entity = "Hello", instant = 1294706395881547000 }
`
func main() {
var m TaggedMessage
err := dhall.Unmarshal([]byte(dhallTaggedMessage), &m)
if err != nil {
panic(err)
}
fmt.Printf("%+v", m)
}
Output: {Name:Alice Body:Hello Time:1294706395881547000}
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var JSONType core.Value = mkJSONType()
Functions ¶
func Unmarshal ¶
Unmarshal takes dhall input as a byte array and parses it, resolves imports, typechecks, evaluates, and unmarshals it into the given variable.
func UnmarshalFile ¶
UnmarshalFile takes dhall input from a file and parses it, resolves imports, typechecks, evaluates, and unmarshals it into the given variable.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package binary defines the CBOR representation of Dhall terms.
|
Package binary defines the CBOR representation of Dhall terms. |
|
Package core contains the core Dhall language implementation.
|
Package core contains the core Dhall language implementation. |
|
Package imports defines how to resolve Dhall imports.
|
Package imports defines how to resolve Dhall imports. |
|
Package internal contains internal names, not for use by library consumers.
|
Package internal contains internal names, not for use by library consumers. |
|
Package parser enables parsing Dhall source into Terms.
|
Package parser enables parsing Dhall source into Terms. |
|
Package term contains data types for Dhall terms.
|
Package term contains data types for Dhall terms. |
