package toml

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

Package toml is a library to read and write TOML documents.

Index ¶

• func Marshal(v interface{}) ([]byte, error)
• func Unmarshal(data []byte, v interface{}) error
• type DecodeError
• func (e *DecodeError) Error() string
• func (e *DecodeError) Key() Key
• func (e *DecodeError) Position() (row int, column int)
• func (e *DecodeError) String() string
• type Decoder
• func NewDecoder(r io.Reader) *Decoder
• func (d *Decoder) Decode(v interface{}) error
• func (d *Decoder) SetStrict(strict bool) *Decoder
• type Encoder
• func NewEncoder(w io.Writer) *Encoder
• func (enc *Encoder) Encode(v interface{}) error
• func (enc *Encoder) SetArraysMultiline(multiline bool) *Encoder
• func (enc *Encoder) SetIndentSymbol(s string) *Encoder
• func (enc *Encoder) SetIndentTables(indent bool) *Encoder
• func (enc *Encoder) SetTablesInline(inline bool) *Encoder
• type Key
• type LocalDate
• func (d LocalDate) AsTime(zone *time.Location) time.Time
• func (d LocalDate) MarshalText() ([]byte, error)
• func (d LocalDate) String() string
• func (d *LocalDate) UnmarshalText(b []byte) error
• type LocalDateTime
• func (d LocalDateTime) AsTime(zone *time.Location) time.Time
• func (d LocalDateTime) MarshalText() ([]byte, error)
• func (d LocalDateTime) String() string
• func (d *LocalDateTime) UnmarshalText(data []byte) error
• type LocalTime
• func (d LocalTime) MarshalText() ([]byte, error)
• func (d LocalTime) String() string
• func (d *LocalTime) UnmarshalText(b []byte) error
• type StrictMissingError
• func (s *StrictMissingError) Error() string
• func (s *StrictMissingError) String() string

Examples ¶

• DecodeError
• Decoder.SetStrict
• Marshal
• Unmarshal

Functions ¶

func Marshal ¶

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

Marshal serializes a Go value as a TOML document.

It is a shortcut for Encoder.Encode() with the default options.

{
	type MyConfig struct {
		Version int
		Name    string
		Tags    []string
	}

	cfg := MyConfig{
		Version: 2,
		Name:    "go-toml",
		Tags:    []string{"go", "toml"},
	}

	b, err := toml.Marshal(cfg)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(b))

	// Output:
	// Version = 2
	// Name = 'go-toml'
	// Tags = ['go', 'toml']
}

Version = 2
Name = 'go-toml'
Tags = ['go', 'toml']

func Unmarshal ¶

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

Unmarshal deserializes a TOML document into a Go value.

It is a shortcut for Decoder.Decode() with the default options.

{
	type MyConfig struct {
		Version int
		Name    string
		Tags    []string
	}

	doc := `
	version = 2
	name = "go-toml"
	tags = ["go", "toml"]
	`

	var cfg MyConfig
	err := toml.Unmarshal([]byte(doc), &cfg)
	if err != nil {
		panic(err)
	}
	fmt.Println("version:", cfg.Version)
	fmt.Println("name:", cfg.Name)
	fmt.Println("tags:", cfg.Tags)

	// Output:
	// version: 2
	// name: go-toml
	// tags: [go toml]
}

version: 2
name: go-toml
tags: [go toml]

Types ¶

type DecodeError ¶

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

DecodeError represents an error encountered during the parsing or decoding of a TOML document.

In addition to the error message, it contains the position in the document where it happened, as well as a human-readable representation that shows where the error occurred in the document.

{
	doc := `name = 123__456`

	s := map[string]interface{}{}
	err := Unmarshal([]byte(doc), &s)

	fmt.Println(err)

	var derr *DecodeError
	if errors.As(err, &derr) {
		fmt.Println(derr.String())
		row, col := derr.Position()
		fmt.Println("error occurred at row", row, "column", col)
	}
	// Output:
	// toml: number must have at least one digit between underscores
	// 1| name = 123__456
	//  |           ~~ number must have at least one digit between underscores
	// error occurred at row 1 column 11
}

toml: number must have at least one digit between underscores
1| name = 123__456
 |           ~~ number must have at least one digit between underscores
error occurred at row 1 column 11

func (*DecodeError) Error ¶

func (e *DecodeError) Error() string

Error returns the error message contained in the DecodeError.

func (*DecodeError) Key ¶

func (e *DecodeError) Key() Key

Key that was being processed when the error occurred. The key is present only if this DecodeError is part of a StrictMissingError.

func (*DecodeError) Position ¶

func (e *DecodeError) Position() (row int, column int)

Position returns the (line, column) pair indicating where the error occurred in the document. Positions are 1-indexed.

func (*DecodeError) String ¶

func (e *DecodeError) String() string

String returns the human-readable contextualized error. This string is multi-line.

type Decoder ¶

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

Decoder reads and decode a TOML document from an input stream.

func NewDecoder ¶

func NewDecoder(r io.Reader) *Decoder

NewDecoder creates a new Decoder that will read from r.

func (*Decoder) Decode ¶

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

Decode the whole content of r into v.

By default, values in the document that don't exist in the target Go value are ignored. See Decoder.SetStrict() to change this behavior.

When a TOML local date, time, or date-time is decoded into a time.Time, its value is represented in time.Local timezone. Otherwise the approriate Local* structure is used. For time values, precision up to the nanosecond is supported by truncating extra digits.

Empty tables decoded in an interface{} create an empty initialized map[string]interface{}.

Types implementing the encoding.TextUnmarshaler interface are decoded from a TOML string.

When decoding a number, go-toml will return an error if the number is out of bounds for the target type (which includes negative numbers when decoding into an unsigned int).

If an error occurs while decoding the content of the document, this function returns a toml.DecodeError, providing context about the issue. When using strict mode and a field is missing, a `toml.StrictMissingError` is returned. In any other case, this function returns a standard Go error.

Type mapping

List of supported TOML types and their associated accepted Go types:

String           -> string
Integer          -> uint*, int*, depending on size
Float            -> float*, depending on size
Boolean          -> bool
Offset Date-Time -> time.Time
Local Date-time  -> LocalDateTime, time.Time
Local Date       -> LocalDate, time.Time
Local Time       -> LocalTime, time.Time
Array            -> slice and array, depending on elements types
Table            -> map and struct
Inline Table     -> same as Table
Array of Tables  -> same as Array and Table

func (*Decoder) SetStrict ¶

func (d *Decoder) SetStrict(strict bool) *Decoder

SetStrict toggles decoding in stict mode.

When the decoder is in strict mode, it will record fields from the document that could not be set on the target value. In that case, the decoder returns a StrictMissingError that can be used to retrieve the individual errors as well as generate a human readable description of the missing fields.

{
	type S struct {
		Key1 string
		Key3 string
	}
	doc := `
key1 = "value1"
key2 = "value2"
key3 = "value3"
`
	r := strings.NewReader(doc)
	d := toml.NewDecoder(r)
	d.SetStrict(true)
	s := S{}
	err := d.Decode(&s)

	fmt.Println(err.Error())

	var details *toml.StrictMissingError
	if !errors.As(err, &details) {
		panic(fmt.Sprintf("err should have been a *toml.StrictMissingError, but got %s (%T)", err, err))
	}

	fmt.Println(details.String())
	// Output:
	// strict mode: fields in the document are missing in the target struct
	// 2| key1 = "value1"
	// 3| key2 = "value2"
	//  | ~~~~ missing field
	// 4| key3 = "value3"
}

strict mode: fields in the document are missing in the target struct
2| key1 = "value1"
3| key2 = "value2"
 | ~~~~ missing field
4| key3 = "value3"

type Encoder ¶

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

Encoder writes a TOML document to an output stream.

func NewEncoder ¶

func NewEncoder(w io.Writer) *Encoder

NewEncoder returns a new Encoder that writes to w.

func (*Encoder) Encode ¶

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

Encode writes a TOML representation of v to the stream.

If v cannot be represented to TOML it returns an error.

Encoding rules

A top level slice containing only maps or structs is encoded as [[table array]].

All slices not matching rule 1 are encoded as [array]. As a result, any map or struct they contain is encoded as an {inline table}.

Nil interfaces and nil pointers are not supported.

Keys in key-values always have one part.

Intermediate tables are always printed.

By default, strings are encoded as literal string, unless they contain either a newline character or a single quote. In that case they are emitted as quoted strings.

When encoding structs, fields are encoded in order of definition, with their exact name.

Struct tags

The encoding of each public struct field can be customized by the format string in the "toml" key of the struct field's tag. This follows encoding/json's convention. The format string starts with the name of the field, optionally followed by a comma-separated list of options. The name may be empty in order to provide options without overriding the default name.

The "multiline" option emits strings as quoted multi-line TOML strings. It has no effect on fields that would not be encoded as strings.

The "inline" option turns fields that would be emitted as tables into inline tables instead. It has no effect on other fields.

The "omitempty" option prevents empty values or groups from being emitted.

In addition to the "toml" tag struct tag, a "comment" tag can be used to emit a TOML comment before the value being annotated. Comments are ignored inside inline tables.

func (*Encoder) SetArraysMultiline ¶

func (enc *Encoder) SetArraysMultiline(multiline bool) *Encoder

SetArraysMultiline forces the encoder to emit all arrays with one element per line.

This behavior can be controlled on an individual struct field basis with the multiline tag:

MyField `multiline:"true"`

func (*Encoder) SetIndentSymbol ¶

func (enc *Encoder) SetIndentSymbol(s string) *Encoder

SetIndentSymbol defines the string that should be used for indentation. The provided string is repeated for each indentation level. Defaults to two spaces.

func (*Encoder) SetIndentTables ¶

func (enc *Encoder) SetIndentTables(indent bool) *Encoder

SetIndentTables forces the encoder to intent tables and array tables.

func (*Encoder) SetTablesInline ¶

func (enc *Encoder) SetTablesInline(inline bool) *Encoder

SetTablesInline forces the encoder to emit all tables inline.

This behavior can be controlled on an individual struct field basis with the inline tag:

MyField `inline:"true"`

type Key ¶

type Key []string

type LocalDate ¶

type LocalDate struct {
	Year  int
	Month int
	Day   int
}

LocalDate represents a calendar day in no specific timezone.

func (LocalDate) AsTime ¶

func (d LocalDate) AsTime(zone *time.Location) time.Time

AsTime converts d into a specific time instance at midnight in zone.

func (LocalDate) MarshalText ¶

func (d LocalDate) MarshalText() ([]byte, error)

MarshalText returns RFC 3339 representation of d.

func (LocalDate) String ¶

func (d LocalDate) String() string

String returns RFC 3339 representation of d.

func (*LocalDate) UnmarshalText ¶

func (d *LocalDate) UnmarshalText(b []byte) error

UnmarshalText parses b using RFC 3339 to fill d.

type LocalDateTime ¶

type LocalDateTime struct {
	LocalDate
	LocalTime
}

LocalDateTime represents a time of a specific day in no specific timezone.

func (LocalDateTime) AsTime ¶

func (d LocalDateTime) AsTime(zone *time.Location) time.Time

AsTime converts d into a specific time instance in zone.

func (LocalDateTime) MarshalText ¶

func (d LocalDateTime) MarshalText() ([]byte, error)

MarshalText returns RFC 3339 representation of d.

func (LocalDateTime) String ¶

func (d LocalDateTime) String() string

String returns RFC 3339 representation of d.

func (*LocalDateTime) UnmarshalText ¶

func (d *LocalDateTime) UnmarshalText(data []byte) error

UnmarshalText parses b using RFC 3339 to fill d.

type LocalTime ¶

type LocalTime struct {
	Hour       int // Hour of the day: [0; 24[
	Minute     int // Minute of the hour: [0; 60[
	Second     int // Second of the minute: [0; 60[
	Nanosecond int // Nanoseconds within the second:  [0, 1000000000[
	Precision  int // Number of digits to display for Nanosecond.
}

LocalTime represents a time of day of no specific day in no specific timezone.

func (LocalTime) MarshalText ¶

func (d LocalTime) MarshalText() ([]byte, error)

MarshalText returns RFC 3339 representation of d.

func (LocalTime) String ¶

func (d LocalTime) String() string

String returns RFC 3339 representation of d. If d.Nanosecond and d.Precision are zero, the time won't have a nanosecond component. If d.Nanosecond > 0 but d.Precision = 0, then the minimum number of digits for nanoseconds is provided.

func (*LocalTime) UnmarshalText ¶

func (d *LocalTime) UnmarshalText(b []byte) error

UnmarshalText parses b using RFC 3339 to fill d.

type StrictMissingError ¶

type StrictMissingError struct {
	// One error per field that could not be found.
	Errors []DecodeError
}

StrictMissingError occurs in a TOML document that does not have a corresponding field in the target value. It contains all the missing fields in Errors.

Emitted by Decoder when SetStrict(true) was called.

func (*StrictMissingError) Error ¶

func (s *StrictMissingError) Error() string

Error returns the canonical string for this error.

func (*StrictMissingError) String ¶

func (s *StrictMissingError) String() string

String returns a human readable description of all errors.

Source Files ¶

decode.go doc.go errors.go localtime.go marshaler.go parser.go scanner.go strict.go types.go unmarshaler.go utf8.go

Directories ¶