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 retrive elements of a TOML document using a single expression. See the package documentation for more information.

{
	config, err := 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").(*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"))
	}
}

{
	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{}
	Unmarshal(document, &person)
	fmt.Println(person.Name, "is", person.Age, "and works at", person.Employer.Name)
}

Index ¶

• func Marshal(v interface{}) ([]byte, error)
• func Unmarshal(data []byte, v interface{}) error
• type Marshaler
• type Position
• func (p Position) Invalid() bool
• func (p Position) String() string
• type Tree
• func Load(content string) (tree *Tree, err error)
• func LoadFile(path string) (tree *Tree, err error)
• func LoadReader(reader io.Reader) (tree *Tree, err error)
• func TreeFromMap(m map[string]interface{}) (*Tree, error)
• func (t *Tree) Get(key string) interface{}
• func (t *Tree) GetDefault(key string, def interface{}) interface{}
• func (t *Tree) GetPath(keys []string) interface{}
• func (t *Tree) GetPosition(key string) Position
• func (t *Tree) GetPositionPath(keys []string) Position
• func (t *Tree) Has(key string) bool
• func (t *Tree) HasPath(keys []string) bool
• func (t *Tree) Keys() []string
• func (t *Tree) Position() Position
• func (t *Tree) Set(key string, value interface{})
• func (t *Tree) SetPath(keys []string, value interface{})
• func (t *Tree) String() string
• func (t *Tree) ToMap() map[string]interface{}
• func (t *Tree) ToTomlString() (string, error)
• func (t *Tree) Unmarshal(v interface{}) error
• func (t *Tree) WriteTo(w io.Writer) (int64, error)

Examples ¶

• package (Tree)
• package (Unmarshal)
• Unmarshal

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{}`).

Note that pointers are automatically assigned the "omitempty" option, as TOML explicity 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

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{}`).

See Marshal() documentation for types mapping table.

{
	type Postgres struct {
		User     string
		Password string
	}
	type Config struct {
		Postgres Postgres
	}

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

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

Types ¶

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 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 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) 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). 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) 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) 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:

• bool
• float64
• int64
• string
• uint64
• time.Time
• map[string]interface{} (where interface{} is any of this list)
• []interface{} (where interface{} is any of this list)

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 ¶