Exclude testing PRs from release notes

Fixes #714

.github/release.yml

@@ -2,6 +2,7 @@ changelog:
   exclude:
     labels:
       - build
+      - testing
   categories:
     - title: What's new
       labels:

README.md

@@ -55,8 +55,9 @@ to check for typos. [See example in the documentation][strict].
 
 ### Contextualized errors
 
-When decoding errors occur, go-toml returns [`DecodeError`][decode-err]), which
+When most decoding errors occur, go-toml returns [`DecodeError`][decode-err]),
-contains a human readable contextualized version of the error. For example:
+which contains a human readable contextualized version of the error. For
+example:
 
 ```
 2| key1 = "value1"
@@ -324,6 +325,29 @@ The recommended replacement is pre-filling the struct before unmarshaling.
 
 [go-defaults]: https://github.com/mcuadros/go-defaults
 
+#### `toml.Tree` replacement
+
+This structure was the initial attempt at providing a document model for
+go-toml. It allows manipulating the structure of any document, encoding and
+decoding from their TOML representation. While a more robust feature was
+initially planned in go-toml v2, this has been ultimately [removed from
+scope][nodoc] of this library, with no plan to add it back at the moment. The
+closest equivalent at the moment would be to unmarshal into an `interface{}` and
+use type assertions and/or reflection to manipulate the arbitrary
+structure. However this would fall short of providing all of the TOML features
+such as adding comments and be specific about whitespace.
+
+
+#### `toml.Position` are not retrievable anymore
+
+The API for retrieving the position (line, column) of a specific TOML element do
+not exist anymore. This was done to minimize the amount of concepts introduced
+by the library (query path), and avoid the performance hit related to storing
+positions in the absence of a document model, for a feature that seemed to have
+little use. Errors however have gained more detailed position
+information. Position retrieval seems better fitted for a document model, which
+has been [removed from the scope][nodoc] of go-toml v2 at the moment.
+
 ### Encoding / Marshal
 
 #### Default struct fields order
@@ -359,7 +383,8 @@ fmt.Println("v2:\n" + string(b))
 ```
 
 There is no way to make v2 encoder behave like v1. A workaround could be to
-manually sort the fields alphabetically in the struct definition.
+manually sort the fields alphabetically in the struct definition, or generate
+struct types using `reflect.StructOf`.
 
 #### No indentation by default
 
@@ -407,7 +432,9 @@ fmt.Println("v2 Encoder:\n" + string(buf.Bytes()))
 
 V1 always uses double quotes (`"`) around strings and keys that cannot be
 represented bare (unquoted). V2 uses single quotes instead by default (`'`),
-unless a character cannot be represented, then falls back to double quotes.
+unless a character cannot be represented, then falls back to double quotes. As a
+result of this change, `Encoder.QuoteMapKeys` has been removed, as it is not
+useful anymore.
 
 There is no way to make v2 encoder behave like v1.
 
@@ -422,6 +449,84 @@ There is no way to make v2 encoder behave like v1.
 
 [tm]: https://golang.org/pkg/encoding/#TextMarshaler
 
+#### `Encoder.CompactComments` has been removed
+
+Emitting compact comments is now the default behavior of go-toml. This option
+is not necessary anymore.
+
+#### Struct tags have been merged
+
+V1 used to provide multiple struct tags: `comment`, `commented`, `multiline`,
+`toml`, and `omitempty`. To behave more like the standard library, v2 has merged
+`toml`, `multiline`, and `omitempty`. For example:
+
+```go
+type doc struct {
+	// v1
+	F string `toml:"field" multiline:"true" omitempty:"true"`
+	// v2
+	F string `toml:"field,multiline,omitempty"`
+}
+```
+
+Has a result, the `Encoder.SetTag*` methods have been removed, as there is just
+one tag now.
+
+
+#### `commented` tag has been removed
+
+There is no replacement for the `commented` tag. This feature would be better
+suited in a proper document model for go-toml v2, which has been [cut from
+scope][nodoc] at the moment.
+
+#### `Encoder.ArraysWithOneElementPerLine` has been renamed
+
+The new name is `Encoder.SetArraysMultiline`. The behavior should be the same.
+
+#### `Encoder.Indentation` has been renamed
+
+The new name is `Encoder.SetIndentSymbol`. The behavior should be the same.
+
+
+#### Embedded structs are tables
+
+V1 defaults to merging embedded struct fields into the embedding struct. This
+behavior was unexpected because it does not follow the standard library. To
+avoid breaking backward compatibility, the `Encoder.PromoteAnonymous` method was
+added to make the encoder behave correctly. Given backward compatibility is not
+a problem anymore, v2 does the right thing by default. There is no way to revert
+to the old behavior, and `Encoder.PromoteAnonymous` has been removed.
+
+```go
+type Embedded struct {
+	Value string `toml:"value"`
+}
+
+type Doc struct {
+	Embedded
+}
+
+d := Doc{}
+
+fmt.Println("v1:")
+b, err := v1.Marshal(d)
+fmt.Println(string(b))
+
+fmt.Println("v2:")
+b, err = v2.Marshal(d)
+fmt.Println(string(b))
+
+// Output:
+// v1:
+// value = ""
+//
+// v2:
+// [Embedded]
+// value = ''
+```
+
+[nodoc]: https://github.com/pelletier/go-toml/discussions/506#discussioncomment-1526038
+
 ## License
 
 The MIT License (MIT). Read [LICENSE](LICENSE).

benchmark/benchmark_test.go

@@ -321,6 +321,7 @@ type benchmarkDoc struct {
 		Key1 []int64
 		Key2 []string
 		Key3 [][]int64
+		// TODO: Key4 not supported by go-toml's Unmarshal
 		Key4 []interface{}
 		Key5 []int64
 		Key6 []int64

decode.go

@@ -99,13 +99,36 @@ func parseDateTime(b []byte) (time.Time, error) {
 		if len(b) != dateTimeByteLen {
 			return time.Time{}, newDecodeError(b, "invalid date-time timezone")
 		}
-		direction := 1
+		var direction int
-		if b[0] == '-' {
+		switch b[0] {
+		case '-':
 			direction = -1
+		case '+':
+			direction = +1
+		default:
+			return time.Time{}, newDecodeError(b[:1], "invalid timezone offset character")
+		}
+
+		if b[3] != ':' {
+			return time.Time{}, newDecodeError(b[3:4], "expected a : separator")
+		}
+
+		hours, err := parseDecimalDigits(b[1:3])
+		if err != nil {
+			return time.Time{}, err
+		}
+		if hours > 23 {
+			return time.Time{}, newDecodeError(b[:1], "invalid timezone offset hours")
+		}
+
+		minutes, err := parseDecimalDigits(b[4:6])
+		if err != nil {
+			return time.Time{}, err
+		}
+		if minutes > 59 {
+			return time.Time{}, newDecodeError(b[:1], "invalid timezone offset minutes")
 		}
 
-		hours := digitsToInt(b[1:3])
-		minutes := digitsToInt(b[4:6])
 		seconds := direction * (hours*3600 + minutes*60)
 		zone = time.FixedZone("", seconds)
 		b = b[dateTimeByteLen:]
@@ -201,45 +224,53 @@ func parseLocalTime(b []byte) (LocalTime, []byte, error) {
 		return t, nil, err
 	}
 
-	if t.Second > 59 {
+	if t.Second > 60 {
-		return t, nil, newDecodeError(b[3:5], "seconds cannot be greater 59")
+		return t, nil, newDecodeError(b[6:8], "seconds cannot be greater 60")
 	}
 
-	const minLengthWithFrac = 9
+	b = b[8:]
-	if len(b) >= minLengthWithFrac && b[minLengthWithFrac-1] == '.' {
+
+	if len(b) >= 1 && b[0] == '.' {
 		frac := 0
+		precision := 0
 		digits := 0
 
-		for i, c := range b[minLengthWithFrac:] {
+		for i, c := range b[1:] {
 			if !isDigit(c) {
 				if i == 0 {
-					return t, nil, newDecodeError(b[i:i+1], "need at least one digit after fraction point")
+					return t, nil, newDecodeError(b[0:1], "need at least one digit after fraction point")
 				}
-
 				break
 			}
+			digits++
 
 			const maxFracPrecision = 9
 			if i >= maxFracPrecision {
-				return t, nil, newDecodeError(b[i:i+1], "maximum precision for date time is nanosecond")
+				// go-toml allows decoding fractional seconds
+				// beyond the supported precision of 9
+				// digits. It truncates the fractional component
+				// to the supported precision and ignores the
+				// remaining digits.
+				//
+				// https://github.com/pelletier/go-toml/discussions/707
+				continue
 			}
 
 			frac *= 10
 			frac += int(c - '0')
-			digits++
+			precision++
 		}
 
-		if digits == 0 {
+		if precision == 0 {
-			return t, nil, newDecodeError(b[minLengthWithFrac-1:minLengthWithFrac], "nanoseconds need at least one digit")
+			return t, nil, newDecodeError(b[:1], "nanoseconds need at least one digit")
 		}
 
-		t.Nanosecond = frac * nspow[digits]
+		t.Nanosecond = frac * nspow[precision]
-		t.Precision = digits
+		t.Precision = precision
 
-		return t, b[9+digits:], nil
+		return t, b[1+digits:], nil
 	}
-
+	return t, b, nil
-	return t, b[8:], nil
 }
 
 //nolint:cyclop
@@ -364,8 +395,17 @@ func parseIntDec(b []byte) (int64, error) {
 }
 
 func checkAndRemoveUnderscoresIntegers(b []byte) ([]byte, error) {
-	if b[0] == '_' {
+	start := 0
-		return nil, newDecodeError(b[0:1], "number cannot start with underscore")
+	if b[start] == '+' || b[start] == '-' {
+		start++
+	}
+
+	if len(b) == start {
+		return b, nil
+	}
+
+	if b[start] == '_' {
+		return nil, newDecodeError(b[start:start+1], "number cannot start with underscore")
 	}
 
 	if b[len(b)-1] == '_' {
@@ -438,6 +478,10 @@ func checkAndRemoveUnderscoresFloats(b []byte) ([]byte, error) {
 				return nil, newDecodeError(b[i+1:i+2], "cannot have underscore before exponent")
 			}
 			before = false
+		case '+', '-':
+			// signed exponents
+			cleaned = append(cleaned, c)
+			before = false
 		case 'e', 'E':
 			if i < len(b)-1 && b[i+1] == '_' {
 				return nil, newDecodeError(b[i+1:i+2], "cannot have underscore after exponent")
@@ -462,7 +506,7 @@ func checkAndRemoveUnderscoresFloats(b []byte) ([]byte, error) {
 
 // isValidDate checks if a provided date is a date that exists.
 func isValidDate(year int, month int, day int) bool {
-	return day <= daysIn(month, year)
+	return month > 0 && month < 13 && day > 0 && day <= daysIn(month, year)
 }
 
 // daysBefore[m] counts the number of days in a non-leap year

errors_test.go

@@ -212,12 +212,12 @@ func ExampleDecodeError() {
 
 	fmt.Println(err)
 
-	//nolint:errorlint
+	var derr *DecodeError
-	de := err.(*DecodeError)
+	if errors.As(err, &derr) {
-	fmt.Println(de.String())
+		fmt.Println(derr.String())
-
+		row, col := derr.Position()
-	row, col := de.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

internal/ast/ast.go

@@ -20,8 +20,8 @@ type Iterator struct {
 	node    *Node
 }
 
-// Next moves the iterator forward and returns true if points to a node, false
+// Next moves the iterator forward and returns true if points to a
-// otherwise.
+// node, false otherwise.
 func (c *Iterator) Next() bool {
 	if !c.started {
 		c.started = true
@@ -31,8 +31,8 @@ func (c *Iterator) Next() bool {
 	return c.node.Valid()
 }
 
-// IsLast returns true if the current node of the iterator is the last one.
+// IsLast returns true if the current node of the iterator is the last
-// Subsequent call to Next() will return false.
+// one.  Subsequent call to Next() will return false.
 func (c *Iterator) IsLast() bool {
 	return c.node.next == 0
 }
@@ -62,20 +62,20 @@ func (r *Root) at(idx Reference) *Node {
 	return &r.nodes[idx]
 }
 
-// Arrays have one child per element in the array.
+// Arrays have one child per element in the array.  InlineTables have
-// InlineTables have one child per key-value pair in the table.
+// one child per key-value pair in the table.  KeyValues have at least
-// KeyValues have at least two children. The first one is the value. The
+// two children. The first one is the value. The rest make a
-// rest make a potentially dotted key.
+// potentially dotted key.  Table and Array table have one child per
-// Table and Array table have one child per element of the key they
+// element of the key they represent (same as KeyValue, but without
-// represent (same as KeyValue, but without the last node being the value).
+// the last node being the value).
-// children []Node
 type Node struct {
 	Kind Kind
 	Raw  Range  // Raw bytes from the input.
-	Data []byte // Node value (could be either allocated or referencing the input).
+	Data []byte // Node value (either allocated or referencing the input).
 
-	// References to other nodes, as offsets in the backing array from this
+	// References to other nodes, as offsets in the backing array
-	// node. References can go backward, so those can be negative.
+	// from this node. References can go backward, so those can be
+	// negative.
 	next  int // 0 if last element
 	child int // 0 if no child
 }
@@ -85,8 +85,8 @@ type Range struct {
 	Length uint32
 }
 
-// Next returns a copy of the next node, or an invalid Node if there is no
+// Next returns a copy of the next node, or an invalid Node if there
-// next node.
+// is no next node.
 func (n *Node) Next() *Node {
 	if n.next == 0 {
 		return nil
@@ -96,9 +96,9 @@ func (n *Node) Next() *Node {
 	return (*Node)(danger.Stride(ptr, size, n.next))
 }
 
-// Child returns a copy of the first child node of this node. Other children
+// Child returns a copy of the first child node of this node. Other
-// can be accessed calling Next on the first child.
+// children can be accessed calling Next on the first child.  Returns
-// Returns an invalid Node if there is none.
+// an invalid Node if there is none.
 func (n *Node) Child() *Node {
 	if n.child == 0 {
 		return nil
@@ -113,10 +113,9 @@ func (n *Node) Valid() bool {
 	return n != nil
 }
 
-// Key returns the child nodes making the Key on a supported node. Panics
+// Key returns the child nodes making the Key on a supported
-// otherwise.
+// node. Panics otherwise.  They are guaranteed to be all be of the
-// They are guaranteed to be all be of the Kind Key. A simple key would return
+// Kind Key. A simple key would return just one element.
-// just one element.
 func (n *Node) Key() Iterator {
 	switch n.Kind {
 	case KeyValue:
@@ -133,8 +132,8 @@ func (n *Node) Key() Iterator {
 }
 
 // Value returns a pointer to the value node of a KeyValue.
-// Guaranteed to be non-nil.
+// Guaranteed to be non-nil.  Panics if not called on a KeyValue node,
-// Panics if not called on a KeyValue node, or if the Children are malformed.
+// or if the Children are malformed.
 func (n *Node) Value() *Node {
 	return n.Child()
 }

internal/danger/danger.go

@@ -63,14 +63,3 @@ func Stride(ptr unsafe.Pointer, size uintptr, offset int) unsafe.Pointer {
 	//   https://github.com/golang/go/issues/40481
 	return unsafe.Pointer(uintptr(ptr) + uintptr(int(size)*offset))
 }
-
-type Slice struct {
-	Data unsafe.Pointer
-	Len  int
-	Cap  int
-}
-
-type iface struct {
-	typ unsafe.Pointer
-	ptr unsafe.Pointer
-}

internal/danger/slices.go

@@ -1,20 +0,0 @@
-//go:build go1.18
-// +build go1.18
-
-package danger
-
-import (
-	"reflect"
-	"unsafe"
-)
-
-func ExtendSlice(t reflect.Type, s *Slice, n int) Slice {
-	arrayType := reflect.ArrayOf(n, t.Elem())
-	arrayData := reflect.New(arrayType)
-	reflect.Copy(arrayData.Elem(), reflect.NewAt(t, unsafe.Pointer(s)).Elem())
-	return Slice{
-		Data: unsafe.Pointer(arrayData.Pointer()),
-		Len:  s.Len,
-		Cap:  n,
-	}
-}

internal/danger/slices_optimized.go

@@ -1,30 +0,0 @@
-//go:build !go1.18
-// +build !go1.18
-
-package danger
-
-import (
-	"reflect"
-	"unsafe"
-)
-
-//go:linkname unsafe_NewArray reflect.unsafe_NewArray
-func unsafe_NewArray(rtype unsafe.Pointer, length int) unsafe.Pointer
-
-//go:linkname typedslicecopy reflect.typedslicecopy
-//go:noescape
-func typedslicecopy(elemType unsafe.Pointer, dst, src Slice) int
-
-func ExtendSlice(t reflect.Type, s *Slice, n int) Slice {
-	elemTypeRef := t.Elem()
-	elemTypePtr := ((*iface)(unsafe.Pointer(&elemTypeRef))).ptr
-
-	d := Slice{
-		Data: unsafe_NewArray(elemTypePtr, n),
-		Len:  s.Len,
-		Cap:  n,
-	}
-
-	typedslicecopy(elemTypePtr, d, *s)
-	return d
-}

internal/imported_tests/unmarshal_imported_test.go

@@ -457,35 +457,6 @@ func TestEmptytomlUnmarshal(t *testing.T) {
 	assert.Equal(t, emptyTestData, result)
 }
 
-func TestEmptyUnmarshalOmit(t *testing.T) {
-	t.Skipf("Have not figured yet if omitempty is a good idea")
-
-	type emptyMarshalTestStruct2 struct {
-		Title      string                  `toml:"title"`
-		Bool       bool                    `toml:"bool,omitempty"`
-		Int        int                     `toml:"int, omitempty"`
-		String     string                  `toml:"string,omitempty "`
-		StringList []string                `toml:"stringlist,omitempty"`
-		Ptr        *basicMarshalTestStruct `toml:"ptr,omitempty"`
-		Map        map[string]string       `toml:"map,omitempty"`
-	}
-
-	emptyTestData2 := emptyMarshalTestStruct2{
-		Title:      "Placeholder",
-		Bool:       false,
-		Int:        0,
-		String:     "",
-		StringList: []string{},
-		Ptr:        nil,
-		Map:        map[string]string{},
-	}
-
-	result := emptyMarshalTestStruct2{}
-	err := toml.Unmarshal(emptyTestToml, &result)
-	require.NoError(t, err)
-	assert.Equal(t, emptyTestData2, result)
-}
-
 type pointerMarshalTestStruct struct {
 	Str       *string
 	List      *[]string

internal/tracker/seen.go

@@ -3,6 +3,7 @@ package tracker
 import (
 	"bytes"
 	"fmt"
+	"sync"
 
 	"github.com/pelletier/go-toml/v2/internal/ast"
 )
@@ -54,69 +55,103 @@ func (k keyKind) String() string {
 type SeenTracker struct {
 	entries    []entry
 	currentIdx int
-	nextID     int
+}
+
+var pool sync.Pool
+
+func (s *SeenTracker) reset() {
+	// Always contains a root element at index 0.
+	s.currentIdx = 0
+	if len(s.entries) == 0 {
+		s.entries = make([]entry, 1, 2)
+	} else {
+		s.entries = s.entries[:1]
+	}
+	s.entries[0].child = -1
+	s.entries[0].next = -1
 }
 
 type entry struct {
-	id       int
+	// Use -1 to indicate no child or no sibling.
-	parent   int
+	child int
+	next  int
+
 	name     []byte
 	kind     keyKind
 	explicit bool
 }
 
-// Remove all descendants of node at position idx.
+// Find the index of the child of parentIdx with key k. Returns -1 if
-func (s *SeenTracker) clear(idx int) {
+// it does not exist.
-	p := s.entries[idx].id
+func (s *SeenTracker) find(parentIdx int, k []byte) int {
-	rest := clear(p, s.entries[idx+1:])
+	for i := s.entries[parentIdx].child; i >= 0; i = s.entries[i].next {
-	s.entries = s.entries[:idx+1+len(rest)]
+		if bytes.Equal(s.entries[i].name, k) {
+			return i
+		}
+	}
+	return -1
 }
 
-func clear(parentID int, entries []entry) []entry {
+// Remove all descendants of node at position idx.
-	for i := 0; i < len(entries); {
+func (s *SeenTracker) clear(idx int) {
-		if entries[i].parent == parentID {
+	if idx >= len(s.entries) {
-			id := entries[i].id
+		return
-			copy(entries[i:], entries[i+1:])
-			entries = entries[:len(entries)-1]
-			rest := clear(id, entries[i:])
-			entries = entries[:i+len(rest)]
-		} else {
-			i++
 	}
+
+	for i := s.entries[idx].child; i >= 0; {
+		next := s.entries[i].next
+		n := s.entries[0].next
+		s.entries[0].next = i
+		s.entries[i].next = n
+		s.entries[i].name = nil
+		s.clear(i)
+		i = next
 	}
-	return entries
+
+	s.entries[idx].child = -1
 }
 
 func (s *SeenTracker) create(parentIdx int, name []byte, kind keyKind, explicit bool) int {
-	parentID := s.id(parentIdx)
+	e := entry{
+		child: -1,
+		next:  s.entries[parentIdx].child,
 
-	idx := len(s.entries)
-	s.entries = append(s.entries, entry{
-		id:       s.nextID,
-		parent:   parentID,
 		name:     name,
 		kind:     kind,
 		explicit: explicit,
-	})
+	}
-	s.nextID++
+	var idx int
+	if s.entries[0].next >= 0 {
+		idx = s.entries[0].next
+		s.entries[0].next = s.entries[idx].next
+		s.entries[idx] = e
+	} else {
+		idx = len(s.entries)
+		s.entries = append(s.entries, e)
+	}
+
+	s.entries[parentIdx].child = idx
+
 	return idx
 }
 
+func (s *SeenTracker) setExplicitFlag(parentIdx int) {
+	for i := s.entries[parentIdx].child; i >= 0; i = s.entries[i].next {
+		s.entries[i].explicit = true
+		s.setExplicitFlag(i)
+	}
+}
+
 // CheckExpression takes a top-level node and checks that it does not contain
 // keys that have been seen in previous calls, and validates that types are
 // consistent.
 func (s *SeenTracker) CheckExpression(node *ast.Node) error {
 	if s.entries == nil {
-		// Skip ID = 0 to remove the confusion between nodes whose
+		s.reset()
-		// parent has id 0 and root nodes (parent id is 0 because it's
-		// the zero value).
-		s.nextID = 1
-		// Start unscoped, so idx is negative.
-		s.currentIdx = -1
 	}
 	switch node.Kind {
 	case ast.KeyValue:
-		return s.checkKeyValue(s.currentIdx, node)
+		return s.checkKeyValue(node)
 	case ast.Table:
 		return s.checkTable(node)
 	case ast.ArrayTable:
@@ -127,9 +162,13 @@ func (s *SeenTracker) CheckExpression(node *ast.Node) error {
 }
 
 func (s *SeenTracker) checkTable(node *ast.Node) error {
+	if s.currentIdx >= 0 {
+		s.setExplicitFlag(s.currentIdx)
+	}
+
 	it := node.Key()
 
-	parentIdx := -1
+	parentIdx := 0
 
 	// This code is duplicated in checkArrayTable. This is because factoring
 	// it in a function requires to copy the iterator, or allocate it to the
@@ -145,6 +184,11 @@ func (s *SeenTracker) checkTable(node *ast.Node) error {
 
 		if idx < 0 {
 			idx = s.create(parentIdx, k, tableKind, false)
+		} else {
+			entry := s.entries[idx]
+			if entry.kind == valueKind {
+				return fmt.Errorf("toml: expected %s to be a table, not a %s", string(k), entry.kind)
+			}
 		}
 		parentIdx = idx
 	}
@@ -171,9 +215,13 @@ func (s *SeenTracker) checkTable(node *ast.Node) error {
 }
 
 func (s *SeenTracker) checkArrayTable(node *ast.Node) error {
+	if s.currentIdx >= 0 {
+		s.setExplicitFlag(s.currentIdx)
+	}
+
 	it := node.Key()
 
-	parentIdx := -1
+	parentIdx := 0
 
 	for it.Next() {
 		if it.IsLast() {
@@ -186,7 +234,13 @@ func (s *SeenTracker) checkArrayTable(node *ast.Node) error {
 
 		if idx < 0 {
 			idx = s.create(parentIdx, k, tableKind, false)
+		} else {
+			entry := s.entries[idx]
+			if entry.kind == valueKind {
+				return fmt.Errorf("toml: expected %s to be a table, not a %s", string(k), entry.kind)
 			}
+		}
+
 		parentIdx = idx
 	}
 
@@ -208,7 +262,8 @@ func (s *SeenTracker) checkArrayTable(node *ast.Node) error {
 	return nil
 }
 
-func (s *SeenTracker) checkKeyValue(parentIdx int, node *ast.Node) error {
+func (s *SeenTracker) checkKeyValue(node *ast.Node) error {
+	parentIdx := s.currentIdx
 	it := node.Key()
 
 	for it.Next() {
@@ -238,67 +293,59 @@ func (s *SeenTracker) checkKeyValue(parentIdx int, node *ast.Node) error {
 
 	switch value.Kind {
 	case ast.InlineTable:
-		return s.checkInlineTable(parentIdx, value)
+		return s.checkInlineTable(value)
 	case ast.Array:
-		return s.checkArray(parentIdx, value)
+		return s.checkArray(value)
 	}
 
 	return nil
 }
 
-func (s *SeenTracker) checkArray(parentIdx int, node *ast.Node) error {
+func (s *SeenTracker) checkArray(node *ast.Node) error {
-	set := false
 	it := node.Children()
 	for it.Next() {
-		if set {
-			s.clear(parentIdx)
-		}
 		n := it.Node()
 		switch n.Kind {
 		case ast.InlineTable:
-			err := s.checkInlineTable(parentIdx, n)
+			err := s.checkInlineTable(n)
 			if err != nil {
 				return err
 			}
-			set = true
 		case ast.Array:
-			err := s.checkArray(parentIdx, n)
+			err := s.checkArray(n)
 			if err != nil {
 				return err
 			}
-			set = true
 		}
 	}
 	return nil
 }
 
-func (s *SeenTracker) checkInlineTable(parentIdx int, node *ast.Node) error {
+func (s *SeenTracker) checkInlineTable(node *ast.Node) error {
+	if pool.New == nil {
+		pool.New = func() interface{} {
+			return &SeenTracker{}
+		}
+	}
+
+	s = pool.Get().(*SeenTracker)
+	s.reset()
+
 	it := node.Children()
 	for it.Next() {
 		n := it.Node()
-		err := s.checkKeyValue(parentIdx, n)
+		err := s.checkKeyValue(n)
 		if err != nil {
 			return err
 		}
 	}
+
+	// As inline tables are self-contained, the tracker does not
+	// need to retain the details of what they contain. The
+	// keyValue element that creates the inline table is kept to
+	// mark the presence of the inline table and prevent
+	// redefinition of its keys: check* functions cannot walk into
+	// a value.
+	pool.Put(s)
 	return nil
 }
-
-func (s *SeenTracker) id(idx int) int {
-	if idx >= 0 {
-		return s.entries[idx].id
-	}
-	return 0
-}
-
-func (s *SeenTracker) find(parentIdx int, k []byte) int {
-	parentID := s.id(parentIdx)
-
-	for i := parentIdx + 1; i < len(s.entries); i++ {
-		if s.entries[i].parent == parentID && bytes.Equal(s.entries[i].name, k) {
-			return i
-		}
-	}
-
-	return -1
-}

marshaler.go

@@ -11,6 +11,7 @@ import (
 	"strconv"
 	"strings"
 	"time"
+	"unicode"
 )
 
 // Marshal serializes a Go value as a TOML document.
@@ -103,27 +104,31 @@ func (enc *Encoder) SetIndentTables(indent bool) *Encoder {
 // 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
+// a newline character or a single quote. In that case they are emitted as
-// strings.
+// quoted strings.
 //
 // When encoding structs, fields are encoded in order of definition, with their
 // exact name.
 //
 // Struct tags
 //
-// The following struct tags are available to tweak encoding on a per-field
+// The encoding of each public struct field can be customized by the format
-// basis:
+// 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.
 //
-//   toml:"foo"
+// The "multiline" option emits strings as quoted multi-line TOML strings. It
-//     Changes the name of the key to use for the field to foo.
+// has no effect on fields that would not be encoded as strings.
 //
-//   multiline:"true"
+// The "inline" option turns fields that would be emitted as tables into inline
-//     When the field contains a string, it will be emitted as a quoted
+// tables instead. It has no effect on other fields.
-//     multi-line TOML string.
 //
-//   inline:"true"
+// The "omitempty" option prevents empty values or groups from being emitted.
-//     When the field would normally be encoded as a table, it is instead
+//
-//     encoded as an inline table.
+// 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 (enc *Encoder) Encode(v interface{}) error {
 	var (
 		b   []byte
@@ -151,6 +156,8 @@ func (enc *Encoder) Encode(v interface{}) error {
 
 type valueOptions struct {
 	multiline bool
+	omitempty bool
+	comment   string
 }
 
 type encoderCtx struct {
@@ -200,7 +207,6 @@ func (ctx *encoderCtx) isRoot() bool {
 	return len(ctx.parentKey) == 0 && !ctx.hasKey
 }
 
-//nolint:cyclop,funlen
 func (enc *Encoder) encode(b []byte, ctx encoderCtx, v reflect.Value) ([]byte, error) {
 	if !v.IsZero() {
 		i, ok := v.Interface().(time.Time)
@@ -209,7 +215,12 @@ func (enc *Encoder) encode(b []byte, ctx encoderCtx, v reflect.Value) ([]byte, e
 		}
 	}
 
-	if v.Type().Implements(textMarshalerType) {
+	hasTextMarshaler := v.Type().Implements(textMarshalerType)
+	if hasTextMarshaler || (v.CanAddr() && reflect.PtrTo(v.Type()).Implements(textMarshalerType)) {
+		if !hasTextMarshaler {
+			v = v.Addr()
+		}
+
 		if ctx.isRoot() {
 			return nil, fmt.Errorf("toml: type %s implementing the TextMarshaler interface cannot be a root element", v.Type())
 		}
@@ -292,6 +303,15 @@ func (enc *Encoder) encodeKv(b []byte, ctx encoderCtx, options valueOptions, v r
 	if !ctx.hasKey {
 		panic("caller of encodeKv should have set the key in the context")
 	}
+
+	if (ctx.options.omitempty || options.omitempty) && isEmptyValue(v) {
+		return b, nil
+	}
+
+	if !ctx.inline {
+		b = enc.encodeComment(ctx.indent, options.comment, b)
+	}
+
 	b = enc.indent(ctx.indent, b)
 
 	b, err = enc.encodeKey(b, ctx.key)
@@ -316,6 +336,24 @@ func (enc *Encoder) encodeKv(b []byte, ctx encoderCtx, options valueOptions, v r
 	return b, nil
 }
 
+func isEmptyValue(v reflect.Value) bool {
+	switch v.Kind() {
+	case reflect.Array, reflect.Map, reflect.Slice, reflect.String:
+		return v.Len() == 0
+	case reflect.Bool:
+		return !v.Bool()
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return v.Int() == 0
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+		return v.Uint() == 0
+	case reflect.Float32, reflect.Float64:
+		return v.Float() == 0
+	case reflect.Interface, reflect.Ptr:
+		return v.IsNil()
+	}
+	return false
+}
+
 const literalQuote = '\''
 
 func (enc *Encoder) encodeString(b []byte, v string, options valueOptions) []byte {
@@ -409,6 +447,8 @@ func (enc *Encoder) encodeTableHeader(ctx encoderCtx, b []byte) ([]byte, error)
 		return b, nil
 	}
 
+	b = enc.encodeComment(ctx.indent, ctx.options.comment, b)
+
 	b = enc.indent(ctx.indent, b)
 
 	b = append(b, '[')
@@ -525,8 +565,7 @@ func (t *table) pushTable(k string, v reflect.Value, options valueOptions) {
 func (enc *Encoder) encodeStruct(b []byte, ctx encoderCtx, v reflect.Value) ([]byte, error) {
 	var t table
 
-	//nolint:godox
+	// TODO: cache this
-	// TODO: cache this?
 	typ := v.Type()
 	for i := 0; i < typ.NumField(); i++ {
 		fieldType := typ.Field(i)
@@ -536,16 +575,20 @@ func (enc *Encoder) encodeStruct(b []byte, ctx encoderCtx, v reflect.Value) ([]b
 			continue
 		}
 
-		k, ok := fieldType.Tag.Lookup("toml")
+		k := fieldType.Name
-		if !ok {
+
-			k = fieldType.Name
+		tag := fieldType.Tag.Get("toml")
-		}
 
 		// special field name to skip field
-		if k == "-" {
+		if tag == "-" {
 			continue
 		}
 
+		name, opts := parseTag(tag)
+		if isValidName(name) {
+			k = name
+		}
+
 		f := v.Field(i)
 
 		if isNil(f) {
@@ -553,12 +596,12 @@ func (enc *Encoder) encodeStruct(b []byte, ctx encoderCtx, v reflect.Value) ([]b
 		}
 
 		options := valueOptions{
-			multiline: fieldBoolTag(fieldType, "multiline"),
+			multiline: opts.multiline,
+			omitempty: opts.omitempty,
+			comment:   fieldType.Tag.Get("comment"),
 		}
 
-		inline := fieldBoolTag(fieldType, "inline")
+		if opts.inline || !willConvertToTableOrArrayTable(ctx, f) {
-
-		if inline || !willConvertToTableOrArrayTable(ctx, f) {
 			t.pushKV(k, f, options)
 		} else {
 			t.pushTable(k, f, options)
@@ -568,13 +611,70 @@ func (enc *Encoder) encodeStruct(b []byte, ctx encoderCtx, v reflect.Value) ([]b
 	return enc.encodeTable(b, ctx, t)
 }
 
-func fieldBoolTag(field reflect.StructField, tag string) bool {
+func (enc *Encoder) encodeComment(indent int, comment string, b []byte) []byte {
-	x, ok := field.Tag.Lookup(tag)
+	if comment != "" {
-
+		b = enc.indent(indent, b)
-	return ok && x == "true"
+		b = append(b, "# "...)
+		b = append(b, comment...)
+		b = append(b, '\n')
+	}
+	return b
+}
+
+func isValidName(s string) bool {
+	if s == "" {
+		return false
+	}
+	for _, c := range s {
+		switch {
+		case strings.ContainsRune("!#$%&()*+-./:;<=>?@[]^_{|}~ ", c):
+			// Backslash and quote chars are reserved, but
+			// otherwise any punctuation chars are allowed
+			// in a tag name.
+		case !unicode.IsLetter(c) && !unicode.IsDigit(c):
+			return false
+		}
+	}
+	return true
+}
+
+type tagOptions struct {
+	multiline bool
+	inline    bool
+	omitempty bool
+}
+
+func parseTag(tag string) (string, tagOptions) {
+	opts := tagOptions{}
+
+	idx := strings.Index(tag, ",")
+	if idx == -1 {
+		return tag, opts
+	}
+
+	raw := tag[idx+1:]
+	tag = string(tag[:idx])
+	for raw != "" {
+		var o string
+		i := strings.Index(raw, ",")
+		if i >= 0 {
+			o, raw = raw[:i], raw[i+1:]
+		} else {
+			o, raw = raw, ""
+		}
+		switch o {
+		case "multiline":
+			opts.multiline = true
+		case "inline":
+			opts.inline = true
+		case "omitempty":
+			opts.omitempty = true
+		}
+	}
+
+	return tag, opts
 }
 
-//nolint:cyclop
 func (enc *Encoder) encodeTable(b []byte, ctx encoderCtx, t table) ([]byte, error) {
 	var err error
 
@@ -657,7 +757,7 @@ func willConvertToTable(ctx encoderCtx, v reflect.Value) bool {
 	if !v.IsValid() {
 		return false
 	}
-	if v.Type() == timeType || v.Type().Implements(textMarshalerType) {
+	if v.Type() == timeType || v.Type().Implements(textMarshalerType) || (v.Kind() != reflect.Ptr && v.CanAddr() && reflect.PtrTo(v.Type()).Implements(textMarshalerType)) {
 		return false
 	}
 

marshaler_test.go

@@ -4,20 +4,27 @@ import (
 	"bytes"
 	"encoding/json"
 	"fmt"
+	"math/big"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/pelletier/go-toml/v2"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
-//nolint:funlen
 func TestMarshal(t *testing.T) {
 	someInt := 42
 
 	type structInline struct {
-		A interface{} `inline:"true"`
+		A interface{} `toml:",inline"`
+	}
+
+	type comments struct {
+		One   int
+		Two   int   `comment:"Before kv"`
+		Three []int `comment:"Before array"`
 	}
 
 	examples := []struct {
@@ -193,9 +200,9 @@ name = 'Alice'
 		{
 			desc: "string escapes",
 			v: map[string]interface{}{
-				"a": `'"\`,
+				"a": "'\b\f\r\t\"\\",
 			},
-			expected: `a = "'\"\\"`,
+			expected: `a = "'\b\f\r\t\"\\"`,
 		},
 		{
 			desc: "string utf8 low",
@@ -242,7 +249,7 @@ name = 'Alice'
 		{
 			desc: "multi-line forced",
 			v: struct {
-				A string `multiline:"true"`
+				A string `toml:",multiline"`
 			}{
 				A: "hello\nworld",
 			},
@@ -253,7 +260,7 @@ world"""`,
 		{
 			desc: "inline field",
 			v: struct {
-				A map[string]string `inline:"true"`
+				A map[string]string `toml:",inline"`
 				B map[string]string
 			}{
 				A: map[string]string{
@@ -272,7 +279,7 @@ isinline = 'no'
 		{
 			desc: "mutiline array int",
 			v: struct {
-				A []int `multiline:"true"`
+				A []int `toml:",multiline"`
 				B []int
 			}{
 				A: []int{1, 2, 3, 4},
@@ -291,7 +298,7 @@ B = [1, 2, 3, 4]
 		{
 			desc: "mutiline array in array",
 			v: struct {
-				A [][]int `multiline:"true"`
+				A [][]int `toml:",multiline"`
 			}{
 				A: [][]int{{1, 2}, {3, 4}},
 			},
@@ -469,6 +476,28 @@ hello = 'world'`,
 			},
 			err: true,
 		},
+		{
+			desc: "time",
+			v: struct {
+				T time.Time
+			}{
+				T: time.Time{},
+			},
+			expected: `T = '0001-01-01T00:00:00Z'`,
+		},
+		{
+			desc: "bool",
+			v: struct {
+				A bool
+				B bool
+			}{
+				A: false,
+				B: true,
+			},
+			expected: `
+A = false
+B = true`,
+		},
 		{
 			desc: "numbers",
 			v: struct {
@@ -483,6 +512,7 @@ hello = 'world'`,
 				I int16
 				J int8
 				K int
+				L float64
 			}{
 				A: 1.1,
 				B: 42,
@@ -495,6 +525,7 @@ hello = 'world'`,
 				I: 42,
 				J: 42,
 				K: 42,
+				L: 2.2,
 			},
 			expected: `
 A = 1.1
@@ -507,7 +538,29 @@ G = 42
 H = 42
 I = 42
 J = 42
-K = 42`,
+K = 42
+L = 2.2`,
+		},
+		{
+			desc: "comments",
+			v: struct {
+				Table comments `comment:"Before table"`
+			}{
+				Table: comments{
+					One:   1,
+					Two:   2,
+					Three: []int{1, 2, 3},
+				},
+			},
+			expected: `
+# Before table
+[Table]
+One = 1
+# Before kv
+Two = 2
+# Before array
+Three = [1, 2, 3]
+`,
 		},
 	}
 
@@ -734,6 +787,60 @@ func TestEncoderSetIndentSymbol(t *testing.T) {
 	equalStringsIgnoreNewlines(t, expected, w.String())
 }
 
+func TestEncoderOmitempty(t *testing.T) {
+	type doc struct {
+		String  string            `toml:",omitempty,multiline"`
+		Bool    bool              `toml:",omitempty,multiline"`
+		Int     int               `toml:",omitempty,multiline"`
+		Int8    int8              `toml:",omitempty,multiline"`
+		Int16   int16             `toml:",omitempty,multiline"`
+		Int32   int32             `toml:",omitempty,multiline"`
+		Int64   int64             `toml:",omitempty,multiline"`
+		Uint    uint              `toml:",omitempty,multiline"`
+		Uint8   uint8             `toml:",omitempty,multiline"`
+		Uint16  uint16            `toml:",omitempty,multiline"`
+		Uint32  uint32            `toml:",omitempty,multiline"`
+		Uint64  uint64            `toml:",omitempty,multiline"`
+		Float32 float32           `toml:",omitempty,multiline"`
+		Float64 float64           `toml:",omitempty,multiline"`
+		MapNil  map[string]string `toml:",omitempty,multiline"`
+		Slice   []string          `toml:",omitempty,multiline"`
+		Ptr     *string           `toml:",omitempty,multiline"`
+		Iface   interface{}       `toml:",omitempty,multiline"`
+		Struct  struct{}          `toml:",omitempty,multiline"`
+	}
+
+	d := doc{}
+
+	b, err := toml.Marshal(d)
+	require.NoError(t, err)
+
+	expected := `[Struct]`
+
+	equalStringsIgnoreNewlines(t, expected, string(b))
+}
+
+func TestEncoderTagFieldName(t *testing.T) {
+	type doc struct {
+		String string `toml:"hello"`
+		OkSym  string `toml:"#"`
+		Bad    string `toml:"\"`
+	}
+
+	d := doc{String: "world"}
+
+	b, err := toml.Marshal(d)
+	require.NoError(t, err)
+
+	expected := `
+hello = 'world'
+'#' = ''
+Bad = ''
+`
+
+	equalStringsIgnoreNewlines(t, expected, string(b))
+}
+
 func TestIssue436(t *testing.T) {
 	data := []byte(`{"a": [ { "b": { "c": "d" } } ]}`)
 
@@ -798,6 +905,48 @@ func TestIssue590(t *testing.T) {
 	require.NoError(t, err)
 }
 
+func TestIssue571(t *testing.T) {
+	type Foo struct {
+		Float32 float32
+		Float64 float64
+	}
+
+	const closeEnough = 1e-9
+
+	foo := Foo{
+		Float32: 42,
+		Float64: 43,
+	}
+	b, err := toml.Marshal(foo)
+	require.NoError(t, err)
+
+	var foo2 Foo
+	err = toml.Unmarshal(b, &foo2)
+	require.NoError(t, err)
+
+	assert.InDelta(t, 42, foo2.Float32, closeEnough)
+	assert.InDelta(t, 43, foo2.Float64, closeEnough)
+}
+
+func TestIssue678(t *testing.T) {
+	type Config struct {
+		BigInt big.Int
+	}
+
+	cfg := &Config{
+		BigInt: *big.NewInt(123),
+	}
+
+	out, err := toml.Marshal(cfg)
+	require.NoError(t, err)
+	equalStringsIgnoreNewlines(t, "BigInt = '123'", string(out))
+
+	cfg2 := &Config{}
+	err = toml.Unmarshal(out, cfg2)
+	require.NoError(t, err)
+	require.Equal(t, cfg, cfg2)
+}
+
 func ExampleMarshal() {
 	type MyConfig struct {
 		Version int
@@ -822,26 +971,3 @@ func ExampleMarshal() {
 	// Name = 'go-toml'
 	// Tags = ['go', 'toml']
 }
-
-func TestIssue571(t *testing.T) {
-	type Foo struct {
-		Float32 float32
-		Float64 float64
-	}
-
-	const closeEnough = 1e-9
-
-	foo := Foo{
-		Float32: 42,
-		Float64: 43,
-	}
-	b, err := toml.Marshal(foo)
-	require.NoError(t, err)
-
-	var foo2 Foo
-	err = toml.Unmarshal(b, &foo2)
-	require.NoError(t, err)
-
-	assert.InDelta(t, 42, foo2.Float32, closeEnough)
-	assert.InDelta(t, 43, foo2.Float64, closeEnough)
-}

parser.go

@@ -578,6 +578,10 @@ func (p *parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, er
 				switch token[i+j] {
 				case ' ', '\t':
 					continue
+				case '\r':
+					if token[i+j+1] == '\n' {
+						continue
+					}
 				case '\n':
 					isLastNonWhitespaceOnLine = true
 				}
@@ -689,6 +693,10 @@ func (p *parser) parseKey(b []byte) (ast.Reference, []byte, error) {
 }
 
 func (p *parser) parseSimpleKey(b []byte) (raw, key, rest []byte, err error) {
+	if len(b) == 0 {
+		return nil, nil, nil, newDecodeError(b, "expected key but found none")
+	}
+
 	// simple-key = quoted-key / unquoted-key
 	// unquoted-key = 1*( ALPHA / DIGIT / %x2D / %x5F ) ; A-Z / a-z / 0-9 / - / _
 	// quoted-key = basic-string / literal-string
@@ -862,7 +870,6 @@ func (p *parser) parseIntOrFloatOrDateTime(b []byte) (ast.Reference, []byte, err
 		return p.scanIntOrFloat(b)
 	}
 
-	//nolint:gomnd
 	if len(b) < 3 {
 		return p.scanIntOrFloat(b)
 	}
@@ -887,18 +894,6 @@ func (p *parser) parseIntOrFloatOrDateTime(b []byte) (ast.Reference, []byte, err
 	return p.scanIntOrFloat(b)
 }
 
-func digitsToInt(b []byte) int {
-	x := 0
-
-	for _, d := range b {
-		x *= 10
-		x += int(d - '0')
-	}
-
-	return x
-}
-
-//nolint:gocognit,cyclop
 func (p *parser) scanDateTime(b []byte) (ast.Reference, []byte, error) {
 	// scans for contiguous characters in [0-9T:Z.+-], and up to one space if
 	// followed by a digit.

scanner.go

@@ -53,7 +53,7 @@ func scanLiteralString(b []byte) ([]byte, []byte, error) {
 		switch b[i] {
 		case '\'':
 			return b[:i+1], b[i+1:], nil
-		case '\n':
+		case '\n', '\r':
 			return nil, nil, newDecodeError(b[i:i+1], "literal strings cannot have new lines")
 		}
 		size := utf8ValidNext(b[i:])
@@ -76,6 +76,8 @@ func scanMultilineLiteralString(b []byte) ([]byte, []byte, error) {
 	// mll-char = %x09 / %x20-26 / %x28-7E / non-ascii
 	// mll-quotes = 1*2apostrophe
 	for i := 3; i < len(b); {
+		switch b[i] {
+		case '\'':
 			if scanFollowsMultilineLiteralStringDelimiter(b[i:]) {
 				i += 3
 
@@ -101,6 +103,16 @@ func scanMultilineLiteralString(b []byte) ([]byte, []byte, error) {
 
 				return b[:i], b[i:], nil
 			}
+		case '\r':
+			if len(b) < i+2 {
+				return nil, nil, newDecodeError(b[len(b):], `need a \n after \r`)
+			}
+			if b[i+1] != '\n' {
+				return nil, nil, newDecodeError(b[i:i+2], `need a \n after \r`)
+			}
+			i += 2 // skip the \n
+			continue
+		}
 		size := utf8ValidNext(b[i:])
 		if size == 0 {
 			return nil, nil, newDecodeError(b[i:i+1], "invalid character")
@@ -242,6 +254,14 @@ func scanMultilineBasicString(b []byte) ([]byte, bool, []byte, error) {
 			}
 			escaped = true
 			i++ // skip the next character
+		case '\r':
+			if len(b) < i+2 {
+				return nil, escaped, nil, newDecodeError(b[len(b):], `need a \n after \r`)
+			}
+			if b[i+1] != '\n' {
+				return nil, escaped, nil, newDecodeError(b[i:i+2], `need a \n after \r`)
+			}
+			i++ // skip the \n
 		}
 	}
 

unmarshaler.go

@@ -11,7 +11,6 @@ import (
 	"strings"
 	"sync/atomic"
 	"time"
-	"unsafe"
 
 	"github.com/pelletier/go-toml/v2/internal/ast"
 	"github.com/pelletier/go-toml/v2/internal/danger"
@@ -61,7 +60,8 @@ func (d *Decoder) SetStrict(strict bool) *Decoder {
 //
 // 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.
+// 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{}.
@@ -73,6 +73,11 @@ func (d *Decoder) SetStrict(strict bool) *Decoder {
 // 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:
@@ -132,6 +137,23 @@ type decoder struct {
 
 	// Strict mode
 	strict strict
+
+	// Current context for the error.
+	errorContext *errorContext
+}
+
+type errorContext struct {
+	Struct reflect.Type
+	Field  []int
+}
+
+func (d *decoder) typeMismatchError(toml string, target reflect.Type) error {
+	if d.errorContext != nil && d.errorContext.Struct != nil {
+		ctx := d.errorContext
+		f := ctx.Struct.FieldByIndex(ctx.Field)
+		return fmt.Errorf("toml: cannot decode TOML %s into struct field %s.%s of type %s", toml, ctx.Struct, f.Name, f.Type)
+	}
+	return fmt.Errorf("toml: cannot decode TOML %s into a Go value of type %s", toml, target)
 }
 
 func (d *decoder) expr() *ast.Node {
@@ -346,7 +368,9 @@ func (d *decoder) handleArrayTableCollection(key ast.Iterator, v reflect.Value)
 		if err != nil {
 			return reflect.Value{}, err
 		}
+		if elem.IsValid() {
 			v.Elem().Set(elem)
+		}
 
 		return v, nil
 	case reflect.Slice:
@@ -443,12 +467,20 @@ func (d *decoder) handleKeyPart(key ast.Iterator, v reflect.Value, nextFn handle
 			v.SetMapIndex(mk, mv)
 		}
 	case reflect.Struct:
-		f, found := structField(v, string(key.Node().Data))
+		path, found := structFieldPath(v, string(key.Node().Data))
 		if !found {
 			d.skipUntilTable = true
 			return reflect.Value{}, nil
 		}
 
+		if d.errorContext == nil {
+			d.errorContext = new(errorContext)
+		}
+		t := v.Type()
+		d.errorContext.Struct = t
+		d.errorContext.Field = path
+
+		f := v.FieldByIndex(path)
 		x, err := nextFn(key, f)
 		if err != nil || d.skipUntilTable {
 			return reflect.Value{}, err
@@ -456,6 +488,8 @@ func (d *decoder) handleKeyPart(key ast.Iterator, v reflect.Value, nextFn handle
 		if x.IsValid() {
 			f.Set(x)
 		}
+		d.errorContext.Field = nil
+		d.errorContext.Struct = nil
 	case reflect.Interface:
 		if v.Elem().IsValid() {
 			v = v.Elem()
@@ -621,128 +655,62 @@ func (d *decoder) handleValue(value *ast.Node, v reflect.Value) error {
 	}
 }
 
-type unmarshalArrayFn func(d *decoder, array *ast.Node, v reflect.Value) error
-
-var globalUnmarshalArrayFnCache atomic.Value // map[danger.TypeID]unmarshalArrayFn
-
-func unmarshalArrayFnForSlice(vt reflect.Type) unmarshalArrayFn {
-	tid := danger.MakeTypeID(vt)
-
-	cache, _ := globalUnmarshalArrayFnCache.Load().(map[danger.TypeID]unmarshalArrayFn)
-	fn, ok := cache[tid]
-
-	if ok {
-		return fn
-	}
-
-	elemType := vt.Elem()
-	elemSize := elemType.Size()
-
-	fn = func(d *decoder, array *ast.Node, v reflect.Value) error {
-		sp := (*danger.Slice)(unsafe.Pointer(v.UnsafeAddr()))
-
-		sp.Len = 0
-
-		it := array.Children()
-		for it.Next() {
-			n := it.Node()
-
-			idx := sp.Len
-
-			if sp.Len == sp.Cap {
-				c := sp.Cap
-				if c == 0 {
-					c = 16
-				} else {
-					c *= 2
-				}
-				*sp = danger.ExtendSlice(vt, sp, c)
-			}
-
-			datap := unsafe.Pointer(sp.Data)
-			elemp := danger.Stride(datap, elemSize, idx)
-			elem := reflect.NewAt(elemType, elemp).Elem()
-
-			err := d.handleValue(n, elem)
-			if err != nil {
-				return err
-			}
-
-			sp.Len++
-		}
-
-		if sp.Data == nil {
-			*sp = danger.ExtendSlice(vt, sp, 0)
-		}
-
-		return nil
-	}
-
-	newCache := make(map[danger.TypeID]unmarshalArrayFn, len(cache)+1)
-	newCache[tid] = fn
-	for k, v := range cache {
-		newCache[k] = v
-	}
-	globalUnmarshalArrayFnCache.Store(newCache)
-
-	return fn
-}
-
-func unmarshalArraySliceInterface(d *decoder, array *ast.Node, v reflect.Value) error {
-	sp := (*danger.Slice)(unsafe.Pointer(v.UnsafeAddr()))
-
-	sp.Len = 0
-
-	var x interface{}
-
-	it := array.Children()
-	for it.Next() {
-		n := it.Node()
-
-		idx := sp.Len
-
-		if sp.Len == sp.Cap {
-			c := sp.Cap
-			if c == 0 {
-				c = 16
-			} else {
-				c *= 2
-			}
-			*sp = danger.ExtendSlice(sliceInterfaceType, sp, c)
-		}
-
-		datap := unsafe.Pointer(sp.Data)
-		elemp := danger.Stride(datap, unsafe.Sizeof(x), idx)
-		elem := reflect.NewAt(sliceInterfaceType.Elem(), elemp).Elem()
-
-		err := d.handleValue(n, elem)
-		if err != nil {
-			return err
-		}
-
-		sp.Len++
-	}
-
-	if sp.Data == nil {
-		*sp = danger.ExtendSlice(sliceInterfaceType, sp, 0)
-	}
-
-	return nil
-}
-
 func (d *decoder) unmarshalArray(array *ast.Node, v reflect.Value) error {
 	switch v.Kind() {
 	case reflect.Slice:
-		fn := unmarshalArrayFnForSlice(v.Type())
+		if v.IsNil() {
-		return fn(d, array, v)
+			v.Set(reflect.MakeSlice(v.Type(), 0, 16))
+		} else {
+			v.SetLen(0)
+		}
 	case reflect.Array:
 		// arrays are always initialized
+	case reflect.Interface:
+		elem := v.Elem()
+		if !elem.IsValid() {
+			elem = reflect.New(sliceInterfaceType).Elem()
+			elem.Set(reflect.MakeSlice(sliceInterfaceType, 0, 16))
+		} else if elem.Kind() == reflect.Slice {
+			if elem.Type() != sliceInterfaceType {
+				elem = reflect.New(sliceInterfaceType).Elem()
+				elem.Set(reflect.MakeSlice(sliceInterfaceType, 0, 16))
+			} else if !elem.CanSet() {
+				nelem := reflect.New(sliceInterfaceType).Elem()
+				nelem.Set(reflect.MakeSlice(sliceInterfaceType, elem.Len(), elem.Cap()))
+				reflect.Copy(nelem, elem)
+				elem = nelem
+			}
+		}
+		err := d.unmarshalArray(array, elem)
+		if err != nil {
+			return err
+		}
+		v.Set(elem)
+		return nil
+	default:
+		// TODO: use newDecodeError, but first the parser needs to fill
+		//   array.Data.
+		return d.typeMismatchError("array", v.Type())
+	}
+
+	elemType := v.Type().Elem()
 
 	it := array.Children()
 	idx := 0
 	for it.Next() {
 		n := it.Node()
 
+		// TODO: optimize
+		if v.Kind() == reflect.Slice {
+			elem := reflect.New(elemType).Elem()
+
+			err := d.handleValue(n, elem)
+			if err != nil {
+				return err
+			}
+
+			v.Set(reflect.Append(v, elem))
+		} else { // array
 			if idx >= v.Len() {
 				return nil
 			}
@@ -753,39 +721,6 @@ func (d *decoder) unmarshalArray(array *ast.Node, v reflect.Value) error {
 			}
 			idx++
 		}
-	case reflect.Interface:
-		elemIsSliceInterface := false
-		elem := v.Elem()
-		if !elem.IsValid() {
-			s := make([]interface{}, 0, 16)
-			elem = reflect.ValueOf(&s).Elem()
-			elemIsSliceInterface = true
-		} else if elem.Kind() == reflect.Slice {
-			if elem.Type() != sliceInterfaceType {
-				s := make([]interface{}, 0, 16)
-				elem = reflect.ValueOf(&s).Elem()
-			} else if !elem.CanSet() {
-				s := make([]interface{}, elem.Len(), elem.Cap())
-				nelem := reflect.ValueOf(&s).Elem()
-				reflect.Copy(nelem, elem)
-				elem = nelem
-			}
-			elemIsSliceInterface = true
-		}
-
-		var err error
-		if elemIsSliceInterface {
-			err = unmarshalArraySliceInterface(d, array, elem)
-		} else {
-			err = d.unmarshalArray(array, elem)
-		}
-
-		v.Set(elem)
-		return err
-	default:
-		// TODO: use newDecodeError, but first the parser needs to fill
-		//   array.Data.
-		return fmt.Errorf("toml: cannot store array in Go type %s", v.Kind())
 	}
 
 	return nil
@@ -1002,7 +937,7 @@ func (d *decoder) unmarshalInteger(value *ast.Node, v reflect.Value) error {
 	case reflect.Interface:
 		r = reflect.ValueOf(i)
 	default:
-		return fmt.Errorf("toml: cannot store TOML integer into a Go %s", v.Kind())
+		return d.typeMismatchError("integer", v.Type())
 	}
 
 	if !r.Type().AssignableTo(v.Type()) {
@@ -1105,12 +1040,20 @@ func (d *decoder) handleKeyValuePart(key ast.Iterator, value *ast.Node, v reflec
 			v.SetMapIndex(mk, mv)
 		}
 	case reflect.Struct:
-		f, found := structField(v, string(key.Node().Data))
+		path, found := structFieldPath(v, string(key.Node().Data))
 		if !found {
 			d.skipUntilTable = true
 			break
 		}
 
+		if d.errorContext == nil {
+			d.errorContext = new(errorContext)
+		}
+		t := v.Type()
+		d.errorContext.Struct = t
+		d.errorContext.Field = path
+
+		f := v.FieldByIndex(path)
 		x, err := d.handleKeyValueInner(key, value, f)
 		if err != nil {
 			return reflect.Value{}, err
@@ -1119,6 +1062,8 @@ func (d *decoder) handleKeyValuePart(key ast.Iterator, value *ast.Node, v reflec
 		if x.IsValid() {
 			f.Set(x)
 		}
+		d.errorContext.Struct = nil
+		d.errorContext.Field = nil
 	case reflect.Interface:
 		v = v.Elem()
 
@@ -1176,12 +1121,11 @@ type fieldPathsMap = map[string][]int
 
 var globalFieldPathsCache atomic.Value // map[danger.TypeID]fieldPathsMap
 
-func structField(v reflect.Value, name string) (reflect.Value, bool) {
+func structFieldPath(v reflect.Value, name string) ([]int, bool) {
 	t := v.Type()
-	tid := danger.MakeTypeID(t)
 
 	cache, _ := globalFieldPathsCache.Load().(map[danger.TypeID]fieldPathsMap)
-	fieldPaths, ok := cache[tid]
+	fieldPaths, ok := cache[danger.MakeTypeID(t)]
 
 	if !ok {
 		fieldPaths = map[string][]int{}
@@ -1193,7 +1137,7 @@ func structField(v reflect.Value, name string) (reflect.Value, bool) {
 		})
 
 		newCache := make(map[danger.TypeID]fieldPathsMap, len(cache)+1)
-		newCache[tid] = fieldPaths
+		newCache[danger.MakeTypeID(t)] = fieldPaths
 		for k, v := range cache {
 			newCache[k] = v
 		}
@@ -1204,12 +1148,7 @@ func structField(v reflect.Value, name string) (reflect.Value, bool) {
 	if !ok {
 		path, ok = fieldPaths[strings.ToLower(name)]
 	}
-
+	return path, ok
-	if !ok {
-		return reflect.Value{}, false
-	}
-
-	return v.FieldByIndex(path), true
 }
 
 func forEachField(t reflect.Type, path []int, do func(name string, path []int)) {
@@ -1230,8 +1169,15 @@ func forEachField(t reflect.Type, path []int, do func(name string, path []int))
 			continue
 		}
 
-		name, ok := f.Tag.Lookup("toml")
+		name := f.Tag.Get("toml")
-		if !ok {
+		if name == "-" {
+			continue
+		}
+
+		if i := strings.IndexByte(name, ','); i >= 0 {
+			name = name[:i]
+		}
+		if name == "" {
 			name = f.Name
 		}
 

unmarshaler_test.go

@@ -571,7 +571,7 @@ func TestUnmarshal(t *testing.T) {
 		},
 		{
 			desc:  "multiline basic string with windows newline",
-			input: "A = \"\"\"\r\nTest\"\"\"",
+			input: "A = \"\"\"\r\nTe\r\nst\"\"\"",
 			gen: func() test {
 				type doc struct {
 					A string
@@ -579,7 +579,7 @@ func TestUnmarshal(t *testing.T) {
 
 				return test{
 					target:   &doc{},
-					expected: &doc{A: "Test"},
+					expected: &doc{A: "Te\r\nst"},
 				}
 			},
 		},
@@ -664,6 +664,36 @@ func TestUnmarshal(t *testing.T) {
 				}
 			},
 		},
+		{
+			desc:  "long string array into []string",
+			input: `A = ["0","1","2","3","4","5","6","7","8","9","10","11","12","13","14","15","16","17"]`,
+			gen: func() test {
+				type doc struct {
+					A []string
+				}
+
+				return test{
+					target:   &doc{},
+					expected: &doc{A: []string{"0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17"}},
+				}
+			},
+		},
+		{
+			desc: "long string array into []interface{}",
+			input: `A = ["0","1","2","3","4","5","6","7","8","9","10","11","12","13","14",
+"15","16","17"]`,
+			gen: func() test {
+				type doc struct {
+					A []interface{}
+				}
+
+				return test{
+					target: &doc{},
+					expected: &doc{A: []interface{}{"0", "1", "2", "3", "4", "5", "6",
+						"7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17"}},
+				}
+			},
+		},
 		{
 			desc: "standard table",
 			input: `[A]
@@ -1760,6 +1790,20 @@ func TestUnmarshalOverflows(t *testing.T) {
 	}
 }
 
+func TestUnmarshalErrors(t *testing.T) {
+	type mystruct struct {
+		Bar string
+	}
+
+	data := `bar = 42`
+
+	s := mystruct{}
+	err := toml.Unmarshal([]byte(data), &s)
+	require.Error(t, err)
+
+	require.Equal(t, "toml: cannot decode TOML integer into struct field toml_test.mystruct.Bar of type string", err.Error())
+}
+
 func TestUnmarshalInvalidTarget(t *testing.T) {
 	x := "foo"
 	err := toml.Unmarshal([]byte{}, x)
@@ -2085,7 +2129,7 @@ xz_hash = "1a48f723fea1f17d786ce6eadd9d00914d38062d28fd9c455ed3c3801905b388"
 
 	expected := doc{
 		Pkg: map[string]pkg{
-			"cargo": pkg{
+			"cargo": {
 				Target: map[string]target{
 					"aarch64-apple-darwin": {
 						XZ_URL: "https://static.rust-lang.org/dist/2021-07-29/cargo-1.54.0-aarch64-apple-darwin.tar.xz",
@@ -2190,7 +2234,119 @@ func TestIssue666(t *testing.T) {
 	require.Error(t, err)
 }
 
-//nolint:funlen
+func TestIssue677(t *testing.T) {
+	doc := `
+[Build]
+Name = "publication build"
+
+[[Build.Dependencies]]
+Name = "command"
+Program = "hugo"
+`
+
+	type _tomlJob struct {
+		Dependencies []map[string]interface{}
+	}
+
+	type tomlParser struct {
+		Build *_tomlJob
+	}
+
+	p := tomlParser{}
+
+	err := toml.Unmarshal([]byte(doc), &p)
+	require.NoError(t, err)
+
+	expected := tomlParser{
+		Build: &_tomlJob{
+			Dependencies: []map[string]interface{}{
+				{
+					"Name":    "command",
+					"Program": "hugo",
+				},
+			},
+		},
+	}
+	require.Equal(t, expected, p)
+}
+
+func TestIssue701(t *testing.T) {
+	// Expected behavior:
+	// Return an error since a cannot be modified. From the TOML spec:
+	//
+	// > Inline tables are fully self-contained and define all
+	// keys and sub-tables within them. Keys and sub-tables cannot
+	// be added outside the braces.
+
+	docs := []string{
+		`
+a={}
+[a.b]
+z=0
+`,
+		`
+a={}
+[[a.b]]
+z=0
+`,
+	}
+
+	for _, doc := range docs {
+		var v interface{}
+		err := toml.Unmarshal([]byte(doc), &v)
+		assert.Error(t, err)
+	}
+}
+
+func TestIssue703(t *testing.T) {
+	var v interface{}
+	err := toml.Unmarshal([]byte("[a]\nx.y=0\n[a.x]"), &v)
+	require.Error(t, err)
+}
+
+func TestIssue708(t *testing.T) {
+	v := map[string]string{}
+	err := toml.Unmarshal([]byte("0=\"\"\"\\\r\n\"\"\""), &v)
+	require.NoError(t, err)
+	require.Equal(t, map[string]string{"0": ""}, v)
+}
+
+func TestIssue710(t *testing.T) {
+	v := map[string]toml.LocalTime{}
+	err := toml.Unmarshal([]byte(`0=00:00:00.0000000000`), &v)
+	require.NoError(t, err)
+	require.Equal(t, map[string]toml.LocalTime{"0": {Precision: 9}}, v)
+	v1 := map[string]toml.LocalTime{}
+	err = toml.Unmarshal([]byte(`0=00:00:00.0000000001`), &v1)
+	require.NoError(t, err)
+	require.Equal(t, map[string]toml.LocalTime{"0": {Precision: 9}}, v1)
+	v2 := map[string]toml.LocalTime{}
+	err = toml.Unmarshal([]byte(`0=00:00:00.1111111119`), &v2)
+	require.NoError(t, err)
+	require.Equal(t, map[string]toml.LocalTime{"0": {Nanosecond: 111111111, Precision: 9}}, v2)
+}
+
+func TestIssue715(t *testing.T) {
+	var v interface{}
+	err := toml.Unmarshal([]byte("0=+"), &v)
+	require.Error(t, err)
+
+	err = toml.Unmarshal([]byte("0=-"), &v)
+	require.Error(t, err)
+
+	err = toml.Unmarshal([]byte("0=+A"), &v)
+	require.Error(t, err)
+}
+
+func TestIssue714(t *testing.T) {
+	var v interface{}
+	err := toml.Unmarshal([]byte("0."), &v)
+	require.Error(t, err)
+
+	err = toml.Unmarshal([]byte("0={0=0,"), &v)
+	require.Error(t, err)
+}
+
 func TestUnmarshalDecodeErrors(t *testing.T) {
 	examples := []struct {
 		desc string
@@ -2205,18 +2361,10 @@ func TestUnmarshalDecodeErrors(t *testing.T) {
 			desc: "local time with fractional",
 			data: `a = 11:22:33.x`,
 		},
-		{
-			desc: "local time frac precision too large",
-			data: `a = 2021-05-09T11:22:33.99999999999`,
-		},
 		{
 			desc: "wrong time offset separator",
 			data: `a = 1979-05-27T00:32:00.-07:00`,
 		},
-		{
-			desc: "missing fractional with tz",
-			data: `a = 2021-05-09T11:22:33.99999999999`,
-		},
 		{
 			desc: "wrong time offset separator",
 			data: `a = 1979-05-27T00:32:00Z07:00`,
@@ -2226,9 +2374,25 @@ func TestUnmarshalDecodeErrors(t *testing.T) {
 			data: `flt8 = 224_617.445_991__228`,
 		},
 		{
-			desc: "float with double _",
+			desc: "float with double .",
 			data: `flt8 = 1..2`,
 		},
+		{
+			desc: "number with plus sign and leading underscore",
+			data: `a = +_0`,
+		},
+		{
+			desc: "number with negative sign and leading underscore",
+			data: `a = -_0`,
+		},
+		{
+			desc: "exponent with plus sign and leading underscore",
+			data: `a = 0e+_0`,
+		},
+		{
+			desc: "exponent with negative sign and leading underscore",
+			data: `a = 0e-_0`,
+		},
 		{
 			desc: "int with wrong base",
 			data: `a = 0f2`,
@@ -2336,7 +2500,7 @@ world'`,
 		{
 			desc: "invalid seconds value",
 			data: `a=1979-05-27T12:45:99`,
-			msg:  `seconds cannot be greater 59`,
+			msg:  `seconds cannot be greater 60`,
 		},
 		{
 			desc: `binary with invalid digit`,
@@ -2540,14 +2704,70 @@ world'`,
 			desc: `invalid month`,
 			data: `a=2021-0--29`,
 		},
+		{
+			desc: `zero is an invalid day`,
+			data: `a=2021-11-00`,
+		},
+		{
+			desc: `zero is an invalid month`,
+			data: `a=2021-00-11`,
+		},
+		{
+			desc: `invalid number of seconds digits with trailing digit`,
+			data: `a=0000-01-01 00:00:000000Z3`,
+		},
+		{
+			desc: `invalid zone offset hours`,
+			data: `a=0000-01-01 00:00:00+24:00`,
+		},
+		{
+			desc: `invalid zone offset minutes`,
+			data: `a=0000-01-01 00:00:00+00:60`,
+		},
+		{
+			desc: `invalid character in zone offset hours`,
+			data: `a=0000-01-01 00:00:00+0Z:00`,
+		},
+		{
+			desc: `invalid character in zone offset minutes`,
+			data: `a=0000-01-01 00:00:00+00:0Z`,
+		},
+		{
+			desc: `invalid number of seconds`,
+			data: `a=0000-01-01 00:00:00+27000`,
+		},
 		{
 			desc: `carriage return inside basic key`,
 			data: "\"\r\"=42",
 		},
+		{
+			desc: `carriage return inside literal key`,
+			data: "'\r'=42",
+		},
 		{
 			desc: `carriage return inside basic string`,
 			data: "A = \"\r\"",
 		},
+		{
+			desc: `carriage return inside basic multiline string`,
+			data: "a=\"\"\"\r\"\"\"",
+		},
+		{
+			desc: `carriage return at the trail of basic multiline string`,
+			data: "a=\"\"\"\r",
+		},
+		{
+			desc: `carriage return inside literal string`,
+			data: "A = '\r'",
+		},
+		{
+			desc: `carriage return inside multiline literal string`,
+			data: "a='''\r'''",
+		},
+		{
+			desc: `carriage return at trail of multiline literal string`,
+			data: "a='''\r",
+		},
 		{
 			desc: `carriage return in comment`,
 			data: "# this is a test\ra=1",
@@ -2578,6 +2798,34 @@ world'`,
 	}
 }
 
+func TestUnmarshalTags(t *testing.T) {
+	type doc struct {
+		Dash   string `toml:"-,"`
+		Ignore string `toml:"-"`
+		A      string `toml:"hello"`
+		B      string `toml:"comma,omitempty"`
+	}
+
+	data := `
+'-' = "dash"
+Ignore = 'me'
+hello = 'content'
+comma = 'ok'
+`
+
+	d := doc{}
+	expected := doc{
+		Dash:   "dash",
+		Ignore: "",
+		A:      "content",
+		B:      "ok",
+	}
+
+	err := toml.Unmarshal([]byte(data), &d)
+	require.NoError(t, err)
+	require.Equal(t, expected, d)
+}
+
 func TestASCIIControlCharacters(t *testing.T) {
 	invalidCharacters := []byte{0x7F}
 	for c := byte(0x0); c <= 0x08; c++ {