README
¶
TOML stands for Tom's Obvious, Minimal Language. This Go package provides a
reflection interface similar to Go's standard library json and xml packages.
Compatible with TOML version v1.0.0.
Documentation: https://godocs.io/git.sr.ht/~pingoo/stdx/toml
See the releases page for a
changelog; this information is also in the git tag annotations (e.g. git show v0.4.0).
This library requires Go 1.13 or newer; add it to your go.mod with:
% go get git.sr.ht/~pingoo/stdx/toml@latest
It also comes with a TOML validator CLI tool:
% go install git.sr.ht/~pingoo/stdx/toml/cmd/tomlv@latest
% tomlv some-toml-file.toml
Examples
For the simplest example, consider some TOML file as just a list of keys and values:
Age = 25
Cats = [ "Cauchy", "Plato" ]
Pi = 3.14
Perfection = [ 6, 28, 496, 8128 ]
DOB = 1987-07-05T05:45:00Z
Which can be decoded with:
type Config struct {
Age int
Cats []string
Pi float64
Perfection []int
DOB time.Time
}
var conf Config
_, err := toml.Decode(tomlData, &conf)
You can also use struct tags if your struct field name doesn't map to a TOML key value directly:
some_key_NAME = "wat"
type TOML struct {
ObscureKey string `toml:"some_key_NAME"`
}
Beware that like other decoders only exported fields are considered when encoding and decoding; private fields are silently ignored.
Using the Marshaler and encoding.TextUnmarshaler interfaces
Here's an example that automatically parses values in a mail.Address:
contacts = [
"Donald Duck <donald@duckburg.com>",
"Scrooge McDuck <scrooge@duckburg.com>",
]
Can be decoded with:
// Create address type which satisfies the encoding.TextUnmarshaler interface.
type address struct {
*mail.Address
}
func (a *address) UnmarshalText(text []byte) error {
var err error
a.Address, err = mail.ParseAddress(string(text))
return err
}
// Decode it.
func decode() {
blob := `
contacts = [
"Donald Duck <donald@duckburg.com>",
"Scrooge McDuck <scrooge@duckburg.com>",
]
`
var contacts struct {
Contacts []address
}
_, err := toml.Decode(blob, &contacts)
if err != nil {
log.Fatal(err)
}
for _, c := range contacts.Contacts {
fmt.Printf("%#v\n", c.Address)
}
// Output:
// &mail.Address{Name:"Donald Duck", Address:"donald@duckburg.com"}
// &mail.Address{Name:"Scrooge McDuck", Address:"scrooge@duckburg.com"}
}
To target TOML specifically you can implement UnmarshalTOML TOML interface in
a similar way.
More complex usage
See the _example/ directory for a more complex example.
Documentation
¶
Overview ¶
Package toml implements decoding and encoding of TOML files.
This package supports TOML v1.0.0, as listed on https://toml.io
There is also support for delaying decoding with the Primitive type, and querying the set of keys in a TOML document with the MetaData type.
The git.sr.ht/~pingoo/stdx/toml/cmd/tomlv package implements a TOML validator, and can be used to verify if TOML document is valid. It can also be used to print the type of each key.
Example (StrictDecoding) ¶
Example StrictDecoding shows how to detect if there are keys in the TOML document that weren't decoded into the value given. This is useful for returning an error to the user if they've included extraneous fields in their configuration.
package main
import (
"fmt"
"log"
"git.sr.ht/~pingoo/stdx/toml"
)
func main() {
var blob = `
key1 = "value1"
key2 = "value2"
key3 = "value3"
`
var conf struct {
Key1 string
Key3 string
}
md, err := toml.Decode(blob, &conf)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Undecoded keys: %q\n", md.Undecoded())
}
Output: Undecoded keys: ["key2"]
Example (UnmarshalTOML) ¶
Example UnmarshalTOML shows how to implement a struct type that knows how to unmarshal itself. The struct must take full responsibility for mapping the values passed into the struct. The method may be used with interfaces in a struct in cases where the actual type is not known until the data is examined.
package main
import (
"fmt"
"log"
"git.sr.ht/~pingoo/stdx/toml"
)
type order struct {
parts parts
}
type parts []part
type part interface {
Name() string
}
type valve struct {
Type string
ID string
Size float32
Rating int
}
func (v *valve) Name() string {
return fmt.Sprintf("VALVE: %s", v.ID)
}
type pipe struct {
Type string
ID string
Length float32
Diameter int
}
func (p *pipe) Name() string {
return fmt.Sprintf("PIPE: %s", p.ID)
}
type cable struct {
Type string
ID string
Length int
Rating float32
}
func (c *cable) Name() string {
return fmt.Sprintf("CABLE: %s", c.ID)
}
func (o *order) UnmarshalTOML(data interface{}) error {
d, _ := data.(map[string]interface{})
parts, _ := d["parts"].([]map[string]interface{})
for _, p := range parts {
typ, _ := p["type"].(string)
id, _ := p["id"].(string)
switch p["type"] {
case "valve":
size := float32(p["size"].(float64))
rating := int(p["rating"].(int64))
valve := &valve{
Type: typ,
ID: id,
Size: size,
Rating: rating,
}
o.parts = append(o.parts, valve)
case "pipe":
length := float32(p["length"].(float64))
diameter := int(p["diameter"].(int64))
pipe := &pipe{
Type: typ,
ID: id,
Length: length,
Diameter: diameter,
}
o.parts = append(o.parts, pipe)
case "cable":
length := int(p["length"].(int64))
rating := float32(p["rating"].(float64))
cable := &cable{
Type: typ,
ID: id,
Length: length,
Rating: rating,
}
o.parts = append(o.parts, cable)
}
}
return nil
}
func main() {
blob := `
[[parts]]
type = "valve"
id = "valve-1"
size = 1.2
rating = 4
[[parts]]
type = "valve"
id = "valve-2"
size = 2.1
rating = 5
[[parts]]
type = "pipe"
id = "pipe-1"
length = 2.1
diameter = 12
[[parts]]
type = "cable"
id = "cable-1"
length = 12
rating = 3.1
`
// See example_test.go in the source for the implementation of the order
// type.
o := &order{}
err := toml.Unmarshal([]byte(blob), o)
if err != nil {
log.Fatal(err)
}
fmt.Println(len(o.parts))
for _, part := range o.parts {
fmt.Println(part.Name())
}
}
Output:
Example (Unmarshaler) ¶
Example Unmarshaler shows how to decode TOML strings into your own custom data type.
package main
import (
"fmt"
"log"
"net/mail"
"git.sr.ht/~pingoo/stdx/toml"
)
type address struct{ *mail.Address }
func (a *address) UnmarshalText(text []byte) error {
var err error
a.Address, err = mail.ParseAddress(string(text))
return err
}
func main() {
blob := `
contacts = [
"Donald Duck <donald@duckburg.com>",
"Scrooge McDuck <scrooge@duckburg.com>",
]
`
var contacts struct {
// Implementation of the address type:
//
// type address struct{ *mail.Address }
//
// func (a *address) UnmarshalText(text []byte) error {
// var err error
// a.Address, err = mail.ParseAddress(string(text))
// return err
// }
Contacts []address
}
_, err := toml.Decode(blob, &contacts)
if err != nil {
log.Fatal(err)
}
for _, c := range contacts.Contacts {
fmt.Printf("%#v\n", c.Address)
}
}
Output: &mail.Address{Name:"Donald Duck", Address:"donald@duckburg.com"} &mail.Address{Name:"Scrooge McDuck", Address:"scrooge@duckburg.com"}
Index ¶
- func PrimitiveDecode(primValue Primitive, v interface{}) errordeprecated
- func Unmarshal(data []byte, v interface{}) error
- type Decoder
- type Encoder
- type Key
- type Marshaler
- type MetaData
- type ParseError
- type Position
- type Primitive
- type TextMarshalerdeprecated
- type TextUnmarshalerdeprecated
- type Unmarshaler
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PrimitiveDecode
deprecated
Types ¶
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder decodes TOML data.
TOML tables correspond to Go structs or maps (dealer's choice – they can be used interchangeably).
TOML table arrays correspond to either a slice of structs or a slice of maps.
TOML datetimes correspond to Go time.Time values. Local datetimes are parsed in the local timezone.
time.Duration types are treated as nanoseconds if the TOML value is an integer, or they're parsed with time.ParseDuration() if they're strings.
All other TOML types (float, string, int, bool and array) correspond to the obvious Go types.
An exception to the above rules is if a type implements the TextUnmarshaler interface, in which case any primitive TOML value (floats, strings, integers, booleans, datetimes) will be converted to a []byte and given to the value's UnmarshalText method. See the Unmarshaler example for a demonstration with email addresses.
Key mapping ¶
TOML keys can map to either keys in a Go map or field names in a Go struct. The special `toml` struct tag can be used to map TOML keys to struct fields that don't match the key name exactly (see the example). A case insensitive match to struct names will be tried if an exact match can't be found.
The mapping between TOML values and Go values is loose. That is, there may exist TOML values that cannot be placed into your representation, and there may be parts of your representation that do not correspond to TOML values. This loose mapping can be made stricter by using the IsDefined and/or Undecoded methods on the MetaData returned.
This decoder does not handle cyclic types. Decode will not terminate if a cyclic type is passed.
type Encoder ¶
type Encoder struct {
// String to use for a single indentation level; default is two spaces.
Indent string
// contains filtered or unexported fields
}
Encoder encodes a Go to a TOML document.
The mapping between Go values and TOML values should be precisely the same as for the Decode* functions.
time.Time is encoded as a RFC 3339 string, and time.Duration as its string representation.
The toml.Marshaler and encoder.TextMarshaler interfaces are supported to encoding the value as custom TOML.
If you want to write arbitrary binary data then you will need to use something like base64 since TOML does not have any binary types.
When encoding TOML hashes (Go maps or structs), keys without any sub-hashes are encoded first.
Go maps will be sorted alphabetically by key for deterministic output.
The toml struct tag can be used to provide the key name; if omitted the struct field name will be used. If the "omitempty" option is present the following value will be skipped:
- arrays, slices, maps, and string with len of 0
- struct with all zero values
- bool false
If omitzero is given all int and float types with a value of 0 will be skipped.
Encoding Go values without a corresponding TOML representation will return an error. Examples of this includes maps with non-string keys, slices with nil elements, embedded non-struct types, and nested slices containing maps or structs. (e.g. [][]map[string]string is not allowed but []map[string]string is okay, as is []map[string][]string).
NOTE: only exported keys are encoded due to the use of reflection. Unexported keys are silently discarded.
func (*Encoder) Encode ¶
Encode writes a TOML representation of the Go value to the Encoder's writer.
An error is returned if the value given cannot be encoded to a valid TOML document.
Example ¶
package main
import (
"bytes"
"fmt"
"log"
"time"
"git.sr.ht/~pingoo/stdx/toml"
)
func main() {
var (
date, _ = time.Parse(time.RFC822, "14 Mar 10 18:00 UTC")
buf = new(bytes.Buffer)
)
err := toml.NewEncoder(buf).Encode(map[string]interface{}{
"date": date,
"counts": []int{1, 1, 2, 3, 5, 8},
"hash": map[string]string{
"key1": "val1",
"key2": "val2",
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(buf.String())
}
Output: counts = [1, 1, 2, 3, 5, 8] date = 2010-03-14T18:00:00Z [hash] key1 = "val1" key2 = "val2"
type Key ¶
type Key []string
Key represents any TOML key, including key groups. Use (MetaData).Keys to get values of this type.
type Marshaler ¶
Marshaler is the interface implemented by types that can marshal themselves into valid TOML.
type MetaData ¶
type MetaData struct {
// contains filtered or unexported fields
}
MetaData allows access to meta information about TOML data that's not accessible otherwise.
It allows checking if a key is defined in the TOML data, whether any keys were undecoded, and the TOML type of a key.
func Decode ¶
Decode the TOML data in to the pointer v.
See the documentation on Decoder for a description of the decoding process.
Example ¶
package main
import (
"fmt"
"log"
"time"
"git.sr.ht/~pingoo/stdx/toml"
)
func main() {
tomlBlob := `
# Some comments.
[alpha]
ip = "10.0.0.1"
[alpha.config]
Ports = [ 8001, 8002 ]
Location = "Toronto"
Created = 1987-07-05T05:45:00Z
[beta]
ip = "10.0.0.2"
[beta.config]
Ports = [ 9001, 9002 ]
Location = "New Jersey"
Created = 1887-01-05T05:55:00Z
`
type (
serverConfig struct {
Ports []int
Location string
Created time.Time
}
server struct {
IP string `toml:"ip,omitempty"`
Config serverConfig `toml:"config"`
}
servers map[string]server
)
var config servers
_, err := toml.Decode(tomlBlob, &config)
if err != nil {
log.Fatal(err)
}
for _, name := range []string{"alpha", "beta"} {
s := config[name]
fmt.Printf("Server: %s (ip: %s) in %s created on %s\n",
name, s.IP, s.Config.Location,
s.Config.Created.Format("2006-01-02"))
fmt.Printf("Ports: %v\n", s.Config.Ports)
}
}
Output: Server: alpha (ip: 10.0.0.1) in Toronto created on 1987-07-05 Ports: [8001 8002] Server: beta (ip: 10.0.0.2) in New Jersey created on 1887-01-05 Ports: [9001 9002]
func DecodeFS ¶
DecodeFS is just like Decode, except it will automatically read the contents of the file at `path` from a fs.FS instance.
func DecodeFile ¶
DecodeFile is just like Decode, except it will automatically read the contents of the file at path and decode it for you.
func DecodeReader
deprecated
func (*MetaData) IsDefined ¶
IsDefined reports if the key exists in the TOML data.
The key should be specified hierarchically, for example to access the TOML key "a.b.c" you would use IsDefined("a", "b", "c"). Keys are case sensitive.
Returns false for an empty key.
func (*MetaData) Keys ¶
Keys returns a slice of every key in the TOML data, including key groups.
Each key is itself a slice, where the first element is the top of the hierarchy and the last is the most specific. The list will have the same order as the keys appeared in the TOML data.
All keys returned are non-empty.
func (*MetaData) PrimitiveDecode ¶
PrimitiveDecode is just like the other `Decode*` functions, except it decodes a TOML value that has already been parsed. Valid primitive values can *only* be obtained from values filled by the decoder functions, including this method. (i.e., `v` may contain more `Primitive` values.)
Meta data for primitive values is included in the meta data returned by the `Decode*` functions with one exception: keys returned by the Undecoded method will only reflect keys that were decoded. Namely, any keys hidden behind a Primitive will be considered undecoded. Executing this method will update the undecoded keys in the meta data. (See the example.)
Example ¶
package main
import (
"fmt"
"log"
"git.sr.ht/~pingoo/stdx/toml"
)
func main() {
tomlBlob := `
ranking = ["Springsteen", "J Geils"]
[bands.Springsteen]
started = 1973
albums = ["Greetings", "WIESS", "Born to Run", "Darkness"]
[bands."J Geils"]
started = 1970
albums = ["The J. Geils Band", "Full House", "Blow Your Face Out"]
`
type (
band struct {
Started int
Albums []string
}
classics struct {
Ranking []string
Bands map[string]toml.Primitive
}
)
// Do the initial decode; reflection is delayed on Primitive values.
var music classics
md, err := toml.Decode(tomlBlob, &music)
if err != nil {
log.Fatal(err)
}
// MetaData still includes information on Primitive values.
fmt.Printf("Is `bands.Springsteen` defined? %v\n",
md.IsDefined("bands", "Springsteen"))
// Decode primitive data into Go values.
for _, artist := range music.Ranking {
// A band is a primitive value, so we need to decode it to get a real
// `band` value.
primValue := music.Bands[artist]
var aBand band
err = md.PrimitiveDecode(primValue, &aBand)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s started in %d.\n", artist, aBand.Started)
}
// Check to see if there were any fields left undecoded. Note that this
// won't be empty before decoding the Primitive value!
fmt.Printf("Undecoded: %q\n", md.Undecoded())
}
Output: Is `bands.Springsteen` defined? true Springsteen started in 1973. J Geils started in 1970. Undecoded: []
func (*MetaData) Type ¶
Type returns a string representation of the type of the key specified.
Type will return the empty string if given an empty key or a key that does not exist. Keys are case sensitive.
func (*MetaData) Undecoded ¶
Undecoded returns all keys that have not been decoded in the order in which they appear in the original TOML document.
This includes keys that haven't been decoded because of a Primitive value. Once the Primitive value is decoded, the keys will be considered decoded.
Also note that decoding into an empty interface will result in no decoding, and so no keys will be considered decoded.
In this sense, the Undecoded keys correspond to keys in the TOML document that do not have a concrete type in your representation.
type ParseError ¶
type ParseError struct {
Message string // Short technical message.
Usage string // Longer message with usage guidance; may be blank.
Position Position // Position of the error
LastKey string // Last parsed key, may be blank.
Line int // Line the error occurred. Deprecated: use Position.
// contains filtered or unexported fields
}
ParseError is returned when there is an error parsing the TOML syntax.
For example invalid syntax, duplicate keys, etc.
In addition to the error message itself, you can also print detailed location information with context by using ErrorWithPosition():
toml: error: Key 'fruit' was already created and cannot be used as an array.
At line 4, column 2-7:
2 | fruit = []
3 |
4 | [[fruit]] # Not allowed
^^^^^
Furthermore, the ErrorWithUsage() can be used to print the above with some more detailed usage guidance:
toml: error: newlines not allowed within inline tables
At line 1, column 18:
1 | x = [{ key = 42 #
^
Error help:
Inline tables must always be on a single line:
table = {key = 42, second = 43}
It is invalid to split them over multiple lines like so:
# INVALID
table = {
key = 42,
second = 43
}
Use regular for this:
[table]
key = 42
second = 43
func (ParseError) Error ¶
func (pe ParseError) Error() string
func (ParseError) ErrorWithPosition ¶
func (pe ParseError) ErrorWithPosition() string
ErrorWithUsage() returns the error with detailed location context.
See the documentation on ParseError.
func (ParseError) ErrorWithUsage ¶
func (pe ParseError) ErrorWithUsage() string
ErrorWithUsage() returns the error with detailed location context and usage guidance.
See the documentation on ParseError.
type Position ¶
type Position struct {
Line int // Line number, starting at 1.
Start int // Start of error, as byte offset starting at 0.
Len int // Lenght in bytes.
}
Position of an error.
type Primitive ¶
type Primitive struct {
// contains filtered or unexported fields
}
Primitive is a TOML value that hasn't been decoded into a Go value.
This type can be used for any value, which will cause decoding to be delayed. You can use the PrimitiveDecode() function to "manually" decode these values.
NOTE: The underlying representation of a `Primitive` value is subject to change. Do not rely on it.
NOTE: Primitive values are still parsed, so using them will only avoid the overhead of reflection. They can be useful when you don't know the exact type of TOML data until runtime.
type TextMarshaler
deprecated
type TextMarshaler encoding.TextMarshaler
Deprecated: use encoding.TextMarshaler
type TextUnmarshaler
deprecated
type TextUnmarshaler encoding.TextUnmarshaler
Deprecated: use encoding.TextUnmarshaler
type Unmarshaler ¶
type Unmarshaler interface {
UnmarshalTOML(interface{}) error
}
Unmarshaler is the interface implemented by objects that can unmarshal a TOML description of themselves.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
toml-test-decoder
Command toml-test-decoder satisfies the toml-test interface for testing TOML decoders.
|
Command toml-test-decoder satisfies the toml-test interface for testing TOML decoders. |
|
toml-test-encoder
Command toml-test-encoder satisfies the toml-test interface for testing TOML encoders.
|
Command toml-test-encoder satisfies the toml-test interface for testing TOML encoders. |
|
tomlv
Command tomlv validates TOML documents and prints each key's type.
|
Command tomlv validates TOML documents and prints each key's type. |