go-toml – github.com/pelletier/go-toml Index | Examples | Files | Directories

package toml

import "github.com/pelletier/go-toml"

Package toml is a TOML parser and manipulation library.

This version supports the specification as described in https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md

Marshaling

Go-toml can marshal and unmarshal TOML documents from and to data structures.

TOML document as a tree

Go-toml can operate on a TOML document as a tree. Use one of the Load* functions to parse TOML data and obtain a Tree instance, then one of its methods to manipulate the tree.

JSONPath-like queries

The package github.com/pelletier/go-toml/query implements a system similar to JSONPath to quickly retrieve elements of a TOML document using a single expression. See the package documentation for more information.

Example (Tree)

Code:play  

package main

import (
	"fmt"

	toml "github.com/pelletier/go-toml"
)

func main() {
	config, err := toml.LoadFile("config.toml")

	if err != nil {
		fmt.Println("Error ", err.Error())
	} else {
		// retrieve data directly
		user := config.Get("postgres.user").(string)
		password := config.Get("postgres.password").(string)

		// or using an intermediate object
		configTree := config.Get("postgres").(*toml.Tree)
		user = configTree.Get("user").(string)
		password = configTree.Get("password").(string)
		fmt.Println("User is", user, " and password is", password)

		// show where elements are in the file
		fmt.Printf("User position: %v\n", configTree.GetPosition("user"))
		fmt.Printf("Password position: %v\n", configTree.GetPosition("password"))
	}
}
Example (Unmarshal)

Code:play  

package main

import (
	"fmt"

	toml "github.com/pelletier/go-toml"
)

func main() {
	type Employer struct {
		Name  string
		Phone string
	}
	type Person struct {
		Name     string
		Age      int64
		Employer Employer
	}

	document := []byte(`
	name = "John"
	age = 30
	[employer]
		name = "Company Inc."
		phone = "+1 234 567 89012"
	`)

	person := Person{}
	toml.Unmarshal(document, &person)
	fmt.Println(person.Name, "is", person.Age, "and works at", person.Employer.Name)
}

Output:

John is 30 and works at Company Inc.

Index

Examples

Constants 

const (
	// Sort fields alphabetically.
	OrderAlphabetical marshalOrder = iota + 1
	// Preserve the order the fields are encountered. For example, the order of fields in
	// a struct.
	OrderPreserve
)

Orders the Encoder can write the fields to the output stream.

Functions

func Marshal 

func Marshal(v interface{}) ([]byte, error)

Marshal returns the TOML encoding of v. Behavior is similar to the Go json encoder, except that there is no concept of a Marshaler interface or MarshalTOML function for sub-structs, and currently only definite types can be marshaled (i.e. no `interface{}`).

The following struct annotations are supported: 

toml:"Field"      Overrides the field's name to output.
omitempty         When set, empty values and groups are not emitted.
comment:"comment" Emits a # comment on the same line. This supports new lines.
commented:"true"  Emits the value as commented.

Note that pointers are automatically assigned the "omitempty" option, as TOML explicitly does not handle null values (saying instead the label should be dropped).

Tree structural types and corresponding marshal types: 

*Tree                            (*)struct, (*)map[string]interface{}
[]*Tree                          (*)[](*)struct, (*)[](*)map[string]interface{}
[]interface{} (as interface{})   (*)[]primitive, (*)[]([]interface{})
interface{}                      (*)primitive

Tree primitive types and corresponding marshal types: 

uint64     uint, uint8-uint64, pointers to same
int64      int, int8-uint64, pointers to same
float64    float32, float64, pointers to same
string     string, pointers to same
bool       bool, pointers to same
time.Time  time.Time{}, pointers to same

For additional flexibility, use the Encoder API.

Example

Code:play  

package main

import (
	"fmt"
	"log"

	toml "github.com/pelletier/go-toml"
)

func main() {
	type Postgres struct {
		User     string `toml:"user"`
		Password string `toml:"password"`
		Database string `toml:"db" commented:"true" comment:"not used anymore"`
	}
	type Config struct {
		Postgres Postgres `toml:"postgres" comment:"Postgres configuration"`
	}

	config := Config{Postgres{User: "pelletier", Password: "mypassword", Database: "old_database"}}
	b, err := toml.Marshal(config)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(b))
}

Output:

# Postgres configuration
[postgres]

  # not used anymore
  # db = "old_database"
  password = "mypassword"
  user = "pelletier"

func Unmarshal 

func Unmarshal(data []byte, v interface{}) error

Unmarshal parses the TOML-encoded data and stores the result in the value pointed to by v. Behavior is similar to the Go json encoder, except that there is no concept of an Unmarshaler interface or UnmarshalTOML function for sub-structs, and currently only definite types can be unmarshaled to (i.e. no `interface{}`).

The following struct annotations are supported: 

toml:"Field" Overrides the field's name to map to.
default:"foo" Provides a default value.

For default values, only fields of the following types are supported:

See Marshal() documentation for types mapping table.

Example

Code:play  

package main

import (
	"fmt"

	toml "github.com/pelletier/go-toml"
)

func main() {
	type Postgres struct {
		User     string
		Password string
	}
	type Config struct {
		Postgres Postgres
	}

	doc := []byte(`
	[postgres]
	user = "pelletier"
	password = "mypassword"`)

	config := Config{}
	toml.Unmarshal(doc, &config)
	fmt.Println("user=", config.Postgres.User)
}

Output:

user= pelletier

Types

type Decoder 

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder reads and decodes TOML values from an input stream.

func NewDecoder 

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r.

func (*Decoder) Decode 

func (d *Decoder) Decode(v interface{}) error

Decode reads a TOML-encoded value from it's input and unmarshals it in the value pointed at by v.

See the documentation for Marshal for details.

func (*Decoder) SetTagName 

func (d *Decoder) SetTagName(v string) *Decoder

SetTagName allows changing default tag "toml"

type Encoder 

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder writes TOML values to an output stream.

func NewEncoder 

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new encoder that writes to w.

func (*Encoder) ArraysWithOneElementPerLine 

func (e *Encoder) ArraysWithOneElementPerLine(v bool) *Encoder

ArraysWithOneElementPerLine sets up the encoder to encode arrays with more than one element on multiple lines instead of one.

For example: 

A = [1,2,3]

Becomes 

A = [
  1,
  2,
  3,
]

func (*Encoder) Encode 

func (e *Encoder) Encode(v interface{}) error

Encode writes the TOML encoding of v to the stream.

See the documentation for Marshal for details.

func (*Encoder) Order 

func (e *Encoder) Order(ord marshalOrder) *Encoder

Order allows to change in which order fields will be written to the output stream.

func (*Encoder) QuoteMapKeys 

func (e *Encoder) QuoteMapKeys(v bool) *Encoder

QuoteMapKeys sets up the encoder to encode maps with string type keys with quoted TOML keys.

This relieves the character limitations on map keys.

func (*Encoder) SetTagComment 

func (e *Encoder) SetTagComment(v string) *Encoder

SetTagComment allows changing default tag "comment"

func (*Encoder) SetTagCommented 

func (e *Encoder) SetTagCommented(v string) *Encoder

SetTagCommented allows changing default tag "commented"

func (*Encoder) SetTagMultiline 

func (e *Encoder) SetTagMultiline(v string) *Encoder

SetTagMultiline allows changing default tag "multiline"

func (*Encoder) SetTagName 

func (e *Encoder) SetTagName(v string) *Encoder

SetTagName allows changing default tag "toml"

type Marshaler 

type Marshaler interface {
	MarshalTOML() ([]byte, error)
}

Marshaler is the interface implemented by types that can marshal themselves into valid TOML.

type Position 

type Position struct {
	Line int // line within the document
	Col  int // column within the line
}

Position of a document element within a TOML document.

Line and Col are both 1-indexed positions for the element's line number and column number, respectively. Values of zero or less will cause Invalid(), to return true.

func (Position) Invalid 

func (p Position) Invalid() bool

Invalid returns whether or not the position is valid (i.e. with negative or null values)

func (Position) String 

func (p Position) String() string

String representation of the position. Displays 1-indexed line and column numbers.

type SetOptions 

type SetOptions struct {
	Comment   string
	Commented bool
	Multiline bool
}

SetOptions arguments are supplied to the SetWithOptions and SetPathWithOptions functions to modify marshalling behaviour. The default values within the struct are valid default options.

type Tree 

type Tree struct {
	// contains filtered or unexported fields
}

Tree is the result of the parsing of a TOML file.

func Load 

func Load(content string) (tree *Tree, err error)

Load creates a Tree from a string.

func LoadBytes 

func LoadBytes(b []byte) (tree *Tree, err error)

LoadBytes creates a Tree from a []byte.

func LoadFile 

func LoadFile(path string) (tree *Tree, err error)

LoadFile creates a Tree from a file.

func LoadReader 

func LoadReader(reader io.Reader) (tree *Tree, err error)

LoadReader creates a Tree from any io.Reader.

func TreeFromMap 

func TreeFromMap(m map[string]interface{}) (*Tree, error)

TreeFromMap initializes a new Tree object using the given map.

func (*Tree) Delete 

func (t *Tree) Delete(key string) error

Delete removes a key from the tree. Key is a dot-separated path (e.g. a.b.c).

func (*Tree) DeletePath 

func (t *Tree) DeletePath(keys []string) error

Delete removes a key from the tree. Keys is an array of path elements (e.g. {"a","b","c"}).

func (*Tree) Get 

func (t *Tree) Get(key string) interface{}

Get the value at key in the Tree. Key is a dot-separated path (e.g. a.b.c) without single/double quoted strings. If you need to retrieve non-bare keys, use GetPath. Returns nil if the path does not exist in the tree. If keys is of length zero, the current tree is returned.

func (*Tree) GetDefault 

func (t *Tree) GetDefault(key string, def interface{}) interface{}

GetDefault works like Get but with a default value

func (*Tree) GetPath 

func (t *Tree) GetPath(keys []string) interface{}

GetPath returns the element in the tree indicated by 'keys'. If keys is of length zero, the current tree is returned.

func (*Tree) GetPosition 

func (t *Tree) GetPosition(key string) Position

GetPosition returns the position of the given key.

func (*Tree) GetPositionPath 

func (t *Tree) GetPositionPath(keys []string) Position

GetPositionPath returns the element in the tree indicated by 'keys'. If keys is of length zero, the current tree is returned.

func (*Tree) Has 

func (t *Tree) Has(key string) bool

Has returns a boolean indicating if the given key exists.

func (*Tree) HasPath 

func (t *Tree) HasPath(keys []string) bool

HasPath returns true if the given path of keys exists, false otherwise.

func (*Tree) Keys 

func (t *Tree) Keys() []string

Keys returns the keys of the toplevel tree (does not recurse).

func (*Tree) Marshal 

func (t *Tree) Marshal() ([]byte, error)

Marshal returns the TOML encoding of Tree. See Marshal() documentation for types mapping table.

func (*Tree) Position 

func (t *Tree) Position() Position

Position returns the position of the tree.

func (*Tree) Set 

func (t *Tree) Set(key string, value interface{})

Set an element in the tree. Key is a dot-separated path (e.g. a.b.c). Creates all necessary intermediate trees, if needed.

func (*Tree) SetPath 

func (t *Tree) SetPath(keys []string, value interface{})

SetPath sets an element in the tree. Keys is an array of path elements (e.g. {"a","b","c"}). Creates all necessary intermediate trees, if needed.

func (*Tree) SetPathWithComment 

func (t *Tree) SetPathWithComment(keys []string, comment string, commented bool, value interface{})

SetPathWithComment is the same as SetPath, but allows you to provide comment information to the key, that will be reused by Marshal().

func (*Tree) SetPathWithOptions 

func (t *Tree) SetPathWithOptions(keys []string, opts SetOptions, value interface{})

SetPathWithOptions is the same as SetPath, but allows you to provide formatting instructions to the key, that will be reused by Marshal().

func (*Tree) SetWithComment 

func (t *Tree) SetWithComment(key string, comment string, commented bool, value interface{})

SetWithComment is the same as Set, but allows you to provide comment information to the key, that will be reused by Marshal().

func (*Tree) SetWithOptions 

func (t *Tree) SetWithOptions(key string, opts SetOptions, value interface{})

SetWithOptions is the same as Set, but allows you to provide formatting instructions to the key, that will be used by Marshal().

func (*Tree) String 

func (t *Tree) String() string

String generates a human-readable representation of the current tree. Alias of ToString. Present to implement the fmt.Stringer interface.

func (*Tree) ToMap 

func (t *Tree) ToMap() map[string]interface{}

ToMap recursively generates a representation of the tree using Go built-in structures. The following types are used:

func (*Tree) ToTomlString 

func (t *Tree) ToTomlString() (string, error)

ToTomlString generates a human-readable representation of the current tree. Output spans multiple lines, and is suitable for ingest by a TOML parser. If the conversion cannot be performed, ToString returns a non-nil error.

func (*Tree) Unmarshal 

func (t *Tree) Unmarshal(v interface{}) error

Unmarshal attempts to unmarshal the Tree into a Go struct pointed by v. Neither Unmarshaler interfaces nor UnmarshalTOML functions are supported for sub-structs, and only definite types can be unmarshaled.

func (*Tree) WriteTo 

func (t *Tree) WriteTo(w io.Writer) (int64, error)

WriteTo encode the Tree as Toml and writes it to the writer w. Returns the number of bytes written in case of success, or an error if anything happened.

Source Files

doc.go keysparsing.go lexer.go marshal.go parser.go position.go token.go toml.go tomltree_create.go tomltree_write.go

Directories

PathSynopsis
cmd
cmd/tomljsonTomljson reads TOML and converts to JSON.
cmd/tomllTomll is a linter for TOML
cmd/tomltestgenTomltestgen is a program that retrieves a given version of https://github.com/BurntSushi/toml-test and generates go code for go-toml's unit tests based on the test files.
queryPackage query performs JSONPath-like queries on a TOML document.
Version
v1.3.0
Published
Apr 2, 2019
Platform
darwin/amd64
Imports
15 packages
Last checked
now –

Tools for package owners.