toml

package module
v0.0.0-...-9d1a8af Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 22, 2019 License: MIT Imports: 13 Imported by: 3

README

TOML parser and encoder for Go

Compatible with TOML version v0.4.0.

GoDoc Build Status

Run go get github.com/kezhuw/toml to install.

Examples

Snippets copied from Go test files.

package toml_test

import (
	"fmt"
	"time"

	"github.com/kezhuw/toml"
)

func ExampleUnmarshal_integer() {
	data := []byte(`key = 12345`)
	var out struct{ Key int }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
	// Output: 12345
}

func ExampleUnmarshal_datetimeNative() {
	data := []byte(`key = 2016-01-07T15:30:30.123456789Z`)
	var out struct{ Key time.Time }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key.Format(time.RFC3339Nano))
	// Output: 2016-01-07T15:30:30.123456789Z
}

func ExampleUnmarshal_array() {
	data := []byte(`key = [1, 2, 3,4]`)
	var out struct{ Key []int }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
	// Output: [1 2 3 4]
}

func ExampleUnmarshal_table() {
	data := []byte(`[key]
	name = "name"
	value = "value"`)
	var out struct {
		Key struct {
			Name  string
			Value string
		}
	}

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Printf("key.name = %q\n", out.Key.Name)
	fmt.Printf("key.value = %q\n", out.Key.Value)
	// Output:
	// key.name = "name"
	// key.value = "value"
}

func ExampleUnmarshal_inlineTable() {
	data := []byte(`key = { name = "name", value = "value" }`)
	var out struct {
		Key struct {
			Name  string
			Value string
		}
	}

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Printf("key.name = %q\n", out.Key.Name)
	fmt.Printf("key.value = %q\n", out.Key.Value)
	// Output:
	// key.name = "name"
	// key.value = "value"
}

func ExampleUnmarshal_tableArray() {
	data := []byte(`
	[[array]]
	description = "Table In Array"
	`)
	var out struct {
		Array []struct{ Description string }
	}

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Array[0].Description)
	// Output: Table In Array
}

func ExampleUnmarshal_interface() {
	data := []byte(`key = [1, 2, 3, 4,]`)
	var out struct{ Key interface{} }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
	// Output: [1 2 3 4]
}

func ExampleUnmarshal_tagName() {
	data := []byte(`KKKK = "value"`)
	var out struct {
		Key string `toml:"KKKK"`
	}

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
	// Output: value
}

func ExampleUnmarshal_tagIgnore() {
	data := []byte(`key = "value"`)
	var out struct {
		Key string `toml:"-"`
	}

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
	// Output:
}

func ExampleUnmarshal_tagString() {
	data := []byte(`key = "12345"`)
	var out struct {
		Key int `toml:",string"`
	}

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
	// Output: 12345
}

func ExampleUnmarshal_tagOmitempty() {
	data := []byte(``)
	var out struct {
		Key string `toml:",omitempty"`
	}
	out.Key = "Not empty, for now."

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
	// Output:
}

package toml_test

import (
	"fmt"
	"time"

	"github.com/kezhuw/toml"
)

type duration time.Duration

func (d *duration) UnmarshalText(b []byte) error {
	v, err := time.ParseDuration(string(b))
	if err != nil {
		return err
	}
	*d = duration(v)
	return nil
}

func ExampleUnmarshal_textUnmarshaler() {
	data := []byte(`timeout = "300ms"`)
	var out struct{ Timeout duration }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(time.Duration(out.Timeout))
	// Output: 300ms
}

Other TOML libraries written in Go.

License

Released under The MIT License (MIT). See LICENSE for the full license text.

Contribution

Fire issue or pull request if you have any questions.

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Marshal 

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

Marshal returns TOML encoding of v.

Argument v must be of type struct/map or non-nil pointer or interface to these types and must not implement encoding.TextMarshaler.

Values implementing encoding.TextMarshaler are encoded as strings.

Fields with nil value in struct or map are ignored. Nil maps or slices in array are encoded as empty tables or arrays in TOML. Error is raised when nil pointer or interface is encountered in array or slice.

Slice of byte is encoded as base64-encoded string.

time.Time and types with "datetime" tagged and convertible to time.Time are encoded as TOML Datetime.

Any value that will be encoded as string can have "literal", "multiline" and/or "ascii" tagged.

Struct or map fields tagged with "inline" are encoded as inline table.

Tag options specified for array or slice fields are inherited by their elements.

func Unmarshal 

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

Unmarshal parses TOML data and stores the result in the value pointed by v.

To unmarshal TOML into a struct, Unmarshal uses TOML tagged name to find matching item in TOML table. Field name and its lower case will got tried in sequence if TOML tagged name is absent. Options can be specified after tag name separated by comma. Examples: 

// Field is ignored by this package.
Field int `toml:"-"`

// "Field" and "field" will be used to find key in TOML table.
Field int `toml:"myName"`

// "myName" will be used to find matching item in TOML table, and
// if it is absent, it will be set to zero value.
Field int `toml:"myName,omitempty"`

// "Field" and "field" will be used to find key in TOML table and
// this field can be unmarshalled from TOML string.
Field int `toml:",string"

To unmarshal TOML into an interface value, Unmarshal stores TOML value in following types: 

bool, for TOML Boolean
int64, for TOML Integer
float64, for TOML Float
string, for TOML String
time.Time, for TOML Datetime
[]interface{}, for TOML Array
map[string]interface{}, for TOML Table

There is no guarantee that origin data in Go value will be preserved after a failure or success Unmarshal().

Example (Array) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`key = [1, 2, 3,4]`)
	var out struct{ Key []int }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
}

Output:

[1 2 3 4]
Example (Boolean) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`key = true`)
	var out struct{ Key bool }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
}

Output:

true
Example (DatetimeNative) 
package main

import (
	"fmt"
	"time"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`key = 2016-01-07T15:30:30.123456789Z`)
	var out struct{ Key time.Time }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key.Format(time.RFC3339Nano))
}

Output:

2016-01-07T15:30:30.123456789Z
Example (DatetimeTextUnmarshaler) 
package main

import (
	"fmt"
	"time"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`key = "2016-01-07T15:30:30.123456789Z"`)
	var out struct{ Key time.Time }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key.Format(time.RFC3339Nano))
}

Output:

2016-01-07T15:30:30.123456789Z
Example (Float) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`key = 3.14`)
	var out struct{ Key float64 }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
}

Output:

3.14
Example (InlineTable) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`key = { name = "name", value = "value" }`)
	var out struct {
		Key struct {
			Name  string
			Value string
		}
	}

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Printf("key.name = %q\n", out.Key.Name)
	fmt.Printf("key.value = %q\n", out.Key.Value)
}

Output:

key.name = "name"
key.value = "value"
Example (Integer) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`key = 12345`)
	var out struct{ Key int }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
}

Output:

12345
Example (Interface) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`key = [1, 2, 3, 4,]`)
	var out struct{ Key interface{} }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
}

Output:

[1 2 3 4]
Example (String) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`key = "value"`)
	var out struct{ Key string }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
}

Output:

value
Example (Table) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`[key]
	name = "name"
	value = "value"`)
	var out struct {
		Key struct {
			Name  string
			Value string
		}
	}

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Printf("key.name = %q\n", out.Key.Name)
	fmt.Printf("key.value = %q\n", out.Key.Value)
}

Output:

key.name = "name"
key.value = "value"
Example (TableArray) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`
	[[array]]
	description = "Table In Array"
	`)
	var out struct {
		Array []struct{ Description string }
	}

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Array[0].Description)
}

Output:

Table In Array
Example (TagIgnore) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`key = "value"`)
	var out struct {
		Key string `toml:"-"`
	}

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
}

Output:
Example (TagName) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`KKKK = "value"`)
	var out struct {
		Key string `toml:"KKKK"`
	}

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
}

Output:

value
Example (TagOmitempty) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(``)
	var out struct {
		Key string `toml:",omitempty"`
	}
	out.Key = "Not empty, for now."

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
}

Output:
Example (TagString) 
package main

import (
	"fmt"

	"github.com/kezhuw/toml"
)

func main() {
	data := []byte(`key = "12345"`)
	var out struct {
		Key int `toml:",string"`
	}

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(out.Key)
}

Output:

12345
Example (TextUnmarshaler) 
package main

import (
	"fmt"
	"time"

	"github.com/kezhuw/toml"
)

type duration time.Duration

func (d *duration) UnmarshalText(b []byte) error {
	v, err := time.ParseDuration(string(b))
	if err != nil {
		return err
	}
	*d = duration(v)
	return nil
}

func main() {
	data := []byte(`timeout = "300ms"`)
	var out struct{ Timeout duration }

	err := toml.Unmarshal(data, &out)
	if err != nil {
		panic(err)
	}

	fmt.Println(time.Duration(out.Timeout))
}

Output:

300ms

Types

type Encoder 

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

Encoder writes TOML document to an output stream.

func NewEncoder 

func NewEncoder(w io.Writer) *Encoder

NewEncoder creates a new encoder that writes to w.

func (*Encoder) Encode 

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

Encode writes TOML document of v to the underlying stream.

type InvalidMarshalError 

type InvalidMarshalError struct {
	Type reflect.Type
}

InvalidMarshalError describes that invalid argument passed to Marshal.

func (*InvalidMarshalError) Error 

func (e *InvalidMarshalError) Error() string

type InvalidUTF8Error 

type InvalidUTF8Error struct {
	S string
}

InvalidUTF8Error describes that invalid UTF-8 encoded string encountered.

func (*InvalidUTF8Error) Error 

func (e *InvalidUTF8Error) Error() string

type InvalidUnmarshalError 

type InvalidUnmarshalError struct {
	Type reflect.Type
}

An InvalidUnmarshalError describes that an invalid argment was passed to Unmarshal. The argument passed to Unmarshal must be non-nil pointer.

func (*InvalidUnmarshalError) Error 

func (e *InvalidUnmarshalError) Error() string

type MarshalArrayTypeError 

type MarshalArrayTypeError struct {
	Path   string
	Expect string
	Got    string
}

MarshalArrayTypeError describes that an unexpected type of array element was encountered.

func (*MarshalArrayTypeError) Error 

func (e *MarshalArrayTypeError) Error() string

type MarshalNilValueError 

type MarshalNilValueError struct {
	Type reflect.Type
	As   string
}

MarshalNilValueError describes that a nil pointer or interface in array or slice.

func (*MarshalNilValueError) Error 

func (e *MarshalNilValueError) Error() string

type MarshalTypeError 

type MarshalTypeError struct {
	Type reflect.Type
	As   string
}

MarshalTypeError describes that a value of specified Go type cannot be represent as desired TOML type.

func (*MarshalTypeError) Error 

func (e *MarshalTypeError) Error() string

type ParseError 

type ParseError struct {
	Line int // 1-based
	Pos  int // 0-based, relative to beginning of input
	Err  error
}

ParseError describes errors raised in parsing phase.

func (*ParseError) Error 

func (e *ParseError) Error() string

type StructKeyError 

type StructKeyError struct {
	Key  string
	Type reflect.Type
}

StructKeyError describes that multiple fields in struct has conflicted key.

func (*StructKeyError) Error 

func (e *StructKeyError) Error() string

type UnmarshalOverflowError 

type UnmarshalOverflowError struct {
	Value string
	Type  reflect.Type
}

An UnmarshalOverflowError describes that a TOML number value overflows specified Go type.

func (*UnmarshalOverflowError) Error 

func (e *UnmarshalOverflowError) Error() string

type UnmarshalTypeError 

type UnmarshalTypeError struct {
	Value string
	Type  reflect.Type
}

An UnmarshalTypeError describes that a TOML value is not appropriate to be stored in specified Go type.

func (*UnmarshalTypeError) Error 

func (e *UnmarshalTypeError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
internal
types

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.