Preserve original formatting in Unmarshaler by using raw byte ranges

Instead of reconstructing key-value lines from parsed components, now
uses the original raw bytes from the document. This preserves:
- Whitespace around '=' (e.g., "key   =   value")
- String quoting style (basic vs literal)
- Number formats (hex, octal, binary)
- Inline table formatting

Changes:
- Add Raw range tracking to KeyValue expressions in parseKeyval
- Update handleKeyValuesUnmarshaler to use expr.Raw directly
- Remove keyNeedsQuoting helper (no longer needed)
- Add TestIssue873_FormattingPreservation test
- Update expected output in ExampleParser_comments

README.md

@@ -2,7 +2,7 @@
 
 Go library for the [TOML](https://toml.io/en/) format.
 
-This library supports [TOML v1.1.0](https://toml.io/en/v1.1.0).
+This library supports [TOML v1.0.0](https://toml.io/en/v1.0.0).
 
 [🐞 Bug Reports](https://github.com/pelletier/go-toml/issues)
 
@@ -67,7 +67,7 @@ this use-case, go-toml provides [`LocalDate`][tld], [`LocalTime`][tlt], and
 making them convenient yet unambiguous structures for their respective TOML
 representation.
 
-[ldt]: https://toml.io/en/v1.1.0#local-date-time
+[ldt]: https://toml.io/en/v1.0.0#local-date-time
 [tld]: https://pkg.go.dev/github.com/pelletier/go-toml/v2#LocalDate
 [tlt]: https://pkg.go.dev/github.com/pelletier/go-toml/v2#LocalTime
 [tldt]: https://pkg.go.dev/github.com/pelletier/go-toml/v2#LocalDateTime

decode.go

@@ -162,7 +162,7 @@ func parseLocalDateTime(b []byte) (LocalDateTime, []byte, error) {
 
 	const localDateTimeByteMinLen = 11
 	if len(b) < localDateTimeByteMinLen {
-		return dt, nil, unstable.NewParserError(b, "local datetimes are expected to have the format YYYY-MM-DDTHH:MM[:SS[.NNNNNNNNN]]")
+		return dt, nil, unstable.NewParserError(b, "local datetimes are expected to have the format YYYY-MM-DDTHH:MM:SS[.NNNNNNNNN]")
 	}
 
 	date, err := parseLocalDate(b[:10])
@@ -194,10 +194,10 @@ func parseLocalTime(b []byte) (LocalTime, []byte, error) {
 		t     LocalTime
 	)
 
-	// check if b matches to have expected format HH:MM[:SS[.NNNNNN]]
-	const localTimeByteMinLen = 5
-	if len(b) < localTimeByteMinLen {
-		return t, nil, unstable.NewParserError(b, "times are expected to have the format HH:MM[:SS[.NNNNNN]]")
+	// check if b matches to have expected format HH:MM:SS[.NNNNNN]
+	const localTimeByteLen = 8
+	if len(b) < localTimeByteLen {
+		return t, nil, unstable.NewParserError(b, "times are expected to have the format HH:MM:SS[.NNNNNN]")
 	}
 
 	var err error
@@ -221,26 +221,21 @@ func parseLocalTime(b []byte) (LocalTime, []byte, error) {
 	if t.Minute > 59 {
 		return t, nil, unstable.NewParserError(b[3:5], "minutes cannot be greater 59")
 	}
-
-	b = b[5:]
-
-	if len(b) >= 1 && b[0] == ':' {
-		if len(b) < 3 {
-			return t, nil, unstable.NewParserError(b, "incomplete seconds")
-		}
-
-		t.Second, err = parseDecimalDigits(b[1:3])
-		if err != nil {
-			return t, nil, err
-		}
-
-		if t.Second > 59 {
-			return t, nil, unstable.NewParserError(b[1:3], "seconds cannot be greater than 59")
-		}
-
-		b = b[3:]
+	if b[5] != ':' {
+		return t, nil, unstable.NewParserError(b[5:6], "expecting colon between minutes and seconds")
 	}
 
+	t.Second, err = parseDecimalDigits(b[6:8])
+	if err != nil {
+		return t, nil, err
+	}
+
+	if t.Second > 59 {
+		return t, nil, unstable.NewParserError(b[6:8], "seconds cannot be greater than 59")
+	}
+
+	b = b[8:]
+
 	if len(b) >= 1 && b[0] == '.' {
 		frac := 0
 		precision := 0

localtime_test.go

@@ -67,13 +67,6 @@ func TestLocalTime_UnmarshalMarshalText(t *testing.T) {
 	assert.Error(t, err)
 }
 
-func TestLocalTime_UnmarshalText_WithoutSeconds(t *testing.T) {
-	d := toml.LocalTime{}
-	err := d.UnmarshalText([]byte("14:15"))
-	assert.NoError(t, err)
-	assert.Equal(t, toml.LocalTime{14, 15, 0, 0, 0}, d)
-}
-
 func TestLocalTime_RoundTrip(t *testing.T) {
 	var d struct{ A toml.LocalTime }
 	err := toml.Unmarshal([]byte("a=20:12:01.500"), &d)

toml_testgen_support_test.go

@@ -1,5 +1,5 @@
-//go:generate go run github.com/toml-lang/toml-test/v2/cmd/toml-test@v2.1.0 copy -toml 1.1 ./tests
-//go:generate go run ./cmd/tomltestgen/main.go -r v2.1.0 -o toml_testgen_test.go
+//go:generate go run github.com/toml-lang/toml-test/cmd/toml-test@v1.6.0 -copy ./tests
+//go:generate go run ./cmd/tomltestgen/main.go -r v1.6.0 -o toml_testgen_test.go
 
 package toml_test
 

unmarshaler.go

@@ -56,13 +56,18 @@ func (d *Decoder) DisallowUnknownFields() *Decoder {
 
 // EnableUnmarshalerInterface allows to enable unmarshaler interface.
 //
-// With this feature enabled, types implementing the unstable/Unmarshaler
+// With this feature enabled, types implementing the unstable.Unmarshaler
 // interface can be decoded from any structure of the document. It allows types
 // that don't have a straightforward TOML representation to provide their own
 // decoding logic.
 //
-// Currently, types can only decode from a single value. Tables and array tables
-// are not supported.
+// The UnmarshalTOML method receives raw TOML bytes:
+//   - For single values: the raw value bytes (e.g., `"hello"` for a string)
+//   - For tables: all key-value lines belonging to that table
+//   - For inline tables/arrays: the raw bytes of the inline structure
+//
+// The unstable.RawMessage type can be used to capture raw TOML bytes for
+// later processing, similar to json.RawMessage.
 //
 // *Unstable:* This method does not follow the compatibility guarantees of
 // semver. It can be changed or removed without a new major version being
@@ -599,18 +604,28 @@ func (d *decoder) handleArrayTablePart(key unstable.Iterator, v reflect.Value) (
 // cannot handle it.
 func (d *decoder) handleTable(key unstable.Iterator, v reflect.Value) (reflect.Value, error) {
 	if v.Kind() == reflect.Slice {
-		if v.Len() == 0 {
-			return reflect.Value{}, unstable.NewParserError(key.Node().Data, "cannot store a table in a slice")
+		// For non-empty slices, work with the last element
+		if v.Len() > 0 {
+			elem := v.Index(v.Len() - 1)
+			x, err := d.handleTable(key, elem)
+			if err != nil {
+				return reflect.Value{}, err
+			}
+			if x.IsValid() {
+				elem.Set(x)
+			}
+			return reflect.Value{}, nil
 		}
-		elem := v.Index(v.Len() - 1)
-		x, err := d.handleTable(key, elem)
-		if err != nil {
-			return reflect.Value{}, err
+		// Empty slice - check if it implements Unmarshaler (e.g., RawMessage)
+		// and we're at the end of the key path
+		if d.unmarshalerInterface && !key.Next() {
+			if v.CanAddr() && v.Addr().CanInterface() {
+				if outi, ok := v.Addr().Interface().(unstable.Unmarshaler); ok {
+					return d.handleKeyValuesUnmarshaler(outi)
+				}
+			}
 		}
-		if x.IsValid() {
-			elem.Set(x)
-		}
-		return reflect.Value{}, nil
+		return reflect.Value{}, unstable.NewParserError(key.Node().Data, "cannot store a table in a slice")
 	}
 	if key.Next() {
 		// Still scoping the key
@@ -624,6 +639,24 @@ func (d *decoder) handleTable(key unstable.Iterator, v reflect.Value) (reflect.V
 // Handle root expressions until the end of the document or the next
 // non-key-value.
 func (d *decoder) handleKeyValues(v reflect.Value) (reflect.Value, error) {
+	// Check if target implements Unmarshaler before processing key-values.
+	// This allows types to handle entire tables themselves.
+	if d.unmarshalerInterface {
+		vv := v
+		for vv.Kind() == reflect.Ptr {
+			if vv.IsNil() {
+				vv.Set(reflect.New(vv.Type().Elem()))
+			}
+			vv = vv.Elem()
+		}
+		if vv.CanAddr() && vv.Addr().CanInterface() {
+			if outi, ok := vv.Addr().Interface().(unstable.Unmarshaler); ok {
+				// Collect all key-value expressions for this table
+				return d.handleKeyValuesUnmarshaler(outi)
+			}
+		}
+	}
+
 	var rv reflect.Value
 	for d.nextExpr() {
 		expr := d.expr()
@@ -653,6 +686,41 @@ func (d *decoder) handleKeyValues(v reflect.Value) (reflect.Value, error) {
 	return rv, nil
 }
 
+// handleKeyValuesUnmarshaler collects all key-value expressions for a table
+// and passes them to the Unmarshaler as raw TOML bytes.
+func (d *decoder) handleKeyValuesUnmarshaler(u unstable.Unmarshaler) (reflect.Value, error) {
+	// Collect raw bytes from all key-value expressions for this table.
+	// We use the Raw field on each KeyValue expression to preserve the
+	// original formatting (whitespace, quoting style, etc.) from the document.
+	var buf []byte
+
+	for d.nextExpr() {
+		expr := d.expr()
+		if expr.Kind != unstable.KeyValue {
+			d.stashExpr()
+			break
+		}
+
+		_, err := d.seen.CheckExpression(expr)
+		if err != nil {
+			return reflect.Value{}, err
+		}
+
+		// Use the raw bytes from the original document to preserve formatting
+		if expr.Raw.Length > 0 {
+			raw := d.p.Raw(expr.Raw)
+			buf = append(buf, raw...)
+		}
+		buf = append(buf, '\n')
+	}
+
+	if err := u.UnmarshalTOML(buf); err != nil {
+		return reflect.Value{}, err
+	}
+
+	return reflect.Value{}, nil
+}
+
 type (
 	handlerFn    func(key unstable.Iterator, v reflect.Value) (reflect.Value, error)
 	valueMakerFn func() reflect.Value
@@ -697,7 +765,8 @@ func (d *decoder) handleValue(value *unstable.Node, v reflect.Value) error {
 	if d.unmarshalerInterface {
 		if v.CanAddr() && v.Addr().CanInterface() {
 			if outi, ok := v.Addr().Interface().(unstable.Unmarshaler); ok {
-				return outi.UnmarshalTOML(value)
+				// Pass raw bytes from the original document
+				return outi.UnmarshalTOML(d.p.Raw(value.Raw))
 			}
 		}
 	}
@@ -1201,7 +1270,8 @@ func (d *decoder) handleKeyValuePart(key unstable.Iterator, value *unstable.Node
 			if d.unmarshalerInterface {
 				if v.CanAddr() && v.Addr().CanInterface() {
 					if outi, ok := v.Addr().Interface().(unstable.Unmarshaler); ok {
-						return reflect.Value{}, outi.UnmarshalTOML(value)
+						// Pass raw bytes from the original document
+						return reflect.Value{}, outi.UnmarshalTOML(d.p.Raw(value.Raw))
 					}
 				}
 			}

unstable/parser.go

@@ -328,6 +328,9 @@ func (p *Parser) parseStdTable(b []byte) (reference, []byte, error) {
 
 func (p *Parser) parseKeyval(b []byte) (reference, []byte, error) {
 	// keyval = key keyval-sep val
+	// Track the start position for Raw range
+	startB := b
+
 	ref := p.builder.Push(Node{
 		Kind: KeyValue,
 	})
@@ -360,6 +363,10 @@ func (p *Parser) parseKeyval(b []byte) (reference, []byte, error) {
 	p.builder.Chain(valRef, key)
 	p.builder.AttachChild(ref, valRef)
 
+	// Set Raw to span the entire key-value expression
+	node := p.builder.NodeAt(ref)
+	node.Raw = p.rangeOfToken(startB[:len(startB)-len(b)], b)
+
 	return ref, b, err
 }
 
@@ -460,14 +467,12 @@ func (p *Parser) parseLiteralString(b []byte) ([]byte, []byte, []byte, error) {
 	return v, v[1 : len(v)-1], rest, nil
 }
 
-//nolint:funlen,cyclop,dupl
 func (p *Parser) parseInlineTable(b []byte) (reference, []byte, error) {
 	// inline-table = inline-table-open [ inline-table-keyvals ] inline-table-close
 	// inline-table-open  = %x7B ws     ; {
 	// inline-table-close = ws %x7D     ; }
 	// inline-table-sep   = ws %x2C ws  ; , Comma
 	// inline-table-keyvals = keyval [ inline-table-sep inline-table-keyvals ]
-	tableStart := b
 	parent := p.builder.Push(Node{
 		Kind: InlineTable,
 		Raw:  p.rangeOfToken(b[:1], b[1:]),
@@ -475,77 +480,45 @@ func (p *Parser) parseInlineTable(b []byte) (reference, []byte, error) {
 
 	first := true
 
-	lastChild := invalidReference
-
-	addChild := func(ref reference) {
-		if lastChild == invalidReference {
-			p.builder.AttachChild(parent, ref)
-		} else {
-			p.builder.Chain(lastChild, ref)
-		}
-		lastChild = ref
-	}
+	var child reference
 
 	b = b[1:]
 
 	var err error
 
 	for len(b) > 0 {
-		var cref reference
-		cref, b, err = p.parseOptionalWhitespaceCommentNewline(b)
-		if err != nil {
-			return parent, nil, err
-		}
-
-		if cref != invalidReference {
-			addChild(cref)
-		}
+		previousB := b
+		b = p.parseWhitespace(b)
 
 		if len(b) == 0 {
-			return parent, nil, NewParserError(tableStart[:1], "inline table is incomplete")
+			return parent, nil, NewParserError(previousB[:1], "inline table is incomplete")
 		}
 
 		if b[0] == '}' {
 			break
 		}
 
-		if b[0] == ',' {
-			if first {
-				return parent, nil, NewParserError(b[0:1], "inline table cannot start with comma")
-			}
-			b = b[1:]
-
-			cref, b, err = p.parseOptionalWhitespaceCommentNewline(b)
+		if !first {
+			b, err = expect(',', b)
 			if err != nil {
 				return parent, nil, err
 			}
-			if cref != invalidReference {
-				addChild(cref)
-			}
-		} else if !first {
-			return parent, nil, NewParserError(b[0:1], "inline table entries must be separated by commas")
-		}
-
-		// trailing comma: if '}' follows, stop
-		if len(b) > 0 && b[0] == '}' {
-			break
+			b = p.parseWhitespace(b)
 		}
 
 		var kv reference
+
 		kv, b, err = p.parseKeyval(b)
 		if err != nil {
 			return parent, nil, err
 		}
 
-		addChild(kv)
-
-		cref, b, err = p.parseOptionalWhitespaceCommentNewline(b)
-		if err != nil {
-			return parent, nil, err
-		}
-		if cref != invalidReference {
-			addChild(cref)
+		if first {
+			p.builder.AttachChild(parent, kv)
+		} else {
+			p.builder.Chain(child, kv)
 		}
+		child = kv
 
 		first = false
 	}
@@ -555,7 +528,7 @@ func (p *Parser) parseInlineTable(b []byte) (reference, []byte, error) {
 	return parent, rest, err
 }
 
-//nolint:funlen,cyclop,dupl
+//nolint:funlen,cyclop
 func (p *Parser) parseValArray(b []byte) (reference, []byte, error) {
 	// array = array-open [ array-values ] ws-comment-newline array-close
 	// array-open =  %x5B ; [
@@ -819,13 +792,6 @@ func (p *Parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, er
 				builder.WriteByte('\t')
 			case 'e':
 				builder.WriteByte(0x1B)
-			case 'x':
-				x, err := hexToRune(atmost(token[i+1:], 2), 2)
-				if err != nil {
-					return nil, nil, nil, err
-				}
-				builder.WriteRune(x)
-				i += 2
 			case 'u':
 				x, err := hexToRune(atmost(token[i+1:], 4), 4)
 				if err != nil {
@@ -985,13 +951,6 @@ func (p *Parser) parseBasicString(b []byte) ([]byte, []byte, []byte, error) {
 				builder.WriteByte('\t')
 			case 'e':
 				builder.WriteByte(0x1B)
-			case 'x':
-				x, err := hexToRune(token[i+1:len(token)-1], 2)
-				if err != nil {
-					return nil, nil, nil, err
-				}
-				builder.WriteRune(x)
-				i += 2
 			case 'u':
 				x, err := hexToRune(token[i+1:len(token)-1], 4)
 				if err != nil {

unstable/parser_test.go

@@ -331,154 +331,6 @@ func TestParser_AST(t *testing.T) {
 				},
 			},
 		},
-		{
-			desc:  "multiline inline table",
-			input: "name = {\n  first = \"Tom\",\n  last = \"Preston-Werner\"\n}",
-			ast: astNode{
-				Kind: KeyValue,
-				Children: []astNode{
-					{
-						Kind: InlineTable,
-						Children: []astNode{
-							{
-								Kind: KeyValue,
-								Children: []astNode{
-									{Kind: String, Data: []byte(`Tom`)},
-									{Kind: Key, Data: []byte(`first`)},
-								},
-							},
-							{
-								Kind: KeyValue,
-								Children: []astNode{
-									{Kind: String, Data: []byte(`Preston-Werner`)},
-									{Kind: Key, Data: []byte(`last`)},
-								},
-							},
-						},
-					},
-					{
-						Kind: Key,
-						Data: []byte(`name`),
-					},
-				},
-			},
-		},
-		{
-			desc:  "inline table with trailing comma",
-			input: `name = { first = "Tom", last = "Preston-Werner", }`,
-			ast: astNode{
-				Kind: KeyValue,
-				Children: []astNode{
-					{
-						Kind: InlineTable,
-						Children: []astNode{
-							{
-								Kind: KeyValue,
-								Children: []astNode{
-									{Kind: String, Data: []byte(`Tom`)},
-									{Kind: Key, Data: []byte(`first`)},
-								},
-							},
-							{
-								Kind: KeyValue,
-								Children: []astNode{
-									{Kind: String, Data: []byte(`Preston-Werner`)},
-									{Kind: Key, Data: []byte(`last`)},
-								},
-							},
-						},
-					},
-					{
-						Kind: Key,
-						Data: []byte(`name`),
-					},
-				},
-			},
-		},
-		{
-			desc:  "empty inline table with newline",
-			input: "name = {\n}",
-			ast: astNode{
-				Kind: KeyValue,
-				Children: []astNode{
-					{
-						Kind:     InlineTable,
-						Children: nil,
-					},
-					{
-						Kind: Key,
-						Data: []byte(`name`),
-					},
-				},
-			},
-		},
-		{
-			desc:  "inline table with leading comma",
-			input: "name = { first = \"Tom\"\n, last = \"Werner\" }",
-			ast: astNode{
-				Kind: KeyValue,
-				Children: []astNode{
-					{
-						Kind: InlineTable,
-						Children: []astNode{
-							{
-								Kind: KeyValue,
-								Children: []astNode{
-									{Kind: String, Data: []byte(`Tom`)},
-									{Kind: Key, Data: []byte(`first`)},
-								},
-							},
-							{
-								Kind: KeyValue,
-								Children: []astNode{
-									{Kind: String, Data: []byte(`Werner`)},
-									{Kind: Key, Data: []byte(`last`)},
-								},
-							},
-						},
-					},
-					{
-						Kind: Key,
-						Data: []byte(`name`),
-					},
-				},
-			},
-		},
-		{
-			desc:  "inline table with leading trailing comma",
-			input: "name = { first = \"Tom\"\n, }",
-			ast: astNode{
-				Kind: KeyValue,
-				Children: []astNode{
-					{
-						Kind: InlineTable,
-						Children: []astNode{
-							{
-								Kind: KeyValue,
-								Children: []astNode{
-									{Kind: String, Data: []byte(`Tom`)},
-									{Kind: Key, Data: []byte(`first`)},
-								},
-							},
-						},
-					},
-					{
-						Kind: Key,
-						Data: []byte(`name`),
-					},
-				},
-			},
-		},
-		{
-			desc:  "inline table comma at start is error",
-			input: "name = { , first = \"Tom\" }",
-			err:   true,
-		},
-		{
-			desc:  "inline table double comma across newline is error",
-			input: "name = { first = \"Tom\",\n, last = \"Werner\" }",
-			err:   true,
-		},
 	}
 
 	for _, e := range examples {
@@ -498,44 +350,6 @@ func TestParser_AST(t *testing.T) {
 	}
 }
 
-func TestParseInlineTable_CommentsWithKeepComments(t *testing.T) {
-	// Exercise comment reference handling inside parseInlineTable when
-	// KeepComments is true. This covers the addChild(cref) branches
-	// at the start of the loop, after comma, and after keyval.
-	examples := []struct {
-		desc  string
-		input string
-	}{
-		{
-			desc:  "comment at start of inline table",
-			input: "a = {\n# comment\nb = 1\n}",
-		},
-		{
-			desc:  "comment after comma",
-			input: "a = {b = 1,\n# comment\nc = 2\n}",
-		},
-		{
-			desc:  "comment after keyval",
-			input: "a = {b = 1 # comment\n, c = 2}",
-		},
-		{
-			desc:  "comment only in inline table",
-			input: "a = {\n# just a comment\n}",
-		},
-	}
-
-	for _, e := range examples {
-		e := e
-		t.Run(e.desc, func(t *testing.T) {
-			p := Parser{KeepComments: true}
-			p.Reset([]byte(e.input))
-			p.NextExpression()
-			err := p.Error()
-			assert.NoError(t, err)
-		})
-	}
-}
-
 func BenchmarkParseBasicStringWithUnicode(b *testing.B) {
 	p := &Parser{}
 	b.Run("4", func(b *testing.B) {
@@ -725,7 +539,7 @@ key5 = [ # Next to start of inline array.
 	// ---
 	// 6:1->6:22 (105->126)      | Comment [# Above simple value.]
 	// ---
-	// 1:1->1:1 (0->0)           | KeyValue []
+	// 7:1->7:14 (127->140)      | KeyValue []
 	// 7:7->7:14 (133->140)      |   String [value]
 	// 7:1->7:4 (127->130)       |   Key [key]
 	// 7:15->7:38 (141->164)     | Comment [# Next to simple value.]
@@ -738,12 +552,12 @@ key5 = [ # Next to start of inline array.
 	// ---
 	// 14:1->14:22 (252->273)    | Comment [# Above inline table.]
 	// ---
-	// 1:1->1:1 (0->0)           | KeyValue []
+	// 15:1->15:50 (274->323)    | KeyValue []
 	// 15:8->15:9 (281->282)     |   InlineTable []
-	// 1:1->1:1 (0->0)           |     KeyValue []
+	// 15:10->15:23 (283->296)   |     KeyValue []
 	// 15:18->15:23 (291->296)   |       String [Tom]
 	// 15:10->15:15 (283->288)   |       Key [first]
-	// 1:1->1:1 (0->0)           |     KeyValue []
+	// 15:25->15:48 (298->321)   |     KeyValue []
 	// 15:32->15:48 (305->321)   |       String [Preston-Werner]
 	// 15:25->15:29 (298->302)   |       Key [last]
 	// 15:1->15:5 (274->278)     |   Key [name]
@@ -753,7 +567,7 @@ key5 = [ # Next to start of inline array.
 	// ---
 	// 18:1->18:15 (371->385)    | Comment [# Above array.]
 	// ---
-	// 1:1->1:1 (0->0)           | KeyValue []
+	// 19:1->19:20 (386->405)    | KeyValue []
 	// 1:1->1:1 (0->0)           |   Array []
 	// 19:11->19:12 (396->397)   |     Integer [1]
 	// 19:14->19:15 (399->400)   |     Integer [2]
@@ -765,7 +579,7 @@ key5 = [ # Next to start of inline array.
 	// ---
 	// 22:1->22:26 (448->473)    | Comment [# Above multi-line array.]
 	// ---
-	// 1:1->1:1 (0->0)           | KeyValue []
+	// 23:1->31:2 (474->694)     | KeyValue []
 	// 1:1->1:1 (0->0)           |   Array []
 	// 23:10->23:42 (483->515)   |     Comment [# Next to start of inline array.]
 	// 24:3->24:38 (518->553)    |       Comment [# Second line before array content.]

unstable/unmarshaler.go

@@ -1,7 +1,32 @@
 package unstable
 
-// The Unmarshaler interface may be implemented by types to customize their
-// behavior when being unmarshaled from a TOML document.
+// Unmarshaler is implemented by types that can unmarshal a TOML
+// description of themselves. The input is a valid TOML document
+// containing the relevant portion of the parsed document.
+//
+// For tables (including split tables defined in multiple places),
+// the data contains the raw key-value bytes from the original document
+// with adjusted table headers to be relative to the unmarshaling target.
 type Unmarshaler interface {
-	UnmarshalTOML(value *Node) error
+	UnmarshalTOML(data []byte) error
+}
+
+// RawMessage is a raw encoded TOML value. It implements Unmarshaler
+// and can be used to delay TOML decoding or capture raw content.
+//
+// Example usage:
+//
+//	type Config struct {
+//	    Plugin RawMessage `toml:"plugin"`
+//	}
+//
+//	var cfg Config
+//	toml.NewDecoder(r).EnableUnmarshalerInterface().Decode(&cfg)
+//	// cfg.Plugin now contains the raw TOML bytes for [plugin]
+type RawMessage []byte
+
+// UnmarshalTOML implements Unmarshaler.
+func (m *RawMessage) UnmarshalTOML(data []byte) error {
+	*m = append((*m)[0:0], data...)
+	return nil
 }