You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Andrew Gallant 3012a1dbe2
Merge pull request #230 from gregwebs/cmd-license-wtf
1 year ago
_examples Various formatting fixes. 80 cols. 4 years ago
cmd switch the licenses of the cmd to be the same as the root 1 year ago
.gitignore Ignore test binary. 5 years ago
.travis.yml Run .travis.yml against latest Go versions 3 years ago
COMPATIBLE update compatible version note 2 years ago
COPYING update copyright 2 years ago
Makefile Recompile when testing. 5 years ago
README.md Fix some outdated links and version numbers 2 years ago
decode.go Fix incorrect error message 3 years ago
decode_meta.go simplify return paths by removing 'else' block (golint) 3 years ago
decode_test.go Complete the testing for decoding datetime with UTC offset 2 years ago
doc.go update compatible version note 2 years ago
encode.go Spell it "newline" rather than "new line" 2 years ago
encode_test.go Remove usage of log in tests 3 years ago
encoding_types.go Various formatting fixes. 80 cols. 4 years ago
encoding_types_1.1.go Various formatting fixes. 80 cols. 4 years ago
lex.go Allow '+' in Datetime lexing 2 years ago
parse.go Merge remote-tracking branch 'ttacon/master' 2 years ago
session.vim initial commit. i think the lexer is good. 6 years ago
type_check.go Various formatting fixes. 80 cols. 4 years ago
type_fields.go Encoder: treat tagged anonymous structs as non-anonymous 3 years ago

README.md

TOML parser and encoder for Go with reflection

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. This package also supports the encoding.TextUnmarshaler and encoding.TextMarshaler interfaces so that you can define custom data representations. (There is an example of this below.)

Spec: https://github.com/toml-lang/toml

Compatible with TOML version v0.4.0

Documentation: https://godoc.org/github.com/BurntSushi/toml

Installation:

go get github.com/BurntSushi/toml

Try the toml validator:

go get github.com/BurntSushi/toml/cmd/tomlv
tomlv some-toml-file.toml

Build Status GoDoc

Testing

This package passes all tests in toml-test for both the decoder and the encoder.

Examples

This package works similarly to how the Go standard library handles XML and JSON. Namely, data is loaded into Go values via reflection.

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 could be defined in Go as:

type Config struct {
  Age int
  Cats []string
  Pi float64
  Perfection []int
  DOB time.Time // requires `import time`
}

And then decoded with:

var conf Config
if _, err := toml.Decode(tomlData, &conf); err != nil {
  // handle error
}

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"`
}

Using the encoding.TextUnmarshaler interface

Here’s an example that automatically parses duration strings into time.Duration values:

[[song]]
name = "Thunder Road"
duration = "4m49s"

[[song]]
name = "Stairway to Heaven"
duration = "8m03s"

Which can be decoded with:

type song struct {
  Name     string
  Duration duration
}
type songs struct {
  Song []song
}
var favorites songs
if _, err := toml.Decode(blob, &favorites); err != nil {
  log.Fatal(err)
}

for _, s := range favorites.Song {
  fmt.Printf("%s (%s)\n", s.Name, s.Duration)
}

And you’ll also need a duration type that satisfies the encoding.TextUnmarshaler interface:

type duration struct {
	time.Duration
}

func (d *duration) UnmarshalText(text []byte) error {
	var err error
	d.Duration, err = time.ParseDuration(string(text))
	return err
}

More complex usage

Here’s an example of how to load the example from the official spec page:

# This is a TOML document. Boom.

title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
organization = "GitHub"
bio = "GitHub Cofounder & CEO\nLikes tater tots and beer."
dob = 1979-05-27T07:32:00Z # First class dates? Why not?

[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002 ]
connection_max = 5000
enabled = true

[servers]

  # You can indent as you please. Tabs or spaces. TOML don't care.
  [servers.alpha]
  ip = "10.0.0.1"
  dc = "eqdc10"

  [servers.beta]
  ip = "10.0.0.2"
  dc = "eqdc10"

[clients]
data = [ ["gamma", "delta"], [1, 2] ] # just an update to make sure parsers support it

# Line breaks are OK when inside arrays
hosts = [
  "alpha",
  "omega"
]

And the corresponding Go types are:

type tomlConfig struct {
	Title string
	Owner ownerInfo
	DB database `toml:"database"`
	Servers map[string]server
	Clients clients
}

type ownerInfo struct {
	Name string
	Org string `toml:"organization"`
	Bio string
	DOB time.Time
}

type database struct {
	Server string
	Ports []int
	ConnMax int `toml:"connection_max"`
	Enabled bool
}

type server struct {
	IP string
	DC string
}

type clients struct {
	Data [][]interface{}
	Hosts []string
}

Note that a case insensitive match will be tried if an exact match can’t be found.

A working example of the above can be found in _examples/example.{go,toml}.