Remove Parser.Range and subsliceOffset

Range() existed to recover byte offsets from Highlight subslices.
Now that ParserError carries an explicit Offset field, Range() is
unnecessary. Remove it along with the private subsliceOffset helper
in ast.go.

Tests now use perr.Offset directly and construct Range literals
for Shape() calls.

Co-authored-by: Thomas Pelletier <thomas@pelletier.dev>

.github/workflows/cifuzz.yml

@@ -19,7 +19,7 @@ jobs:
         dry-run: false
         language: go
     - name: Upload Crash
-      uses: actions/upload-artifact@v6
+      uses: actions/upload-artifact@v7
       if: failure() && steps.build.outcome == 'success'
       with:
         name: artifacts

.github/workflows/coverage.yml

@@ -15,6 +15,6 @@ jobs:
       - name: Setup go
         uses: actions/setup-go@v6
         with:
-          go-version: "1.25"
+          go-version: "1.26"
       - name: Run tests with coverage
         run: ./ci.sh coverage -d "${GITHUB_BASE_REF-HEAD}"

.github/workflows/go-versions-test.yml

@@ -20,7 +20,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Run Go versions compatibility test
         run: |
@@ -28,7 +28,7 @@ jobs:
           ./test-go-versions.sh --output ./test-results $VERSIONS
 
       - name: Upload test results
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: go-versions-test-results
           path: |

.github/workflows/lint.yml

@@ -15,7 +15,7 @@ jobs:
       - name: Setup go
         uses: actions/setup-go@v6
         with:
-          go-version: "1.24"
+          go-version: "1.26"
       - name: Run golangci-lint
         uses: golangci/golangci-lint-action@v9
         with:

.github/workflows/release.yml

@@ -22,15 +22,15 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v6
         with:
-          go-version: "1.25"
+          go-version: "1.26"
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
       - name: Run GoReleaser
-        uses: goreleaser/goreleaser-action@v6
+        uses: goreleaser/goreleaser-action@v7
         with:
           distribution: goreleaser
           version: '~> v2'

.github/workflows/workflow.yml

@@ -10,9 +10,10 @@ on:
 jobs:
   build:
     strategy:
+      fail-fast: false
       matrix:
         os: [ 'ubuntu-latest', 'windows-latest', 'macos-latest', 'macos-14' ]
-        go: [ '1.24', '1.25' ]
+        go: [ '1.25', '1.26' ]
     runs-on: ${{ matrix.os }}
     name: ${{ matrix.go }}/${{ matrix.os }}
     steps:

.goreleaser.yaml

@@ -22,7 +22,6 @@ builds:
       - linux_riscv64
       - windows_amd64
       - windows_arm64
-      - windows_arm
       - darwin_amd64
       - darwin_arm64
   - id: tomljson
@@ -42,7 +41,6 @@ builds:
       - linux_riscv64
       - windows_amd64
       - windows_arm64
-      - windows_arm
       - darwin_amd64
       - darwin_arm64
   - id: jsontoml
@@ -62,7 +60,6 @@ builds:
       - linux_arm
       - windows_amd64
       - windows_arm64
-      - windows_arm
       - darwin_amd64
       - darwin_arm64
 universal_binaries:

README.md

@@ -235,17 +235,17 @@ the AST level. See https://pkg.go.dev/github.com/pelletier/go-toml/v2/unstable.
 Execution time speedup compared to other Go TOML libraries:
 
 <table>
-	<thead>
-		<tr><th>Benchmark</th><th>go-toml v1</th><th>BurntSushi/toml</th></tr>
-	</thead>
-	<tbody>
-		<tr><td>Marshal/HugoFrontMatter-2</td><td>1.9x</td><td>2.2x</td></tr>
-		<tr><td>Marshal/ReferenceFile/map-2</td><td>1.7x</td><td>2.1x</td></tr>
-		<tr><td>Marshal/ReferenceFile/struct-2</td><td>2.2x</td><td>3.0x</td></tr>
-		<tr><td>Unmarshal/HugoFrontMatter-2</td><td>2.9x</td><td>2.7x</td></tr>
-		<tr><td>Unmarshal/ReferenceFile/map-2</td><td>2.6x</td><td>2.7x</td></tr>
-		<tr><td>Unmarshal/ReferenceFile/struct-2</td><td>4.6x</td><td>5.1x</td></tr>
-	 </tbody>
+    <thead>
+        <tr><th>Benchmark</th><th>go-toml v1</th><th>BurntSushi/toml</th></tr>
+    </thead>
+    <tbody>
+        <tr><td>Marshal/HugoFrontMatter-2</td><td>2.1x</td><td>2.0x</td></tr>
+        <tr><td>Marshal/ReferenceFile/map-2</td><td>2.0x</td><td>2.0x</td></tr>
+        <tr><td>Marshal/ReferenceFile/struct-2</td><td>2.3x</td><td>2.5x</td></tr>
+        <tr><td>Unmarshal/HugoFrontMatter-2</td><td>3.3x</td><td>2.8x</td></tr>
+        <tr><td>Unmarshal/ReferenceFile/map-2</td><td>2.9x</td><td>3.0x</td></tr>
+        <tr><td>Unmarshal/ReferenceFile/struct-2</td><td>4.8x</td><td>5.0x</td></tr>
+     </tbody>
 </table>
 <details><summary>See more</summary>
 <p>The table above has the results of the most common use-cases. The table below
@@ -253,22 +253,22 @@ contains the results of all benchmarks, including unrealistic ones. It is
 provided for completeness.</p>
 
 <table>
-	<thead>
-		<tr><th>Benchmark</th><th>go-toml v1</th><th>BurntSushi/toml</th></tr>
-	</thead>
-	<tbody>
-		<tr><td>Marshal/SimpleDocument/map-2</td><td>1.8x</td><td>2.7x</td></tr>
-		<tr><td>Marshal/SimpleDocument/struct-2</td><td>2.7x</td><td>3.8x</td></tr>
-		<tr><td>Unmarshal/SimpleDocument/map-2</td><td>3.8x</td><td>3.0x</td></tr>
-		<tr><td>Unmarshal/SimpleDocument/struct-2</td><td>5.6x</td><td>4.1x</td></tr>
-		<tr><td>UnmarshalDataset/example-2</td><td>3.0x</td><td>3.2x</td></tr>
-		<tr><td>UnmarshalDataset/code-2</td><td>2.3x</td><td>2.9x</td></tr>
-		<tr><td>UnmarshalDataset/twitter-2</td><td>2.6x</td><td>2.7x</td></tr>
-		<tr><td>UnmarshalDataset/citm_catalog-2</td><td>2.2x</td><td>2.3x</td></tr>
-		<tr><td>UnmarshalDataset/canada-2</td><td>1.8x</td><td>1.5x</td></tr>
-		<tr><td>UnmarshalDataset/config-2</td><td>4.1x</td><td>2.9x</td></tr>
-		<tr><td>geomean</td><td>2.7x</td><td>2.8x</td></tr>
-	 </tbody>
+    <thead>
+        <tr><th>Benchmark</th><th>go-toml v1</th><th>BurntSushi/toml</th></tr>
+    </thead>
+    <tbody>
+        <tr><td>Marshal/SimpleDocument/map-2</td><td>2.0x</td><td>2.9x</td></tr>
+        <tr><td>Marshal/SimpleDocument/struct-2</td><td>2.5x</td><td>3.6x</td></tr>
+        <tr><td>Unmarshal/SimpleDocument/map-2</td><td>4.2x</td><td>3.4x</td></tr>
+        <tr><td>Unmarshal/SimpleDocument/struct-2</td><td>5.9x</td><td>4.4x</td></tr>
+        <tr><td>UnmarshalDataset/example-2</td><td>3.2x</td><td>2.9x</td></tr>
+        <tr><td>UnmarshalDataset/code-2</td><td>2.4x</td><td>2.8x</td></tr>
+        <tr><td>UnmarshalDataset/twitter-2</td><td>2.7x</td><td>2.5x</td></tr>
+        <tr><td>UnmarshalDataset/citm_catalog-2</td><td>2.3x</td><td>2.3x</td></tr>
+        <tr><td>UnmarshalDataset/canada-2</td><td>1.9x</td><td>1.5x</td></tr>
+        <tr><td>UnmarshalDataset/config-2</td><td>5.4x</td><td>3.0x</td></tr>
+        <tr><td>geomean</td><td>2.9x</td><td>2.8x</td></tr>
+     </tbody>
 </table>
 <p>This table can be generated with <code>./ci.sh benchmark -a -html</code>.</p>
 </details>

ci.sh

@@ -147,7 +147,7 @@ bench() {
     pushd "$dir"
 
     if [ "${replace}" != "" ]; then
-        find ./benchmark/ -iname '*.go' -exec sed -i -E "s|github.com/pelletier/go-toml/v2|${replace}|g" {} \;
+        find ./benchmark/ -iname '*.go' -exec sed -i -E "s|github.com/pelletier/go-toml/v2\"|${replace}\"|g" {} \;
         go get "${replace}"
     fi
 
@@ -195,6 +195,11 @@ for line in reversed(lines[2:]):
         "%.1fx" % (float(line[3])/v2),  # v1
         "%.1fx" % (float(line[7])/v2),  # bs
     ])
+
+if not results:
+    print("No benchmark results to display.", file=sys.stderr)
+    sys.exit(1)
+
 # move geomean to the end
 results.append(results[0])
 del results[0]

decode.go

@@ -9,64 +9,60 @@ import (
 	"github.com/pelletier/go-toml/v2/unstable"
 )
 
-func parseInteger(b []byte) (int64, error) {
+func parseInteger(b []byte, base int) (int64, error) {
 	if len(b) > 2 && b[0] == '0' {
 		switch b[1] {
 		case 'x':
-			return parseIntHex(b)
+			return parseIntHex(b, base)
 		case 'b':
-			return parseIntBin(b)
+			return parseIntBin(b, base)
 		case 'o':
-			return parseIntOct(b)
+			return parseIntOct(b, base)
 		default:
 			panic(fmt.Errorf("invalid base '%c', should have been checked by scanIntOrFloat", b[1]))
 		}
 	}
 
-	return parseIntDec(b)
+	return parseIntDec(b, base)
 }
 
-func parseLocalDate(b []byte) (LocalDate, error) {
-	// full-date      = date-fullyear "-" date-month "-" date-mday
-	// date-fullyear  = 4DIGIT
-	// date-month     = 2DIGIT  ; 01-12
-	// date-mday      = 2DIGIT  ; 01-28, 01-29, 01-30, 01-31 based on month/year
+func parseLocalDate(b []byte, base int) (LocalDate, error) {
 	var date LocalDate
 
 	if len(b) != 10 || b[4] != '-' || b[7] != '-' {
-		return date, unstable.NewParserError(b, "dates are expected to have the format YYYY-MM-DD")
+		return date, unstable.NewParserError(b, base, "dates are expected to have the format YYYY-MM-DD")
 	}
 
 	var err error
 
-	date.Year, err = parseDecimalDigits(b[0:4])
+	date.Year, err = parseDecimalDigits(b[0:4], base)
 	if err != nil {
 		return LocalDate{}, err
 	}
 
-	date.Month, err = parseDecimalDigits(b[5:7])
+	date.Month, err = parseDecimalDigits(b[5:7], base+5)
 	if err != nil {
 		return LocalDate{}, err
 	}
 
-	date.Day, err = parseDecimalDigits(b[8:10])
+	date.Day, err = parseDecimalDigits(b[8:10], base+8)
 	if err != nil {
 		return LocalDate{}, err
 	}
 
 	if !isValidDate(date.Year, date.Month, date.Day) {
-		return LocalDate{}, unstable.NewParserError(b, "impossible date")
+		return LocalDate{}, unstable.NewParserError(b, base, "impossible date")
 	}
 
 	return date, nil
 }
 
-func parseDecimalDigits(b []byte) (int, error) {
+func parseDecimalDigits(b []byte, base int) (int, error) {
 	v := 0
 
 	for i, c := range b {
 		if c < '0' || c > '9' {
-			return 0, unstable.NewParserError(b[i:i+1], "expected digit (0-9)")
+			return 0, unstable.NewParserError(b[i:i+1], base+i, "expected digit (0-9)")
 		}
 		v *= 10
 		v += int(c - '0')
@@ -75,21 +71,18 @@ func parseDecimalDigits(b []byte) (int, error) {
 	return v, nil
 }
 
-func parseDateTime(b []byte) (time.Time, error) {
-	// offset-date-time = full-date time-delim full-time
-	// full-time      = partial-time time-offset
-	// time-offset    = "Z" / time-numoffset
-	// time-numoffset = ( "+" / "-" ) time-hour ":" time-minute
-
-	dt, b, err := parseLocalDateTime(b)
+func parseDateTime(b []byte, base int) (time.Time, error) {
+	origLen := len(b)
+	dt, b, err := parseLocalDateTime(b, base)
 	if err != nil {
 		return time.Time{}, err
 	}
 
+	tzBase := base + origLen - len(b)
+
 	var zone *time.Location
 
 	if len(b) == 0 {
-		// parser should have checked that when assigning the date time node
 		panic("date time should have a timezone")
 	}
 
@@ -99,7 +92,7 @@ func parseDateTime(b []byte) (time.Time, error) {
 	} else {
 		const dateTimeByteLen = 6
 		if len(b) != dateTimeByteLen {
-			return time.Time{}, unstable.NewParserError(b, "invalid date-time timezone")
+			return time.Time{}, unstable.NewParserError(b, tzBase, "invalid date-time timezone")
 		}
 		var direction int
 		switch b[0] {
@@ -108,27 +101,27 @@ func parseDateTime(b []byte) (time.Time, error) {
 		case '+':
 			direction = +1
 		default:
-			return time.Time{}, unstable.NewParserError(b[:1], "invalid timezone offset character")
+			return time.Time{}, unstable.NewParserError(b[:1], tzBase, "invalid timezone offset character")
 		}
 
 		if b[3] != ':' {
-			return time.Time{}, unstable.NewParserError(b[3:4], "expected a : separator")
+			return time.Time{}, unstable.NewParserError(b[3:4], tzBase+3, "expected a : separator")
 		}
 
-		hours, err := parseDecimalDigits(b[1:3])
+		hours, err := parseDecimalDigits(b[1:3], tzBase+1)
 		if err != nil {
 			return time.Time{}, err
 		}
 		if hours > 23 {
-			return time.Time{}, unstable.NewParserError(b[:1], "invalid timezone offset hours")
+			return time.Time{}, unstable.NewParserError(b[:1], tzBase, "invalid timezone offset hours")
 		}
 
-		minutes, err := parseDecimalDigits(b[4:6])
+		minutes, err := parseDecimalDigits(b[4:6], tzBase+4)
 		if err != nil {
 			return time.Time{}, err
 		}
 		if minutes > 59 {
-			return time.Time{}, unstable.NewParserError(b[:1], "invalid timezone offset minutes")
+			return time.Time{}, unstable.NewParserError(b[:1], tzBase, "invalid timezone offset minutes")
 		}
 
 		seconds := direction * (hours*3600 + minutes*60)
@@ -141,7 +134,7 @@ func parseDateTime(b []byte) (time.Time, error) {
 	}
 
 	if len(b) > 0 {
-		return time.Time{}, unstable.NewParserError(b, "extra bytes at the end of the timezone")
+		return time.Time{}, unstable.NewParserError(b, tzBase, "extra bytes at the end of the timezone")
 	}
 
 	t := time.Date(
@@ -157,15 +150,15 @@ func parseDateTime(b []byte) (time.Time, error) {
 	return t, nil
 }
 
-func parseLocalDateTime(b []byte) (LocalDateTime, []byte, error) {
+func parseLocalDateTime(b []byte, base int) (LocalDateTime, []byte, error) {
 	var dt LocalDateTime
 
 	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, base, "local datetimes are expected to have the format YYYY-MM-DDTHH:MM:SS[.NNNNNNNNN]")
 	}
 
-	date, err := parseLocalDate(b[:10])
+	date, err := parseLocalDate(b[:10], base)
 	if err != nil {
 		return dt, nil, err
 	}
@@ -173,10 +166,10 @@ func parseLocalDateTime(b []byte) (LocalDateTime, []byte, error) {
 
 	sep := b[10]
 	if sep != 'T' && sep != ' ' && sep != 't' {
-		return dt, nil, unstable.NewParserError(b[10:11], "datetime separator is expected to be T or a space")
+		return dt, nil, unstable.NewParserError(b[10:11], base+10, "datetime separator is expected to be T or a space")
 	}
 
-	t, rest, err := parseLocalTime(b[11:])
+	t, rest, err := parseLocalTime(b[11:], base+11)
 	if err != nil {
 		return dt, nil, err
 	}
@@ -188,53 +181,53 @@ func parseLocalDateTime(b []byte) (LocalDateTime, []byte, error) {
 // parseLocalTime is a bit different because it also returns the remaining
 // []byte that is didn't need. This is to allow parseDateTime to parse those
 // remaining bytes as a timezone.
-func parseLocalTime(b []byte) (LocalTime, []byte, error) {
+func parseLocalTime(b []byte, base int) (LocalTime, []byte, error) {
 	var (
 		nspow = [10]int{0, 1e8, 1e7, 1e6, 1e5, 1e4, 1e3, 1e2, 1e1, 1e0}
 		t     LocalTime
 	)
 
-	// 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]")
+		return t, nil, unstable.NewParserError(b, base, "times are expected to have the format HH:MM:SS[.NNNNNN]")
 	}
 
 	var err error
 
-	t.Hour, err = parseDecimalDigits(b[0:2])
+	t.Hour, err = parseDecimalDigits(b[0:2], base)
 	if err != nil {
 		return t, nil, err
 	}
 
 	if t.Hour > 23 {
-		return t, nil, unstable.NewParserError(b[0:2], "hour cannot be greater 23")
+		return t, nil, unstable.NewParserError(b[0:2], base, "hour cannot be greater 23")
 	}
 	if b[2] != ':' {
-		return t, nil, unstable.NewParserError(b[2:3], "expecting colon between hours and minutes")
+		return t, nil, unstable.NewParserError(b[2:3], base+2, "expecting colon between hours and minutes")
 	}
 
-	t.Minute, err = parseDecimalDigits(b[3:5])
+	t.Minute, err = parseDecimalDigits(b[3:5], base+3)
 	if err != nil {
 		return t, nil, err
 	}
 	if t.Minute > 59 {
-		return t, nil, unstable.NewParserError(b[3:5], "minutes cannot be greater 59")
+		return t, nil, unstable.NewParserError(b[3:5], base+3, "minutes cannot be greater 59")
 	}
 	if b[5] != ':' {
-		return t, nil, unstable.NewParserError(b[5:6], "expecting colon between minutes and seconds")
+		return t, nil, unstable.NewParserError(b[5:6], base+5, "expecting colon between minutes and seconds")
 	}
 
-	t.Second, err = parseDecimalDigits(b[6:8])
+	t.Second, err = parseDecimalDigits(b[6:8], base+6)
 	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")
+		return t, nil, unstable.NewParserError(b[6:8], base+6, "seconds cannot be greater than 59")
 	}
 
 	b = b[8:]
+	base += 8
 
 	if len(b) >= 1 && b[0] == '.' {
 		frac := 0
@@ -244,7 +237,7 @@ func parseLocalTime(b []byte) (LocalTime, []byte, error) {
 		for i, c := range b[1:] {
 			if !isDigit(c) {
 				if i == 0 {
-					return t, nil, unstable.NewParserError(b[0:1], "need at least one digit after fraction point")
+					return t, nil, unstable.NewParserError(b[0:1], base, "need at least one digit after fraction point")
 				}
 				break
 			}
@@ -252,13 +245,6 @@ func parseLocalTime(b []byte) (LocalTime, []byte, error) {
 
 			const maxFracPrecision = 9
 			if i >= maxFracPrecision {
-				// 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
 			}
 
@@ -268,7 +254,7 @@ func parseLocalTime(b []byte) (LocalTime, []byte, error) {
 		}
 
 		if precision == 0 {
-			return t, nil, unstable.NewParserError(b[:1], "nanoseconds need at least one digit")
+			return t, nil, unstable.NewParserError(b[:1], base, "nanoseconds need at least one digit")
 		}
 
 		t.Nanosecond = frac * nspow[precision]
@@ -279,35 +265,35 @@ func parseLocalTime(b []byte) (LocalTime, []byte, error) {
 	return t, b, nil
 }
 
-func parseFloat(b []byte) (float64, error) {
+func parseFloat(b []byte, base int) (float64, error) {
 	if len(b) == 4 && (b[0] == '+' || b[0] == '-') && b[1] == 'n' && b[2] == 'a' && b[3] == 'n' {
 		return math.NaN(), nil
 	}
 
-	cleaned, err := checkAndRemoveUnderscoresFloats(b)
+	cleaned, err := checkAndRemoveUnderscoresFloats(b, base)
 	if err != nil {
 		return 0, err
 	}
 
 	if cleaned[0] == '.' {
-		return 0, unstable.NewParserError(b, "float cannot start with a dot")
+		return 0, unstable.NewParserError(b, base, "float cannot start with a dot")
 	}
 
 	if cleaned[len(cleaned)-1] == '.' {
-		return 0, unstable.NewParserError(b, "float cannot end with a dot")
+		return 0, unstable.NewParserError(b, base, "float cannot end with a dot")
 	}
 
 	dotAlreadySeen := false
 	for i, c := range cleaned {
 		if c == '.' {
 			if dotAlreadySeen {
-				return 0, unstable.NewParserError(b[i:i+1], "float can have at most one decimal point")
+				return 0, unstable.NewParserError(b[i:i+1], base+i, "float can have at most one decimal point")
 			}
 			if !isDigit(cleaned[i-1]) {
-				return 0, unstable.NewParserError(b[i-1:i+1], "float decimal point must be preceded by a digit")
+				return 0, unstable.NewParserError(b[i-1:i+1], base+i-1, "float decimal point must be preceded by a digit")
 			}
 			if !isDigit(cleaned[i+1]) {
-				return 0, unstable.NewParserError(b[i:i+2], "float decimal point must be followed by a digit")
+				return 0, unstable.NewParserError(b[i:i+2], base+i, "float decimal point must be followed by a digit")
 			}
 			dotAlreadySeen = true
 		}
@@ -318,54 +304,54 @@ func parseFloat(b []byte) (float64, error) {
 		start = 1
 	}
 	if cleaned[start] == '0' && len(cleaned) > start+1 && isDigit(cleaned[start+1]) {
-		return 0, unstable.NewParserError(b, "float integer part cannot have leading zeroes")
+		return 0, unstable.NewParserError(b, base, "float integer part cannot have leading zeroes")
 	}
 
 	f, err := strconv.ParseFloat(string(cleaned), 64)
 	if err != nil {
-		return 0, unstable.NewParserError(b, "unable to parse float: %w", err)
+		return 0, unstable.NewParserError(b, base, "unable to parse float: %w", err)
 	}
 
 	return f, nil
 }
 
-func parseIntHex(b []byte) (int64, error) {
-	cleaned, err := checkAndRemoveUnderscoresIntegers(b[2:])
+func parseIntHex(b []byte, base int) (int64, error) {
+	cleaned, err := checkAndRemoveUnderscoresIntegers(b[2:], base+2)
 	if err != nil {
 		return 0, err
 	}
 
 	i, err := strconv.ParseInt(string(cleaned), 16, 64)
 	if err != nil {
-		return 0, unstable.NewParserError(b, "couldn't parse hexadecimal number: %w", err)
+		return 0, unstable.NewParserError(b, base, "couldn't parse hexadecimal number: %w", err)
 	}
 
 	return i, nil
 }
 
-func parseIntOct(b []byte) (int64, error) {
-	cleaned, err := checkAndRemoveUnderscoresIntegers(b[2:])
+func parseIntOct(b []byte, base int) (int64, error) {
+	cleaned, err := checkAndRemoveUnderscoresIntegers(b[2:], base+2)
 	if err != nil {
 		return 0, err
 	}
 
 	i, err := strconv.ParseInt(string(cleaned), 8, 64)
 	if err != nil {
-		return 0, unstable.NewParserError(b, "couldn't parse octal number: %w", err)
+		return 0, unstable.NewParserError(b, base, "couldn't parse octal number: %w", err)
 	}
 
 	return i, nil
 }
 
-func parseIntBin(b []byte) (int64, error) {
-	cleaned, err := checkAndRemoveUnderscoresIntegers(b[2:])
+func parseIntBin(b []byte, base int) (int64, error) {
+	cleaned, err := checkAndRemoveUnderscoresIntegers(b[2:], base+2)
 	if err != nil {
 		return 0, err
 	}
 
 	i, err := strconv.ParseInt(string(cleaned), 2, 64)
 	if err != nil {
-		return 0, unstable.NewParserError(b, "couldn't parse binary number: %w", err)
+		return 0, unstable.NewParserError(b, base, "couldn't parse binary number: %w", err)
 	}
 
 	return i, nil
@@ -375,8 +361,8 @@ func isSign(b byte) bool {
 	return b == '+' || b == '-'
 }
 
-func parseIntDec(b []byte) (int64, error) {
-	cleaned, err := checkAndRemoveUnderscoresIntegers(b)
+func parseIntDec(b []byte, base int) (int64, error) {
+	cleaned, err := checkAndRemoveUnderscoresIntegers(b, base)
 	if err != nil {
 		return 0, err
 	}
@@ -388,18 +374,18 @@ func parseIntDec(b []byte) (int64, error) {
 	}
 
 	if len(cleaned) > startIdx+1 && cleaned[startIdx] == '0' {
-		return 0, unstable.NewParserError(b, "leading zero not allowed on decimal number")
+		return 0, unstable.NewParserError(b, base, "leading zero not allowed on decimal number")
 	}
 
 	i, err := strconv.ParseInt(string(cleaned), 10, 64)
 	if err != nil {
-		return 0, unstable.NewParserError(b, "couldn't parse decimal number: %w", err)
+		return 0, unstable.NewParserError(b, base, "couldn't parse decimal number: %w", err)
 	}
 
 	return i, nil
 }
 
-func checkAndRemoveUnderscoresIntegers(b []byte) ([]byte, error) {
+func checkAndRemoveUnderscoresIntegers(b []byte, base int) ([]byte, error) {
 	start := 0
 	if b[start] == '+' || b[start] == '-' {
 		start++
@@ -410,11 +396,11 @@ func checkAndRemoveUnderscoresIntegers(b []byte) ([]byte, error) {
 	}
 
 	if b[start] == '_' {
-		return nil, unstable.NewParserError(b[start:start+1], "number cannot start with underscore")
+		return nil, unstable.NewParserError(b[start:start+1], base+start, "number cannot start with underscore")
 	}
 
 	if b[len(b)-1] == '_' {
-		return nil, unstable.NewParserError(b[len(b)-1:], "number cannot end with underscore")
+		return nil, unstable.NewParserError(b[len(b)-1:], base+len(b)-1, "number cannot end with underscore")
 	}
 
 	// fast path
@@ -436,7 +422,7 @@ func checkAndRemoveUnderscoresIntegers(b []byte) ([]byte, error) {
 		c := b[i]
 		if c == '_' {
 			if !before {
-				return nil, unstable.NewParserError(b[i-1:i+1], "number must have at least one digit between underscores")
+				return nil, unstable.NewParserError(b[i-1:i+1], base+i-1, "number must have at least one digit between underscores")
 			}
 			before = false
 		} else {
@@ -448,13 +434,13 @@ func checkAndRemoveUnderscoresIntegers(b []byte) ([]byte, error) {
 	return cleaned, nil
 }
 
-func checkAndRemoveUnderscoresFloats(b []byte) ([]byte, error) {
+func checkAndRemoveUnderscoresFloats(b []byte, base int) ([]byte, error) {
 	if b[0] == '_' {
-		return nil, unstable.NewParserError(b[0:1], "number cannot start with underscore")
+		return nil, unstable.NewParserError(b[0:1], base, "number cannot start with underscore")
 	}
 
 	if b[len(b)-1] == '_' {
-		return nil, unstable.NewParserError(b[len(b)-1:], "number cannot end with underscore")
+		return nil, unstable.NewParserError(b[len(b)-1:], base+len(b)-1, "number cannot end with underscore")
 	}
 
 	// fast path
@@ -477,27 +463,26 @@ func checkAndRemoveUnderscoresFloats(b []byte) ([]byte, error) {
 		switch c {
 		case '_':
 			if !before {
-				return nil, unstable.NewParserError(b[i-1:i+1], "number must have at least one digit between underscores")
+				return nil, unstable.NewParserError(b[i-1:i+1], base+i-1, "number must have at least one digit between underscores")
 			}
 			if i < len(b)-1 && (b[i+1] == 'e' || b[i+1] == 'E') {
-				return nil, unstable.NewParserError(b[i+1:i+2], "cannot have underscore before exponent")
+				return nil, unstable.NewParserError(b[i+1:i+2], base+i+1, "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, unstable.NewParserError(b[i+1:i+2], "cannot have underscore after exponent")
+				return nil, unstable.NewParserError(b[i+1:i+2], base+i+1, "cannot have underscore after exponent")
 			}
 			cleaned = append(cleaned, c)
 		case '.':
 			if i < len(b)-1 && b[i+1] == '_' {
-				return nil, unstable.NewParserError(b[i+1:i+2], "cannot have underscore after decimal point")
+				return nil, unstable.NewParserError(b[i+1:i+2], base+i+1, "cannot have underscore after decimal point")
 			}
 			if i > 0 && b[i-1] == '_' {
-				return nil, unstable.NewParserError(b[i-1:i], "cannot have underscore before decimal point")
+				return nil, unstable.NewParserError(b[i-1:i], base+i-1, "cannot have underscore before decimal point")
 			}
 			cleaned = append(cleaned, c)
 		default:

errors.go

@@ -2,7 +2,6 @@ package toml
 
 import (
 	"fmt"
-	"reflect"
 	"strconv"
 	"strings"
 
@@ -100,7 +99,7 @@ func (e *DecodeError) Key() Key {
 //
 //nolint:funlen
 func wrapDecodeError(document []byte, de *unstable.ParserError) *DecodeError {
-	offset := subsliceOffset(document, de.Highlight)
+	offset := de.Offset
 
 	errMessage := de.Error()
 	errLine, errColumn := positionAtEnd(document[:offset])
@@ -262,22 +261,3 @@ func positionAtEnd(b []byte) (row int, column int) {
 
 	return row, column
 }
-
-// subsliceOffset returns the byte offset of subslice within data.
-// subslice must share the same backing array as data.
-func subsliceOffset(data []byte, subslice []byte) int {
-	if len(subslice) == 0 {
-		return 0
-	}
-
-	// Use reflect to get the data pointers of both slices.
-	// This is safe because we're only reading the pointer values for comparison.
-	dataPtr := reflect.ValueOf(data).Pointer()
-	subPtr := reflect.ValueOf(subslice).Pointer()
-
-	offset := int(subPtr - dataPtr)
-	if offset < 0 || offset > len(data) {
-		panic("subslice is not within data")
-	}
-	return offset
-}

errors_test.go

@@ -171,6 +171,7 @@ line 5`,
 
 			err := wrapDecodeError(doc, &unstable.ParserError{
 				Highlight: hl,
+				Offset:    start,
 				Message:   e.msg,
 			})
 
@@ -259,6 +260,12 @@ func TestDecodeError_Position(t *testing.T) {
 			expectedRow: 3,
 			minCol:      5,
 		},
+		{
+			name:        "missing equals on last line without trailing newline",
+			doc:         "a = 1\nb = 2\nc",
+			expectedRow: 3,
+			minCol:      1,
+		},
 	}
 
 	for _, e := range examples {
@@ -280,6 +287,100 @@ func TestDecodeError_Position(t *testing.T) {
 	}
 }
 
+func TestDecodeError_PositionAfterComments(t *testing.T) {
+	examples := []struct {
+		name        string
+		doc         string
+		expectedRow int
+		expectedCol int
+		errContains string
+	}{
+		{
+			name:        "invalid key after comment",
+			doc:         "# comment\n= \"value\"",
+			expectedRow: 2,
+			expectedCol: 1,
+			errContains: "invalid character at start of key",
+		},
+		{
+			name:        "invalid key after multiple comments",
+			doc:         "# line 1\n# line 2\n= \"value\"",
+			expectedRow: 3,
+			expectedCol: 1,
+			errContains: "invalid character at start of key",
+		},
+		{
+			name:        "invalid key after valid assignment and comment",
+			doc:         "a = 1\n# comment\n= \"value\"",
+			expectedRow: 3,
+			expectedCol: 1,
+			errContains: "invalid character at start of key",
+		},
+		{
+			name:        "invalid key on first line",
+			doc:         "= \"value\"",
+			expectedRow: 1,
+			expectedCol: 1,
+			errContains: "invalid character at start of key",
+		},
+		{
+			name:        "invalid key with leading whitespace",
+			doc:         "# comment\n  = \"value\"",
+			expectedRow: 2,
+			expectedCol: 3,
+			errContains: "invalid character at start of key",
+		},
+	}
+
+	for _, e := range examples {
+		t.Run(e.name, func(t *testing.T) {
+			var v map[string]interface{}
+			err := Unmarshal([]byte(e.doc), &v)
+			if err == nil {
+				t.Fatal("expected an error")
+			}
+
+			var derr *DecodeError
+			if !errors.As(err, &derr) {
+				t.Fatalf("expected DecodeError, got %T: %v", err, err)
+			}
+
+			row, col := derr.Position()
+			if row != e.expectedRow {
+				t.Errorf("row: got %d, want %d (error: %s)", row, e.expectedRow, derr.String())
+			}
+			if col != e.expectedCol {
+				t.Errorf("col: got %d, want %d (error: %s)", col, e.expectedCol, derr.String())
+			}
+			if !strings.Contains(derr.Error(), e.errContains) {
+				t.Errorf("error %q does not contain %q", derr.Error(), e.errContains)
+			}
+		})
+	}
+}
+
+func TestDecodeError_HumanStringAfterComments(t *testing.T) {
+	doc := "# comment\n= \"value\""
+	var v map[string]interface{}
+	err := Unmarshal([]byte(doc), &v)
+	if err == nil {
+		t.Fatal("expected an error")
+	}
+
+	var derr *DecodeError
+	if !errors.As(err, &derr) {
+		t.Fatalf("expected DecodeError, got %T: %v", err, err)
+	}
+
+	human := derr.String()
+	if !strings.Contains(human, "= \"value\"") {
+		t.Errorf("human-readable error should show the offending line, got:\n%s", human)
+	}
+	if !strings.Contains(human, "2|") {
+		t.Errorf("human-readable error should reference line 2, got:\n%s", human)
+	}
+}
+
 func TestStrictErrorUnwrap(t *testing.T) {
 	fo := bytes.NewBufferString(`
 Missing = 1

internal/characters/utf8.go

@@ -24,61 +24,57 @@ import (
 // 0x9 => tab, ok
 // 0xA - 0x1F => invalid
 // 0x7F => invalid
-func Utf8TomlValidAlreadyEscaped(p []byte) []byte {
+func Utf8TomlValidAlreadyEscaped(p []byte) int {
+	consumed := 0
+
 	// Fast path. Check for and skip 8 bytes of ASCII characters per iteration.
 	for len(p) >= 8 {
-		// Combining two 32 bit loads allows the same code to be used
-		// for 32 and 64 bit platforms.
-		// The compiler can generate a 32bit load for first32 and second32
-		// on many platforms. See test/codegen/memcombine.go.
 		first32 := uint32(p[0]) | uint32(p[1])<<8 | uint32(p[2])<<16 | uint32(p[3])<<24
 		second32 := uint32(p[4]) | uint32(p[5])<<8 | uint32(p[6])<<16 | uint32(p[7])<<24
 		if (first32|second32)&0x80808080 != 0 {
-			// Found a non ASCII byte (>= RuneSelf).
 			break
 		}
 
 		for i, b := range p[:8] {
 			if InvalidASCII(b) {
-				return p[i : i+1]
+				return consumed + i
 			}
 		}
 
 		p = p[8:]
+		consumed += 8
 	}
 	n := len(p)
 	for i := 0; i < n; {
 		pi := p[i]
 		if pi < utf8.RuneSelf {
 			if InvalidASCII(pi) {
-				return p[i : i+1]
+				return consumed + i
 			}
 			i++
 			continue
 		}
 		x := first[pi]
 		if x == xx {
-			// Illegal starter byte.
-			return p[i : i+1]
+			return consumed + i
 		}
 		size := int(x & 7)
 		if i+size > n {
-			// Short or invalid.
-			return p[i:n]
+			return consumed + i
 		}
 		accept := acceptRanges[x>>4]
 		if c := p[i+1]; c < accept.lo || accept.hi < c {
-			return p[i : i+2]
+			return consumed + i
 		} else if size == 2 { //revive:disable:empty-block
 		} else if c := p[i+2]; c < locb || hicb < c {
-			return p[i : i+3]
+			return consumed + i
 		} else if size == 3 { //revive:disable:empty-block
 		} else if c := p[i+3]; c < locb || hicb < c {
-			return p[i : i+4]
+			return consumed + i
 		}
 		i += size
 	}
-	return nil
+	return -1
 }
 
 // Utf8ValidNext returns the size of the next rune if valid, 0 otherwise.

localtime.go

@@ -32,7 +32,7 @@ func (d LocalDate) MarshalText() ([]byte, error) {
 
 // UnmarshalText parses b using RFC 3339 to fill d.
 func (d *LocalDate) UnmarshalText(b []byte) error {
-	res, err := parseLocalDate(b)
+	res, err := parseLocalDate(b, 0)
 	if err != nil {
 		return err
 	}
@@ -75,9 +75,9 @@ func (d LocalTime) MarshalText() ([]byte, error) {
 
 // UnmarshalText parses b using RFC 3339 to fill d.
 func (d *LocalTime) UnmarshalText(b []byte) error {
-	res, left, err := parseLocalTime(b)
+	res, left, err := parseLocalTime(b, 0)
 	if err == nil && len(left) != 0 {
-		err = unstable.NewParserError(left, "extra characters")
+		err = unstable.NewParserError(left, len(b)-len(left), "extra characters")
 	}
 	if err != nil {
 		return err
@@ -109,9 +109,9 @@ func (d LocalDateTime) MarshalText() ([]byte, error) {
 
 // UnmarshalText parses b using RFC 3339 to fill d.
 func (d *LocalDateTime) UnmarshalText(data []byte) error {
-	res, left, err := parseLocalDateTime(data)
+	res, left, err := parseLocalDateTime(data, 0)
 	if err == nil && len(left) != 0 {
-		err = unstable.NewParserError(left, "extra characters")
+		err = unstable.NewParserError(left, len(data)-len(left), "extra characters")
 	}
 	if err != nil {
 		return err

marshaler.go

@@ -704,15 +704,18 @@ func (enc *Encoder) encodeMap(b []byte, ctx encoderCtx, v reflect.Value) ([]byte
 	for iter.Next() {
 		v := iter.Value()
 
-		if isNil(v) {
-			// For nil pointers, convert to zero value of the element type.
-			// This allows round-trip marshaling of maps with nil pointer values.
-			// For nil interfaces and nil maps, skip since we can't derive a type.
-			if v.Kind() == reflect.Ptr {
+		// Handle nil values: convert nil pointers to zero value,
+		// skip nil interfaces and nil maps.
+		switch v.Kind() {
+		case reflect.Ptr:
+			if v.IsNil() {
 				v = reflect.Zero(v.Type().Elem())
-			} else {
+			}
+		case reflect.Interface, reflect.Map:
+			if v.IsNil() {
 				continue
 			}
+		default:
 		}
 
 		k, err := enc.keyToString(iter.Key())
@@ -936,7 +939,7 @@ func (enc *Encoder) encodeTable(b []byte, ctx encoderCtx, t table) ([]byte, erro
 		if shouldOmitEmpty(kv.Options, kv.Value) {
 			continue
 		}
-		if shouldOmitZero(kv.Options, kv.Value) {
+		if kv.Options.omitzero && shouldOmitZero(kv.Options, kv.Value) {
 			continue
 		}
 		hasNonEmptyKV = true
@@ -958,7 +961,7 @@ func (enc *Encoder) encodeTable(b []byte, ctx encoderCtx, t table) ([]byte, erro
 		if shouldOmitEmpty(table.Options, table.Value) {
 			continue
 		}
-		if shouldOmitZero(table.Options, table.Value) {
+		if table.Options.omitzero && shouldOmitZero(table.Options, table.Value) {
 			continue
 		}
 		if first {
@@ -995,7 +998,7 @@ func (enc *Encoder) encodeTableInline(b []byte, ctx encoderCtx, t table) ([]byte
 		if shouldOmitEmpty(kv.Options, kv.Value) {
 			continue
 		}
-		if shouldOmitZero(kv.Options, kv.Value) {
+		if kv.Options.omitzero && shouldOmitZero(kv.Options, kv.Value) {
 			continue
 		}
 

strict.go

@@ -54,10 +54,12 @@ func (s *strict) MissingTable(node *unstable.Node) {
 		return
 	}
 
+	loc, offset := s.keyLocation(node)
 	s.missing = append(s.missing, unstable.ParserError{
-		Highlight: s.keyLocation(node),
+		Highlight: loc,
 		Message:   "missing table",
 		Key:       s.key.Key(),
+		Offset:    offset,
 	})
 }
 
@@ -66,10 +68,12 @@ func (s *strict) MissingField(node *unstable.Node) {
 		return
 	}
 
+	loc, offset := s.keyLocation(node)
 	s.missing = append(s.missing, unstable.ParserError{
-		Highlight: s.keyLocation(node),
+		Highlight: loc,
 		Message:   "missing field",
 		Key:       s.key.Key(),
+		Offset:    offset,
 	})
 }
 
@@ -90,7 +94,7 @@ func (s *strict) Error(doc []byte) error {
 	return err
 }
 
-func (s *strict) keyLocation(node *unstable.Node) []byte {
+func (s *strict) keyLocation(node *unstable.Node) ([]byte, int) {
 	k := node.Key()
 
 	hasOne := k.Next()
@@ -98,7 +102,6 @@ func (s *strict) keyLocation(node *unstable.Node) []byte {
 		panic("should not be called with empty key")
 	}
 
-	// Get the range from the first key to the last key.
 	firstRaw := k.Node().Raw
 	lastRaw := firstRaw
 
@@ -106,9 +109,8 @@ func (s *strict) keyLocation(node *unstable.Node) []byte {
 		lastRaw = k.Node().Raw
 	}
 
-	// Compute the slice from the document using the ranges.
 	start := firstRaw.Offset
 	end := lastRaw.Offset + lastRaw.Length
 
-	return s.doc[start:end]
+	return s.doc[start:end], int(start)
 }

test-go-versions.sh

@@ -9,7 +9,7 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
-# Go versions to test (1.11 through 1.25)
+# Go versions to test (1.11 through 1.26)
 GO_VERSIONS=(
     "1.11"
     "1.12"
@@ -26,6 +26,7 @@ GO_VERSIONS=(
     "1.23"
     "1.24"
     "1.25"
+    "1.26"
 )
 
 # Default values
@@ -64,7 +65,7 @@ EXAMPLES:
     $0                          # Test all Go versions in parallel
     $0 --sequential             # Test all Go versions sequentially
     $0 1.21 1.22 1.23          # Test specific versions
-    $0 --verbose --output ./results 1.24 1.25  # Verbose output to custom directory
+    $0 --verbose --output ./results 1.25 1.26  # Verbose output to custom directory
 
 EXIT CODES:
     0                   Recent Go versions pass (good compatibility)
@@ -136,8 +137,8 @@ fi
 
 # Validate Go versions
 for version in "${GO_VERSIONS[@]}"; do
-    if ! [[ "$version" =~ ^1\.(1[1-9]|2[0-5])$ ]]; then
-        log_error "Invalid Go version: $version. Supported versions: 1.11-1.25"
+    if ! [[ "$version" =~ ^1\.(1[1-9]|2[0-6])$ ]]; then
+        log_error "Invalid Go version: $version. Supported versions: 1.11-1.26"
         exit 1
     fi
 done

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, int(key.Node().Raw.Offset), "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
@@ -680,7 +748,7 @@ func (d *decoder) tryTextUnmarshaler(node *unstable.Node, v reflect.Value) (bool
 	if v.CanAddr() && v.Addr().Type().Implements(textUnmarshalerType) {
 		err := v.Addr().Interface().(encoding.TextUnmarshaler).UnmarshalText(node.Data)
 		if err != nil {
-			return false, unstable.NewParserError(d.p.Raw(node.Raw), "%w", err)
+			return false, unstable.NewParserError(d.p.Raw(node.Raw), int(node.Raw.Offset), "%w", err)
 		}
 
 		return true, nil
@@ -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))
 			}
 		}
 	}
@@ -827,7 +896,7 @@ func (d *decoder) unmarshalInlineTable(itable *unstable.Node, v reflect.Value) e
 		}
 		return d.unmarshalInlineTable(itable, elem)
 	default:
-		return unstable.NewParserError(d.p.Raw(itable.Raw), "cannot store inline table in Go type %s", v.Kind())
+		return unstable.NewParserError(d.p.Raw(itable.Raw), int(itable.Raw.Offset), "cannot store inline table in Go type %s", v.Kind())
 	}
 
 	it := itable.Children()
@@ -847,26 +916,26 @@ func (d *decoder) unmarshalInlineTable(itable *unstable.Node, v reflect.Value) e
 }
 
 func (d *decoder) unmarshalDateTime(value *unstable.Node, v reflect.Value) error {
-	dt, err := parseDateTime(value.Data)
+	dt, err := parseDateTime(value.Data, int(value.Raw.Offset))
 	if err != nil {
 		return err
 	}
 
 	if v.Kind() != reflect.Interface && v.Type() != timeType {
-		return unstable.NewParserError(d.p.Raw(value.Raw), "%s", d.typeMismatchString("datetime", v.Type()))
+		return unstable.NewParserError(d.p.Raw(value.Raw), int(value.Raw.Offset), "%s", d.typeMismatchString("datetime", v.Type()))
 	}
 	v.Set(reflect.ValueOf(dt))
 	return nil
 }
 
 func (d *decoder) unmarshalLocalDate(value *unstable.Node, v reflect.Value) error {
-	ld, err := parseLocalDate(value.Data)
+	ld, err := parseLocalDate(value.Data, int(value.Raw.Offset))
 	if err != nil {
 		return err
 	}
 
 	if v.Kind() != reflect.Interface && v.Type() != timeType {
-		return unstable.NewParserError(d.p.Raw(value.Raw), "%s", d.typeMismatchString("local date", v.Type()))
+		return unstable.NewParserError(d.p.Raw(value.Raw), int(value.Raw.Offset), "%s", d.typeMismatchString("local date", v.Type()))
 	}
 	if v.Type() == timeType {
 		v.Set(reflect.ValueOf(ld.AsTime(time.Local)))
@@ -877,34 +946,34 @@ func (d *decoder) unmarshalLocalDate(value *unstable.Node, v reflect.Value) erro
 }
 
 func (d *decoder) unmarshalLocalTime(value *unstable.Node, v reflect.Value) error {
-	lt, rest, err := parseLocalTime(value.Data)
+	lt, rest, err := parseLocalTime(value.Data, int(value.Raw.Offset))
 	if err != nil {
 		return err
 	}
 
 	if len(rest) > 0 {
-		return unstable.NewParserError(rest, "extra characters at the end of a local time")
+		return unstable.NewParserError(rest, int(value.Raw.Offset)+len(value.Data)-len(rest), "extra characters at the end of a local time")
 	}
 
 	if v.Kind() != reflect.Interface {
-		return unstable.NewParserError(d.p.Raw(value.Raw), "%s", d.typeMismatchString("local time", v.Type()))
+		return unstable.NewParserError(d.p.Raw(value.Raw), int(value.Raw.Offset), "%s", d.typeMismatchString("local time", v.Type()))
 	}
 	v.Set(reflect.ValueOf(lt))
 	return nil
 }
 
 func (d *decoder) unmarshalLocalDateTime(value *unstable.Node, v reflect.Value) error {
-	ldt, rest, err := parseLocalDateTime(value.Data)
+	ldt, rest, err := parseLocalDateTime(value.Data, int(value.Raw.Offset))
 	if err != nil {
 		return err
 	}
 
 	if len(rest) > 0 {
-		return unstable.NewParserError(rest, "extra characters at the end of a local date time")
+		return unstable.NewParserError(rest, int(value.Raw.Offset)+len(value.Data)-len(rest), "extra characters at the end of a local date time")
 	}
 
 	if v.Kind() != reflect.Interface && v.Type() != timeType {
-		return unstable.NewParserError(d.p.Raw(value.Raw), "%s", d.typeMismatchString("local datetime", v.Type()))
+		return unstable.NewParserError(d.p.Raw(value.Raw), int(value.Raw.Offset), "%s", d.typeMismatchString("local datetime", v.Type()))
 	}
 	if v.Type() == timeType {
 		v.Set(reflect.ValueOf(ldt.AsTime(time.Local)))
@@ -923,14 +992,14 @@ func (d *decoder) unmarshalBool(value *unstable.Node, v reflect.Value) error {
 	case reflect.Interface:
 		v.Set(reflect.ValueOf(b))
 	default:
-		return unstable.NewParserError(value.Data, "cannot assign boolean to a %t", b)
+		return unstable.NewParserError(value.Data, int(value.Raw.Offset), "cannot assign boolean to a %t", b)
 	}
 
 	return nil
 }
 
 func (d *decoder) unmarshalFloat(value *unstable.Node, v reflect.Value) error {
-	f, err := parseFloat(value.Data)
+	f, err := parseFloat(value.Data, int(value.Raw.Offset))
 	if err != nil {
 		return err
 	}
@@ -940,13 +1009,13 @@ func (d *decoder) unmarshalFloat(value *unstable.Node, v reflect.Value) error {
 		v.SetFloat(f)
 	case reflect.Float32:
 		if f > math.MaxFloat32 {
-			return unstable.NewParserError(value.Data, "number %f does not fit in a float32", f)
+			return unstable.NewParserError(value.Data, int(value.Raw.Offset), "number %f does not fit in a float32", f)
 		}
 		v.SetFloat(f)
 	case reflect.Interface:
 		v.Set(reflect.ValueOf(f))
 	default:
-		return unstable.NewParserError(value.Data, "float cannot be assigned to %s", v.Kind())
+		return unstable.NewParserError(value.Data, int(value.Raw.Offset), "float cannot be assigned to %s", v.Kind())
 	}
 
 	return nil
@@ -979,7 +1048,7 @@ func (d *decoder) unmarshalInteger(value *unstable.Node, v reflect.Value) error
 		return d.unmarshalFloat(value, v)
 	}
 
-	i, err := parseInteger(value.Data)
+	i, err := parseInteger(value.Data, int(value.Raw.Offset))
 	if err != nil {
 		return err
 	}
@@ -1047,7 +1116,7 @@ func (d *decoder) unmarshalInteger(value *unstable.Node, v reflect.Value) error
 	case reflect.Interface:
 		r = reflect.ValueOf(i)
 	default:
-		return unstable.NewParserError(d.p.Raw(value.Raw), "%s", d.typeMismatchString("integer", v.Type()))
+		return unstable.NewParserError(d.p.Raw(value.Raw), int(value.Raw.Offset), "%s", d.typeMismatchString("integer", v.Type()))
 	}
 
 	if !r.Type().AssignableTo(v.Type()) {
@@ -1066,7 +1135,7 @@ func (d *decoder) unmarshalString(value *unstable.Node, v reflect.Value) error {
 	case reflect.Interface:
 		v.Set(reflect.ValueOf(string(value.Data)))
 	default:
-		return unstable.NewParserError(d.p.Raw(value.Raw), "%s", d.typeMismatchString("string", v.Type()))
+		return unstable.NewParserError(d.p.Raw(value.Raw), int(value.Raw.Offset), "%s", d.typeMismatchString("string", v.Type()))
 	}
 
 	return nil
@@ -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))
 					}
 				}
 			}

unmarshaler_test.go

@@ -96,6 +96,132 @@ func ExampleUnmarshal() {
 	// tags: [go toml]
 }
 
+// pluginConfig demonstrates how to implement dynamic unmarshaling
+// based on a "type" field. This pattern is useful for plugin systems
+// or polymorphic configuration.
+type pluginConfig struct {
+	Type   string
+	Config any
+}
+
+func (p *pluginConfig) UnmarshalTOML(data []byte) error {
+	// First, decode just the type field
+	var typeOnly struct {
+		Type string `toml:"type"`
+	}
+	if err := toml.Unmarshal(data, &typeOnly); err != nil {
+		return err
+	}
+	p.Type = typeOnly.Type
+
+	// Now decode the config based on the type
+	switch typeOnly.Type {
+	case "database":
+		var cfg struct {
+			Type string `toml:"type"`
+			Host string `toml:"host"`
+			Port int    `toml:"port"`
+		}
+		if err := toml.Unmarshal(data, &cfg); err != nil {
+			return err
+		}
+		p.Config = map[string]any{"host": cfg.Host, "port": cfg.Port}
+	case "cache":
+		var cfg struct {
+			Type string `toml:"type"`
+			TTL  int    `toml:"ttl"`
+		}
+		if err := toml.Unmarshal(data, &cfg); err != nil {
+			return err
+		}
+		p.Config = map[string]any{"ttl": cfg.TTL}
+	}
+	return nil
+}
+
+// This example demonstrates dynamic unmarshaling based on a discriminator
+// field. The pluginConfig type uses UnmarshalTOML to first read the "type"
+// field, then decode the rest of the configuration based on that type.
+// This pattern is useful for plugin systems or configuration that varies
+// by type.
+func ExampleDecoder_EnableUnmarshalerInterface_dynamicConfig() {
+	doc := `
+[[plugins]]
+type = "database"
+host = "localhost"
+port = 5432
+
+[[plugins]]
+type = "cache"
+ttl = 300
+`
+	type Config struct {
+		Plugins []pluginConfig `toml:"plugins"`
+	}
+
+	var cfg Config
+	err := toml.NewDecoder(strings.NewReader(doc)).
+		EnableUnmarshalerInterface().
+		Decode(&cfg)
+	if err != nil {
+		panic(err)
+	}
+
+	for _, p := range cfg.Plugins {
+		fmt.Printf("type=%s config=%v\n", p.Type, p.Config)
+	}
+	// Output:
+	// type=database config=map[host:localhost port:5432]
+	// type=cache config=map[ttl:300]
+}
+
+// This example demonstrates using RawMessage to capture raw TOML bytes
+// for later processing. RawMessage is similar to json.RawMessage - it
+// delays decoding so you can inspect the raw content or decode it
+// differently based on context.
+func ExampleDecoder_EnableUnmarshalerInterface_rawMessage() {
+	doc := `
+[plugin]
+name = "example"
+version = "1.0"
+enabled = true
+`
+
+	type Config struct {
+		Plugin unstable.RawMessage `toml:"plugin"`
+	}
+
+	var cfg Config
+	err := toml.NewDecoder(strings.NewReader(doc)).
+		EnableUnmarshalerInterface().
+		Decode(&cfg)
+	if err != nil {
+		panic(err)
+	}
+
+	// cfg.Plugin contains the raw TOML bytes
+	fmt.Printf("Raw TOML captured:\n%s", cfg.Plugin)
+
+	// You can later decode it into a specific type
+	var plugin struct {
+		Name    string `toml:"name"`
+		Version string `toml:"version"`
+		Enabled bool   `toml:"enabled"`
+	}
+	if err := toml.Unmarshal(cfg.Plugin, &plugin); err != nil {
+		panic(err)
+	}
+	fmt.Printf("Decoded: name=%s version=%s enabled=%v\n",
+		plugin.Name, plugin.Version, plugin.Enabled)
+
+	// Output:
+	// Raw TOML captured:
+	// name = "example"
+	// version = "1.0"
+	// enabled = true
+	// Decoded: name=example version=1.0 enabled=true
+}
+
 type badReader struct{}
 
 func (r *badReader) Read([]byte) (int, error) {
@@ -3900,8 +4026,8 @@ type CustomUnmarshalerKey struct {
 	A int64
 }
 
-func (k *CustomUnmarshalerKey) UnmarshalTOML(value *unstable.Node) error {
-	item, err := strconv.ParseInt(string(value.Data), 10, 64)
+func (k *CustomUnmarshalerKey) UnmarshalTOML(data []byte) error {
+	item, err := strconv.ParseInt(string(data), 10, 64)
 	if err != nil {
 		return fmt.Errorf("error converting to int64, %w", err)
 	}
@@ -3989,7 +4115,7 @@ foo = "bar"`,
 
 type doc994 struct{}
 
-func (d *doc994) UnmarshalTOML(*unstable.Node) error {
+func (d *doc994) UnmarshalTOML([]byte) error {
 	return errors.New("expected-error")
 }
 
@@ -4012,8 +4138,8 @@ type doc994ok struct {
 	S string
 }
 
-func (d *doc994ok) UnmarshalTOML(value *unstable.Node) error {
-	d.S = string(value.Data) + " from unmarshaler"
+func (d *doc994ok) UnmarshalTOML(data []byte) error {
+	d.S = string(data) + " from unmarshaler"
 	return nil
 }
 
@@ -4026,7 +4152,8 @@ func TestIssue994_OK(t *testing.T) {
 		Decode(&d)
 
 	assert.NoError(t, err)
-	assert.Equal(t, "bar from unmarshaler", d.S)
+	// With bytes-based interface, raw TOML bytes are passed including quotes
+	assert.Equal(t, "\"bar\" from unmarshaler", d.S)
 }
 
 func TestIssue995(t *testing.T) {
@@ -4385,3 +4512,265 @@ func TestIssue1028(t *testing.T) {
 		assert.Error(t, err)
 	})
 }
+
+// Tests for issue #873 - Bring back toml.Unmarshaler for tables and arrays
+
+type customTable873 struct {
+	Keys   []string
+	Values map[string]string
+}
+
+func (c *customTable873) UnmarshalTOML(data []byte) error {
+	c.Keys = []string{}
+	c.Values = make(map[string]string)
+
+	// Parse the raw TOML bytes into a map to extract keys in order
+	// For this test, we use a simple line-by-line parser to preserve order
+	lines := bytes.Split(data, []byte{'\n'})
+	for _, line := range lines {
+		line = bytes.TrimSpace(line)
+		if len(line) == 0 {
+			continue
+		}
+		// Skip table headers
+		if line[0] == '[' {
+			continue
+		}
+		// Parse key = value
+		eqIdx := bytes.Index(line, []byte{'='})
+		if eqIdx < 0 {
+			continue
+		}
+		key := string(bytes.TrimSpace(line[:eqIdx]))
+		// Remove quotes from quoted keys
+		if len(key) >= 2 && key[0] == '"' && key[len(key)-1] == '"' {
+			key = key[1 : len(key)-1]
+		}
+		valueBytes := bytes.TrimSpace(line[eqIdx+1:])
+		// Remove quotes from string values
+		if len(valueBytes) >= 2 && valueBytes[0] == '"' && valueBytes[len(valueBytes)-1] == '"' {
+			valueBytes = valueBytes[1 : len(valueBytes)-1]
+		}
+		c.Keys = append(c.Keys, key)
+		c.Values[key] = string(valueBytes)
+	}
+
+	return nil
+}
+
+// Test for split tables - when the same parent table is defined in multiple places
+// This is a key requirement for issue #873: if type A implements Unmarshaler,
+// and [a.b] and [a.d] are defined with another table [x] in between,
+// A should receive content for both b and d, but not x.
+func TestIssue873_SplitTables(t *testing.T) {
+	// For this test, we expect each sub-table to be handled separately
+	// The parent doesn't receive the sub-tables directly - each sub-table
+	// (b and d) gets its own call to handleKeyValues
+	type Config struct {
+		A struct {
+			B customTable873 `toml:"b"`
+			D customTable873 `toml:"d"`
+		} `toml:"a"`
+		X customTable873 `toml:"x"`
+	}
+
+	doc := `
+[a.b]
+C = "1"
+
+[x]
+Y = "100"
+
+[a.d]
+E = "2"
+`
+
+	var cfg Config
+	err := toml.NewDecoder(bytes.NewReader([]byte(doc))).
+		EnableUnmarshalerInterface().
+		Decode(&cfg)
+
+	assert.NoError(t, err)
+	// Each sub-table should have received its own key-values
+	assert.Equal(t, []string{"C"}, cfg.A.B.Keys)
+	assert.Equal(t, "1", cfg.A.B.Values["C"])
+	assert.Equal(t, []string{"E"}, cfg.A.D.Keys)
+	assert.Equal(t, "2", cfg.A.D.Values["E"])
+	assert.Equal(t, []string{"Y"}, cfg.X.Keys)
+	assert.Equal(t, "100", cfg.X.Values["Y"])
+}
+
+// Test using RawMessage to capture raw TOML bytes
+func TestIssue873_RawMessage(t *testing.T) {
+	type Config struct {
+		Plugin unstable.RawMessage `toml:"plugin"`
+	}
+
+	doc := `
+[plugin]
+name = "example"
+version = "1.0"
+`
+
+	var cfg Config
+	err := toml.NewDecoder(bytes.NewReader([]byte(doc))).
+		EnableUnmarshalerInterface().
+		Decode(&cfg)
+
+	assert.NoError(t, err)
+	// RawMessage should contain the raw key-value bytes
+	expected := "name = \"example\"\nversion = \"1.0\"\n"
+	assert.Equal(t, expected, string(cfg.Plugin))
+}
+
+// Test keys that need quoting (contain special characters)
+func TestIssue873_QuotedKeys(t *testing.T) {
+	type Config struct {
+		Section customTable873 `toml:"section"`
+	}
+
+	doc := `
+[section]
+"key with spaces" = "value1"
+"key.with.dots" = "value2"
+`
+
+	var cfg Config
+	err := toml.NewDecoder(bytes.NewReader([]byte(doc))).
+		EnableUnmarshalerInterface().
+		Decode(&cfg)
+
+	assert.NoError(t, err)
+	assert.Equal(t, 2, len(cfg.Section.Keys))
+	assert.Equal(t, "value1", cfg.Section.Values["key with spaces"])
+	assert.Equal(t, "value2", cfg.Section.Values["key.with.dots"])
+}
+
+// errorUnmarshaler873 is used to test error propagation from UnmarshalTOML
+type errorUnmarshaler873 struct{}
+
+func (e *errorUnmarshaler873) UnmarshalTOML([]byte) error {
+	return errors.New("intentional error")
+}
+
+// Test error propagation from UnmarshalTOML
+func TestIssue873_UnmarshalerError(t *testing.T) {
+	doc := `
+[section]
+key = "value"
+`
+
+	type Config struct {
+		Section errorUnmarshaler873 `toml:"section"`
+	}
+
+	var cfg Config
+	err := toml.NewDecoder(bytes.NewReader([]byte(doc))).
+		EnableUnmarshalerInterface().
+		Decode(&cfg)
+
+	assert.Error(t, err)
+	assert.True(t, strings.Contains(err.Error(), "intentional error"))
+}
+
+// Test dotted keys in a table (e.g., a.b = value)
+func TestIssue873_DottedKeys(t *testing.T) {
+	type Config struct {
+		Section customTable873 `toml:"section"`
+	}
+
+	doc := `
+[section]
+sub.key = "value1"
+another.nested.key = "value2"
+`
+
+	var cfg Config
+	err := toml.NewDecoder(bytes.NewReader([]byte(doc))).
+		EnableUnmarshalerInterface().
+		Decode(&cfg)
+
+	assert.NoError(t, err)
+	assert.Equal(t, 2, len(cfg.Section.Keys))
+	// The dotted keys should be preserved in the raw output
+	assert.Equal(t, "value1", cfg.Section.Values["sub.key"])
+	assert.Equal(t, "value2", cfg.Section.Values["another.nested.key"])
+}
+
+// Test pointer to pointer to Unmarshaler (covers pointer dereferencing loop)
+func TestIssue873_DoublePointerUnmarshaler(t *testing.T) {
+	type Config struct {
+		Section **customTable873 `toml:"section"`
+	}
+
+	doc := `
+[section]
+key = "value"
+`
+
+	var cfg Config
+	err := toml.NewDecoder(bytes.NewReader([]byte(doc))).
+		EnableUnmarshalerInterface().
+		Decode(&cfg)
+
+	assert.NoError(t, err)
+	assert.True(t, cfg.Section != nil)
+	assert.True(t, *cfg.Section != nil)
+	assert.Equal(t, []string{"key"}, (*cfg.Section).Keys)
+	assert.Equal(t, "value", (*cfg.Section).Values["key"])
+}
+
+// formattingCapture captures the raw TOML bytes to verify formatting preservation
+type formattingCapture struct {
+	RawBytes string
+}
+
+func (f *formattingCapture) UnmarshalTOML(data []byte) error {
+	f.RawBytes = string(data)
+	return nil
+}
+
+func TestIssue873_FormattingPreservation(t *testing.T) {
+	type Config struct {
+		Section *formattingCapture `toml:"section"`
+	}
+
+	// Test that various formatting styles are preserved:
+	// - Extra spaces around '='
+	// - Literal strings (single quotes)
+	// - Hex numbers
+	// - Inline tables
+	doc := `[section]
+key1   =   "value with spaces"
+key2 = 'literal string'
+hex_val = 0xDEADBEEF
+inline = { a = 1, b = 2 }
+`
+
+	var cfg Config
+	err := toml.NewDecoder(bytes.NewReader([]byte(doc))).
+		EnableUnmarshalerInterface().
+		Decode(&cfg)
+
+	assert.NoError(t, err)
+	assert.True(t, cfg.Section != nil)
+
+	// The raw bytes should preserve original formatting
+	raw := cfg.Section.RawBytes
+
+	// Check that extra spaces around '=' are preserved
+	assert.True(t, strings.Contains(raw, "key1   =   \"value with spaces\""),
+		"Expected spacing to be preserved, got: %s", raw)
+
+	// Check that literal string style is preserved
+	assert.True(t, strings.Contains(raw, "key2 = 'literal string'"),
+		"Expected literal string to be preserved, got: %s", raw)
+
+	// Check that hex format is preserved
+	assert.True(t, strings.Contains(raw, "hex_val = 0xDEADBEEF"),
+		"Expected hex format to be preserved, got: %s", raw)
+
+	// Check that inline table is preserved
+	assert.True(t, strings.Contains(raw, "inline = { a = 1, b = 2 }"),
+		"Expected inline table to be preserved, got: %s", raw)
+}

unstable/ast.go

@@ -28,12 +28,16 @@ func (c *Iterator) Next() bool {
 	if c.nodes == nil {
 		return false
 	}
+	nodes := *c.nodes
 	if !c.started {
 		c.started = true
-	} else if c.idx >= 0 {
-		c.idx = (*c.nodes)[c.idx].next
+	} else {
+		idx := c.idx
+		if idx >= 0 && int(idx) < len(nodes) {
+			c.idx = nodes[idx].next
+		}
 	}
-	return c.idx >= 0 && int(c.idx) < len(*c.nodes)
+	return c.idx >= 0 && int(c.idx) < len(nodes)
 }
 
 // IsLast returns true if the current node of the iterator is the last

unstable/benchmark_test.go

@@ -35,7 +35,7 @@ func BenchmarkScanComments(b *testing.B) {
 			b.ResetTimer()
 
 			for i := 0; i < b.N; i++ {
-				_, _, _ = scanComment(input)
+				_, _, _ = scanComment(input, 0)
 			}
 		})
 	}

unstable/parser.go

@@ -16,6 +16,7 @@ type ParserError struct {
 	Highlight []byte
 	Message   string
 	Key       []string // optional
+	Offset    int
 }
 
 // Error is the implementation of the error interface.
@@ -27,9 +28,10 @@ func (e *ParserError) Error() string {
 //
 // Warning: Highlight needs to be a subslice of Parser.data, so only slices
 // returned by Parser.Raw are valid candidates.
-func NewParserError(highlight []byte, format string, args ...interface{}) error {
+func NewParserError(highlight []byte, offset int, format string, args ...interface{}) error {
 	return &ParserError{
 		Highlight: highlight,
+		Offset:    offset,
 		Message:   fmt.Errorf(format, args...).Error(),
 	}
 }
@@ -64,14 +66,8 @@ func (p *Parser) Data() []byte {
 	return p.data
 }
 
-// Range returns a range description that corresponds to a given slice of the
-// input. If the argument is not a subslice of the parser input, this function
-// panics.
-func (p *Parser) Range(b []byte) Range {
-	return Range{
-		Offset: uint32(p.subsliceOffset(b)), //nolint:gosec // TOML documents are small
-		Length: uint32(len(b)),              //nolint:gosec // TOML documents are small
-	}
+func (p *Parser) offsetOf(b []byte) int {
+	return len(p.data) - len(b)
 }
 
 // rangeOfToken computes the Range of a token given the remaining bytes after the token.
@@ -82,13 +78,6 @@ func (p *Parser) rangeOfToken(token, rest []byte) Range {
 	return Range{Offset: uint32(offset), Length: uint32(len(token))} //nolint:gosec // TOML documents are small
 }
 
-// subsliceOffset returns the byte offset of subslice b within p.data.
-// b must be a suffix (tail) of p.data.
-func (p *Parser) subsliceOffset(b []byte) int {
-	// b is a suffix of p.data, so its offset is len(p.data) - len(b)
-	return len(p.data) - len(b)
-}
-
 // Raw returns the slice corresponding to the bytes in the given range.
 func (p *Parser) Raw(raw Range) []byte {
 	return p.data[raw.Offset : raw.Offset+raw.Length]
@@ -198,16 +187,16 @@ func (p *Parser) parseNewline(b []byte) ([]byte, error) {
 	}
 
 	if b[0] == '\r' {
-		_, rest, err := scanWindowsNewline(b)
+		_, rest, err := scanWindowsNewline(b, p.offsetOf(b))
 		return rest, err
 	}
 
-	return nil, NewParserError(b[0:1], "expected newline but got %#U", b[0])
+	return nil, NewParserError(b[0:1], p.offsetOf(b), "expected newline but got %#U", b[0])
 }
 
 func (p *Parser) parseComment(b []byte) (reference, []byte, error) {
 	ref := invalidReference
-	data, rest, err := scanComment(b)
+	data, rest, err := scanComment(b, p.offsetOf(b))
 	if p.KeepComments && err == nil {
 		ref = p.builder.Push(Node{
 			Kind: Comment,
@@ -291,12 +280,12 @@ func (p *Parser) parseArrayTable(b []byte) (reference, []byte, error) {
 	p.builder.AttachChild(ref, k)
 	b = p.parseWhitespace(b)
 
-	b, err = expect(']', b)
+	b, err = expect(']', b, p.offsetOf(b))
 	if err != nil {
 		return ref, nil, err
 	}
 
-	b, err = expect(']', b)
+	b, err = expect(']', b, p.offsetOf(b))
 
 	return ref, b, err
 }
@@ -321,13 +310,16 @@ func (p *Parser) parseStdTable(b []byte) (reference, []byte, error) {
 
 	b = p.parseWhitespace(b)
 
-	b, err = expect(']', b)
+	b, err = expect(']', b, p.offsetOf(b))
 
 	return ref, b, err
 }
 
 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,
 	})
@@ -342,10 +334,10 @@ func (p *Parser) parseKeyval(b []byte) (reference, []byte, error) {
 	b = p.parseWhitespace(b)
 
 	if len(b) == 0 {
-		return invalidReference, nil, NewParserError(b, "expected = after a key, but the document ends there")
+		return invalidReference, nil, NewParserError(startB[:len(startB)-len(b)], p.offsetOf(startB), "expected = after a key, but the document ends there")
 	}
 
-	b, err = expect('=', b)
+	b, err = expect('=', b, p.offsetOf(b))
 	if err != nil {
 		return invalidReference, nil, err
 	}
@@ -360,6 +352,11 @@ 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.
+	// Access the node directly in the slice to avoid the write barrier
+	// that NodeAt's nodes-pointer setup would trigger.
+	p.builder.tree.nodes[ref].Raw = p.rangeOfToken(startB[:len(startB)-len(b)], b)
+
 	return ref, b, err
 }
 
@@ -369,7 +366,7 @@ func (p *Parser) parseVal(b []byte) (reference, []byte, error) {
 	ref := invalidReference
 
 	if len(b) == 0 {
-		return ref, nil, NewParserError(b, "expected value, not eof")
+		return ref, nil, NewParserError(b, p.offsetOf(b), "expected value, not eof")
 	}
 
 	var err error
@@ -414,7 +411,7 @@ func (p *Parser) parseVal(b []byte) (reference, []byte, error) {
 		return ref, b, err
 	case 't':
 		if !scanFollowsTrue(b) {
-			return ref, nil, NewParserError(atmost(b, 4), "expected 'true'")
+			return ref, nil, NewParserError(atmost(b, 4), p.offsetOf(b), "expected 'true'")
 		}
 
 		ref = p.builder.Push(Node{
@@ -425,7 +422,7 @@ func (p *Parser) parseVal(b []byte) (reference, []byte, error) {
 		return ref, b[4:], nil
 	case 'f':
 		if !scanFollowsFalse(b) {
-			return ref, nil, NewParserError(atmost(b, 5), "expected 'false'")
+			return ref, nil, NewParserError(atmost(b, 5), p.offsetOf(b), "expected 'false'")
 		}
 
 		ref = p.builder.Push(Node{
@@ -452,7 +449,7 @@ func atmost(b []byte, n int) []byte {
 }
 
 func (p *Parser) parseLiteralString(b []byte) ([]byte, []byte, []byte, error) {
-	v, rest, err := scanLiteralString(b)
+	v, rest, err := scanLiteralString(b, p.offsetOf(b))
 	if err != nil {
 		return nil, nil, nil, err
 	}
@@ -484,7 +481,7 @@ func (p *Parser) parseInlineTable(b []byte) (reference, []byte, error) {
 		b = p.parseWhitespace(b)
 
 		if len(b) == 0 {
-			return parent, nil, NewParserError(previousB[:1], "inline table is incomplete")
+			return parent, nil, NewParserError(previousB[:1], p.offsetOf(previousB), "inline table is incomplete")
 		}
 
 		if b[0] == '}' {
@@ -492,7 +489,7 @@ func (p *Parser) parseInlineTable(b []byte) (reference, []byte, error) {
 		}
 
 		if !first {
-			b, err = expect(',', b)
+			b, err = expect(',', b, p.offsetOf(b))
 			if err != nil {
 				return parent, nil, err
 			}
@@ -516,7 +513,7 @@ func (p *Parser) parseInlineTable(b []byte) (reference, []byte, error) {
 		first = false
 	}
 
-	rest, err := expect('}', b)
+	rest, err := expect('}', b, p.offsetOf(b))
 
 	return parent, rest, err
 }
@@ -565,7 +562,7 @@ func (p *Parser) parseValArray(b []byte) (reference, []byte, error) {
 		}
 
 		if len(b) == 0 {
-			return parent, nil, NewParserError(arrayStart[:1], "array is incomplete")
+			return parent, nil, NewParserError(arrayStart[:1], p.offsetOf(arrayStart), "array is incomplete")
 		}
 
 		if b[0] == ']' {
@@ -574,7 +571,7 @@ func (p *Parser) parseValArray(b []byte) (reference, []byte, error) {
 
 		if b[0] == ',' {
 			if first {
-				return parent, nil, NewParserError(b[0:1], "array cannot start with comma")
+				return parent, nil, NewParserError(b[0:1], p.offsetOf(b), "array cannot start with comma")
 			}
 			b = b[1:]
 
@@ -586,7 +583,7 @@ func (p *Parser) parseValArray(b []byte) (reference, []byte, error) {
 				addChild(cref)
 			}
 		} else if !first {
-			return parent, nil, NewParserError(b[0:1], "array elements must be separated by commas")
+			return parent, nil, NewParserError(b[0:1], p.offsetOf(b), "array elements must be separated by commas")
 		}
 
 		// TOML allows trailing commas in arrays.
@@ -613,7 +610,7 @@ func (p *Parser) parseValArray(b []byte) (reference, []byte, error) {
 		first = false
 	}
 
-	rest, err := expect(']', b)
+	rest, err := expect(']', b, p.offsetOf(b))
 
 	return parent, rest, err
 }
@@ -668,7 +665,7 @@ func (p *Parser) parseOptionalWhitespaceCommentNewline(b []byte) (reference, []b
 }
 
 func (p *Parser) parseMultilineLiteralString(b []byte) ([]byte, []byte, []byte, error) {
-	token, rest, err := scanMultilineLiteralString(b)
+	token, rest, err := scanMultilineLiteralString(b, p.offsetOf(b))
 	if err != nil {
 		return nil, nil, nil, err
 	}
@@ -697,7 +694,7 @@ func (p *Parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, er
 	// mlb-quotes = 1*2quotation-mark
 	// mlb-unescaped = wschar / %x21 / %x23-5B / %x5D-7E / non-ascii
 	// mlb-escaped-nl = escape ws newline *( wschar / newline )
-	token, escaped, rest, err := scanMultilineBasicString(b)
+	token, escaped, rest, err := scanMultilineBasicString(b, p.offsetOf(b))
 	if err != nil {
 		return nil, nil, nil, err
 	}
@@ -714,14 +711,15 @@ func (p *Parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, er
 	// fast path
 	startIdx := i
 	endIdx := len(token) - len(`"""`)
+	tokenBase := p.offsetOf(token)
 
 	if !escaped {
 		str := token[startIdx:endIdx]
-		highlight := characters.Utf8TomlValidAlreadyEscaped(str)
-		if len(highlight) == 0 {
+		invalidIdx := characters.Utf8TomlValidAlreadyEscaped(str)
+		if invalidIdx < 0 {
 			return token, str, rest, nil
 		}
-		return nil, nil, nil, NewParserError(highlight, "invalid UTF-8")
+		return nil, nil, nil, NewParserError(str[invalidIdx:invalidIdx+1], tokenBase+startIdx+invalidIdx, "invalid UTF-8")
 	}
 
 	var builder bytes.Buffer
@@ -786,14 +784,14 @@ func (p *Parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, er
 			case 'e':
 				builder.WriteByte(0x1B)
 			case 'u':
-				x, err := hexToRune(atmost(token[i+1:], 4), 4)
+				x, err := hexToRune(atmost(token[i+1:], 4), tokenBase+i+1, 4)
 				if err != nil {
 					return nil, nil, nil, err
 				}
 				builder.WriteRune(x)
 				i += 4
 			case 'U':
-				x, err := hexToRune(atmost(token[i+1:], 8), 8)
+				x, err := hexToRune(atmost(token[i+1:], 8), tokenBase+i+1, 8)
 				if err != nil {
 					return nil, nil, nil, err
 				}
@@ -801,13 +799,13 @@ func (p *Parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, er
 				builder.WriteRune(x)
 				i += 8
 			default:
-				return nil, nil, nil, NewParserError(token[i:i+1], "invalid escaped character %#U", c)
+				return nil, nil, nil, NewParserError(token[i:i+1], tokenBase+i, "invalid escaped character %#U", c)
 			}
 			i++
 		} else {
 			size := characters.Utf8ValidNext(token[i:])
 			if size == 0 {
-				return nil, nil, nil, NewParserError(token[i:i+1], "invalid character %#U", c)
+				return nil, nil, nil, NewParserError(token[i:i+1], tokenBase+i, "invalid character %#U", c)
 			}
 			builder.Write(token[i : i+size])
 			i += size
@@ -862,12 +860,9 @@ func (p *Parser) parseKey(b []byte) (reference, []byte, error) {
 
 func (p *Parser) parseSimpleKey(b []byte) (raw, key, rest []byte, err error) {
 	if len(b) == 0 {
-		return nil, nil, nil, NewParserError(b, "expected key but found none")
+		return nil, nil, nil, NewParserError(b, p.offsetOf(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
 	switch {
 	case b[0] == '\'':
 		return p.parseLiteralString(b)
@@ -877,7 +872,7 @@ func (p *Parser) parseSimpleKey(b []byte) (raw, key, rest []byte, err error) {
 		key, rest = scanUnquotedKey(b)
 		return key, key, rest, nil
 	default:
-		return nil, nil, nil, NewParserError(b[0:1], "invalid character at start of key: %c", b[0])
+		return nil, nil, nil, NewParserError(b[0:1], p.offsetOf(b), "invalid character at start of key: %c", b[0])
 	}
 }
 
@@ -897,7 +892,7 @@ func (p *Parser) parseBasicString(b []byte) ([]byte, []byte, []byte, error) {
 	// escape-seq-char =/ %x74         ; t    tab             U+0009
 	// escape-seq-char =/ %x75 4HEXDIG ; uXXXX                U+XXXX
 	// escape-seq-char =/ %x55 8HEXDIG ; UXXXXXXXX            U+XXXXXXXX
-	token, escaped, rest, err := scanBasicString(b)
+	token, escaped, rest, err := scanBasicString(b, p.offsetOf(b))
 	if err != nil {
 		return nil, nil, nil, err
 	}
@@ -908,13 +903,15 @@ func (p *Parser) parseBasicString(b []byte) ([]byte, []byte, []byte, error) {
 	// Fast path. If there is no escape sequence, the string should just be
 	// an UTF-8 encoded string, which is the same as Go. In that case,
 	// validate the string and return a direct reference to the buffer.
+	tokenBase := p.offsetOf(token)
+
 	if !escaped {
 		str := token[startIdx:endIdx]
-		highlight := characters.Utf8TomlValidAlreadyEscaped(str)
-		if len(highlight) == 0 {
+		invalidIdx := characters.Utf8TomlValidAlreadyEscaped(str)
+		if invalidIdx < 0 {
 			return token, str, rest, nil
 		}
-		return nil, nil, nil, NewParserError(highlight, "invalid UTF-8")
+		return nil, nil, nil, NewParserError(str[invalidIdx:invalidIdx+1], tokenBase+startIdx+invalidIdx, "invalid UTF-8")
 	}
 
 	i := startIdx
@@ -945,7 +942,7 @@ func (p *Parser) parseBasicString(b []byte) ([]byte, []byte, []byte, error) {
 			case 'e':
 				builder.WriteByte(0x1B)
 			case 'u':
-				x, err := hexToRune(token[i+1:len(token)-1], 4)
+				x, err := hexToRune(token[i+1:len(token)-1], tokenBase+i+1, 4)
 				if err != nil {
 					return nil, nil, nil, err
 				}
@@ -953,7 +950,7 @@ func (p *Parser) parseBasicString(b []byte) ([]byte, []byte, []byte, error) {
 				builder.WriteRune(x)
 				i += 4
 			case 'U':
-				x, err := hexToRune(token[i+1:len(token)-1], 8)
+				x, err := hexToRune(token[i+1:len(token)-1], tokenBase+i+1, 8)
 				if err != nil {
 					return nil, nil, nil, err
 				}
@@ -961,13 +958,13 @@ func (p *Parser) parseBasicString(b []byte) ([]byte, []byte, []byte, error) {
 				builder.WriteRune(x)
 				i += 8
 			default:
-				return nil, nil, nil, NewParserError(token[i:i+1], "invalid escaped character %#U", c)
+				return nil, nil, nil, NewParserError(token[i:i+1], tokenBase+i, "invalid escaped character %#U", c)
 			}
 			i++
 		} else {
 			size := characters.Utf8ValidNext(token[i:])
 			if size == 0 {
-				return nil, nil, nil, NewParserError(token[i:i+1], "invalid character %#U", c)
+				return nil, nil, nil, NewParserError(token[i:i+1], tokenBase+i, "invalid character %#U", c)
 			}
 			builder.Write(token[i : i+size])
 			i += size
@@ -977,9 +974,9 @@ func (p *Parser) parseBasicString(b []byte) ([]byte, []byte, []byte, error) {
 	return token, builder.Bytes(), rest, nil
 }
 
-func hexToRune(b []byte, length int) (rune, error) {
+func hexToRune(b []byte, base int, length int) (rune, error) {
 	if len(b) < length {
-		return -1, NewParserError(b, "unicode point needs %d character, not %d", length, len(b))
+		return -1, NewParserError(b, base, "unicode point needs %d character, not %d", length, len(b))
 	}
 	b = b[:length]
 
@@ -994,13 +991,13 @@ func hexToRune(b []byte, length int) (rune, error) {
 		case 'A' <= c && c <= 'F':
 			d = uint32(c - 'A' + 10)
 		default:
-			return -1, NewParserError(b[i:i+1], "non-hex character")
+			return -1, NewParserError(b[i:i+1], base+i, "non-hex character")
 		}
 		r = r*16 + d
 	}
 
 	if r > unicode.MaxRune || 0xD800 <= r && r < 0xE000 {
-		return -1, NewParserError(b, "escape sequence is invalid Unicode code point")
+		return -1, NewParserError(b, base, "escape sequence is invalid Unicode code point")
 	}
 
 	return rune(r), nil
@@ -1020,7 +1017,7 @@ func (p *Parser) parseIntOrFloatOrDateTime(b []byte) (reference, []byte, error)
 	switch b[0] {
 	case 'i':
 		if !scanFollowsInf(b) {
-			return invalidReference, nil, NewParserError(atmost(b, 3), "expected 'inf'")
+			return invalidReference, nil, NewParserError(atmost(b, 3), p.offsetOf(b), "expected 'inf'")
 		}
 
 		return p.builder.Push(Node{
@@ -1030,7 +1027,7 @@ func (p *Parser) parseIntOrFloatOrDateTime(b []byte) (reference, []byte, error)
 		}), b[3:], nil
 	case 'n':
 		if !scanFollowsNan(b) {
-			return invalidReference, nil, NewParserError(atmost(b, 3), "expected 'nan'")
+			return invalidReference, nil, NewParserError(atmost(b, 3), p.offsetOf(b), "expected 'nan'")
 		}
 
 		return p.builder.Push(Node{
@@ -1189,7 +1186,7 @@ func (p *Parser) scanIntOrFloat(b []byte) (reference, []byte, error) {
 				}), b[i+3:], nil
 			}
 
-			return invalidReference, nil, NewParserError(b[i:i+1], "unexpected character 'i' while scanning for a number")
+			return invalidReference, nil, NewParserError(b[i:i+1], p.offsetOf(b)+i, "unexpected character 'i' while scanning for a number")
 		}
 
 		if c == 'n' {
@@ -1201,14 +1198,14 @@ func (p *Parser) scanIntOrFloat(b []byte) (reference, []byte, error) {
 				}), b[i+3:], nil
 			}
 
-			return invalidReference, nil, NewParserError(b[i:i+1], "unexpected character 'n' while scanning for a number")
+			return invalidReference, nil, NewParserError(b[i:i+1], p.offsetOf(b)+i, "unexpected character 'n' while scanning for a number")
 		}
 
 		break
 	}
 
 	if i == 0 {
-		return invalidReference, b, NewParserError(b, "incomplete number")
+		return invalidReference, b, NewParserError(b, p.offsetOf(b), "incomplete number")
 	}
 
 	kind := Integer
@@ -1245,13 +1242,13 @@ func isValidBinaryRune(r byte) bool {
 	return r == '0' || r == '1' || r == '_'
 }
 
-func expect(x byte, b []byte) ([]byte, error) {
+func expect(x byte, b []byte, base int) ([]byte, error) {
 	if len(b) == 0 {
-		return nil, NewParserError(b, "expected character %c but the document ended here", x)
+		return nil, NewParserError(b, base, "expected character %c but the document ended here", x)
 	}
 
 	if b[0] != x {
-		return nil, NewParserError(b[0:1], "expected character %c", x)
+		return nil, NewParserError(b[0:1], base, "expected character %c", x)
 	}
 
 	return b[1:], nil

unstable/parser_test.go

@@ -1,6 +1,7 @@
 package unstable
 
 import (
+	"errors"
 	"fmt"
 	"strconv"
 	"strings"
@@ -539,7 +540,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.]
@@ -552,12 +553,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]
@@ -567,7 +568,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]
@@ -579,7 +580,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.]
@@ -673,6 +674,96 @@ key3 = "value3"
 	assert.Equal(t, []string{"key1", "key2", "key3"}, keys)
 }
 
+func TestErrorOffsetAfterComment(t *testing.T) {
+	input := []byte("# comment\n= \"value\"")
+
+	p := Parser{}
+	p.Reset(input)
+	for p.NextExpression() {
+	}
+	err := p.Error()
+	if err == nil {
+		t.Fatal("expected an error")
+	}
+	var perr *ParserError
+	if !errors.As(err, &perr) {
+		t.Fatalf("expected ParserError, got %T", err)
+	}
+
+	if perr.Offset != 10 {
+		t.Errorf("offset: got %d, want 10", perr.Offset)
+	}
+	shape := p.Shape(Range{Offset: uint32(perr.Offset), Length: uint32(len(perr.Highlight))})
+	if shape.Start.Line != 2 || shape.Start.Column != 1 {
+		t.Errorf("position: got %d:%d, want 2:1", shape.Start.Line, shape.Start.Column)
+	}
+}
+
+func TestErrorHighlightPositions(t *testing.T) {
+	examples := []struct {
+		desc       string
+		input      string
+		wantLine   int
+		wantColumn int
+	}{
+		{
+			desc:       "invalid key start after comment",
+			input:      "# comment\n= \"value\"",
+			wantLine:   2,
+			wantColumn: 1,
+		},
+		{
+			desc:       "invalid key start on first line",
+			input:      "= \"value\"",
+			wantLine:   1,
+			wantColumn: 1,
+		},
+		{
+			desc:       "invalid key after multiple comments",
+			input:      "# comment 1\n# comment 2\n= \"value\"",
+			wantLine:   3,
+			wantColumn: 1,
+		},
+		{
+			desc:       "invalid key after valid key-value",
+			input:      "a = 1\n= \"value\"",
+			wantLine:   2,
+			wantColumn: 1,
+		},
+		{
+			desc:       "invalid key after whitespace on line",
+			input:      "a = 1\n  = \"value\"",
+			wantLine:   2,
+			wantColumn: 3,
+		},
+	}
+
+	for _, e := range examples {
+		t.Run(e.desc, func(t *testing.T) {
+			p := Parser{}
+			p.Reset([]byte(e.input))
+			for p.NextExpression() {
+			}
+			err := p.Error()
+			if err == nil {
+				t.Fatal("expected an error")
+			}
+			var perr *ParserError
+			if !errors.As(err, &perr) {
+				t.Fatalf("expected ParserError, got %T", err)
+			}
+			shape := p.Shape(Range{Offset: uint32(perr.Offset), Length: uint32(len(perr.Highlight))})
+
+			if shape.Start.Line != e.wantLine {
+				t.Errorf("line: got %d, want %d", shape.Start.Line, e.wantLine)
+			}
+			if shape.Start.Column != e.wantColumn {
+				t.Errorf("column: got %d, want %d", shape.Start.Column, e.wantColumn)
+			}
+		})
+	}
+}
+
 func ExampleParser() {
 	doc := `
 	hello = "world"

unstable/scanner.go

@@ -47,48 +47,31 @@ func isUnquotedKeyChar(r byte) bool {
 	return (r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-' || r == '_'
 }
 
-func scanLiteralString(b []byte) ([]byte, []byte, error) {
-	// literal-string = apostrophe *literal-char apostrophe
-	// apostrophe = %x27 ; ' apostrophe
-	// literal-char = %x09 / %x20-26 / %x28-7E / non-ascii
+func scanLiteralString(b []byte, base int) ([]byte, []byte, error) {
 	for i := 1; i < len(b); {
 		switch b[i] {
 		case '\'':
 			return b[:i+1], b[i+1:], nil
 		case '\n', '\r':
-			return nil, nil, NewParserError(b[i:i+1], "literal strings cannot have new lines")
+			return nil, nil, NewParserError(b[i:i+1], base+i, "literal strings cannot have new lines")
 		}
 		size := characters.Utf8ValidNext(b[i:])
 		if size == 0 {
-			return nil, nil, NewParserError(b[i:i+1], "invalid character")
+			return nil, nil, NewParserError(b[i:i+1], base+i, "invalid character")
 		}
 		i += size
 	}
 
-	return nil, nil, NewParserError(b[len(b):], "unterminated literal string")
+	return nil, nil, NewParserError(b[len(b):], base+len(b), "unterminated literal string")
 }
 
-func scanMultilineLiteralString(b []byte) ([]byte, []byte, error) {
-	// ml-literal-string = ml-literal-string-delim [ newline ] ml-literal-body
-	// ml-literal-string-delim
-	// ml-literal-string-delim = 3apostrophe
-	// ml-literal-body = *mll-content *( mll-quotes 1*mll-content ) [ mll-quotes ]
-	//
-	// mll-content = mll-char / newline
-	// mll-char = %x09 / %x20-26 / %x28-7E / non-ascii
-	// mll-quotes = 1*2apostrophe
+func scanMultilineLiteralString(b []byte, base int) ([]byte, []byte, error) {
 	for i := 3; i < len(b); {
 		switch b[i] {
 		case '\'':
 			if scanFollowsMultilineLiteralStringDelimiter(b[i:]) {
 				i += 3
 
-				// At that point we found 3 apostrophe, and i is the
-				// index of the byte after the third one. The scanner
-				// needs to be eager, because there can be an extra 2
-				// apostrophe that can be accepted at the end of the
-				// string.
-
 				if i >= len(b) || b[i] != '\'' {
 					return b[:i], b[i:], nil
 				}
@@ -100,39 +83,39 @@ func scanMultilineLiteralString(b []byte) ([]byte, []byte, error) {
 				i++
 
 				if i < len(b) && b[i] == '\'' {
-					return nil, nil, NewParserError(b[i-3:i+1], "''' not allowed in multiline literal string")
+					return nil, nil, NewParserError(b[i-3:i+1], base+i-3, "''' not allowed in multiline literal string")
 				}
 
 				return b[:i], b[i:], nil
 			}
 		case '\r':
 			if len(b) < i+2 {
-				return nil, nil, NewParserError(b[len(b):], `need a \n after \r`)
+				return nil, nil, NewParserError(b[len(b):], base+len(b), `need a \n after \r`)
 			}
 			if b[i+1] != '\n' {
-				return nil, nil, NewParserError(b[i:i+2], `need a \n after \r`)
+				return nil, nil, NewParserError(b[i:i+2], base+i, `need a \n after \r`)
 			}
-			i += 2 // skip the \n
+			i += 2
 			continue
 		}
 		size := characters.Utf8ValidNext(b[i:])
 		if size == 0 {
-			return nil, nil, NewParserError(b[i:i+1], "invalid character")
+			return nil, nil, NewParserError(b[i:i+1], base+i, "invalid character")
 		}
 		i += size
 	}
 
-	return nil, nil, NewParserError(b[len(b):], `multiline literal string not terminated by '''`)
+	return nil, nil, NewParserError(b[len(b):], base+len(b), `multiline literal string not terminated by '''`)
 }
 
-func scanWindowsNewline(b []byte) ([]byte, []byte, error) {
+func scanWindowsNewline(b []byte, base int) ([]byte, []byte, error) {
 	const lenCRLF = 2
 	if len(b) < lenCRLF {
-		return nil, nil, NewParserError(b, "windows new line expected")
+		return nil, nil, NewParserError(b, base, "windows new line expected")
 	}
 
 	if b[1] != '\n' {
-		return nil, nil, NewParserError(b, `windows new line should be \r\n`)
+		return nil, nil, NewParserError(b, base, `windows new line should be \r\n`)
 	}
 
 	return b[:lenCRLF], b[lenCRLF:], nil
@@ -151,13 +134,7 @@ func scanWhitespace(b []byte) ([]byte, []byte) {
 	return b, b[len(b):]
 }
 
-func scanComment(b []byte) ([]byte, []byte, error) {
-	// comment-start-symbol = %x23 ; #
-	// non-ascii = %x80-D7FF / %xE000-10FFFF
-	// non-eol = %x09 / %x20-7F / non-ascii
-	//
-	// comment = comment-start-symbol *non-eol
-
+func scanComment(b []byte, base int) ([]byte, []byte, error) {
 	for i := 1; i < len(b); {
 		if b[i] == '\n' {
 			return b[:i], b[i:], nil
@@ -166,11 +143,11 @@ func scanComment(b []byte) ([]byte, []byte, error) {
 			if i+1 < len(b) && b[i+1] == '\n' {
 				return b[:i+1], b[i+1:], nil
 			}
-			return nil, nil, NewParserError(b[i:i+1], "invalid character in comment")
+			return nil, nil, NewParserError(b[i:i+1], base+i, "invalid character in comment")
 		}
 		size := characters.Utf8ValidNext(b[i:])
 		if size == 0 {
-			return nil, nil, NewParserError(b[i:i+1], "invalid character in comment")
+			return nil, nil, NewParserError(b[i:i+1], base+i, "invalid character in comment")
 		}
 
 		i += size
@@ -179,12 +156,7 @@ func scanComment(b []byte) ([]byte, []byte, error) {
 	return b, b[len(b):], nil
 }
 
-func scanBasicString(b []byte) ([]byte, bool, []byte, error) {
-	// basic-string = quotation-mark *basic-char quotation-mark
-	// quotation-mark = %x22            ; "
-	// basic-char = basic-unescaped / escaped
-	// basic-unescaped = wschar / %x21 / %x23-5B / %x5D-7E / non-ascii
-	// escaped = escape escape-seq-char
+func scanBasicString(b []byte, base int) ([]byte, bool, []byte, error) {
 	escaped := false
 	i := 1
 
@@ -193,31 +165,20 @@ func scanBasicString(b []byte) ([]byte, bool, []byte, error) {
 		case '"':
 			return b[:i+1], escaped, b[i+1:], nil
 		case '\n', '\r':
-			return nil, escaped, nil, NewParserError(b[i:i+1], "basic strings cannot have new lines")
+			return nil, escaped, nil, NewParserError(b[i:i+1], base+i, "basic strings cannot have new lines")
 		case '\\':
 			if len(b) < i+2 {
-				return nil, escaped, nil, NewParserError(b[i:i+1], "need a character after \\")
+				return nil, escaped, nil, NewParserError(b[i:i+1], base+i, "need a character after \\")
 			}
 			escaped = true
 			i++ // skip the next character
 		}
 	}
 
-	return nil, escaped, nil, NewParserError(b[len(b):], `basic string not terminated by "`)
+	return nil, escaped, nil, NewParserError(b[len(b):], base+len(b), `basic string not terminated by "`)
 }
 
-func scanMultilineBasicString(b []byte) ([]byte, bool, []byte, error) {
-	// ml-basic-string = ml-basic-string-delim [ newline ] ml-basic-body
-	// ml-basic-string-delim
-	// ml-basic-string-delim = 3quotation-mark
-	// ml-basic-body = *mlb-content *( mlb-quotes 1*mlb-content ) [ mlb-quotes ]
-	//
-	// mlb-content = mlb-char / newline / mlb-escaped-nl
-	// mlb-char = mlb-unescaped / escaped
-	// mlb-quotes = 1*2quotation-mark
-	// mlb-unescaped = wschar / %x21 / %x23-5B / %x5D-7E / non-ascii
-	// mlb-escaped-nl = escape ws newline *( wschar / newline )
-
+func scanMultilineBasicString(b []byte, base int) ([]byte, bool, []byte, error) {
 	escaped := false
 	i := 3
 
@@ -227,12 +188,6 @@ func scanMultilineBasicString(b []byte) ([]byte, bool, []byte, error) {
 			if scanFollowsMultilineBasicStringDelimiter(b[i:]) {
 				i += 3
 
-				// At that point we found 3 apostrophe, and i is the
-				// index of the byte after the third one. The scanner
-				// needs to be eager, because there can be an extra 2
-				// apostrophe that can be accepted at the end of the
-				// string.
-
 				if i >= len(b) || b[i] != '"' {
 					return b[:i], escaped, b[i:], nil
 				}
@@ -244,27 +199,27 @@ func scanMultilineBasicString(b []byte) ([]byte, bool, []byte, error) {
 				i++
 
 				if i < len(b) && b[i] == '"' {
-					return nil, escaped, nil, NewParserError(b[i-3:i+1], `""" not allowed in multiline basic string`)
+					return nil, escaped, nil, NewParserError(b[i-3:i+1], base+i-3, `""" not allowed in multiline basic string`)
 				}
 
 				return b[:i], escaped, b[i:], nil
 			}
 		case '\\':
 			if len(b) < i+2 {
-				return nil, escaped, nil, NewParserError(b[len(b):], "need a character after \\")
+				return nil, escaped, nil, NewParserError(b[len(b):], base+len(b), "need a character after \\")
 			}
 			escaped = true
 			i++ // skip the next character
 		case '\r':
 			if len(b) < i+2 {
-				return nil, escaped, nil, NewParserError(b[len(b):], `need a \n after \r`)
+				return nil, escaped, nil, NewParserError(b[len(b):], base+len(b), `need a \n after \r`)
 			}
 			if b[i+1] != '\n' {
-				return nil, escaped, nil, NewParserError(b[i:i+2], `need a \n after \r`)
+				return nil, escaped, nil, NewParserError(b[i:i+2], base+i, `need a \n after \r`)
 			}
 			i++ // skip the \n
 		}
 	}
 
-	return nil, escaped, nil, NewParserError(b[len(b):], `multiline basic string not terminated by """`)
+	return nil, escaped, nil, NewParserError(b[len(b):], base+len(b), `multiline basic string not terminated by """`)
 }

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
 }