Fix leap second overflow in datetime parsing (#1015)

Normalize leap seconds (second=60) to second=59 before passing to
time.Date() to prevent year overflow. When Go's time.Date() receives
second=60, it normalizes the time by adding 1 minute, which can cause
dates like 9999-12-31 23:59:60 to overflow to year 10000 - outside
the valid TOML date range (0000-9999).

This fix ensures that timestamps with leap seconds can be successfully
round-tripped (parsed and re-serialized) without causing parsing errors.

Fixes OSS-Fuzz issue 472183443

.gitattributes

@@ -1,3 +1,4 @@
 * text=auto
 
 benchmark/benchmark.toml text eol=lf
+testdata/** text eol=lf

.github/release.yml

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

.github/workflows/cifuzz.yml

@@ -0,0 +1,26 @@
+name: CIFuzz
+on: [pull_request]
+jobs:
+  Fuzzing:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Build Fuzzers
+      id: build
+      uses: google/oss-fuzz/infra/cifuzz/actions/build_fuzzers@master
+      with:
+        oss-fuzz-project-name: 'go-toml'
+        dry-run: false
+        language: go
+    - name: Run Fuzzers
+      uses: google/oss-fuzz/infra/cifuzz/actions/run_fuzzers@master
+      with:
+        oss-fuzz-project-name: 'go-toml'
+        fuzz-seconds: 300
+        dry-run: false
+        language: go
+    - name: Upload Crash
+      uses: actions/upload-artifact@v6
+      if: failure() && steps.build.outcome == 'success'
+      with:
+        name: artifacts
+        path: ./out/artifacts

.github/workflows/codeql-analysis.yml

@@ -35,11 +35,11 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v2
+      uses: actions/checkout@v6
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
+      uses: github/codeql-action/init@v4
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -47,10 +47,10 @@ jobs:
         # Prefix the list here with "+" to use these queries and those in the config file.
         # queries: ./path/to/local/query, your-org/your-repo/queries@main
 
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v1
+      uses: github/codeql-action/autobuild@v4
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -64,4 +64,4 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      uses: github/codeql-action/analyze@v4

.github/workflows/coverage.yml

@@ -9,12 +9,12 @@ jobs:
     runs-on: "ubuntu-latest"
     name: report
     steps:
-      - uses: actions/checkout@master
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Setup go
-        uses: actions/setup-go@master
+        uses: actions/setup-go@v6
         with:
-          go-version: 1.16
+          go-version: "1.24"
       - name: Run tests with coverage
         run: ./ci.sh coverage -d "${GITHUB_BASE_REF-HEAD}"

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

@@ -0,0 +1,36 @@
+name: Go Versions Compatibility Test
+
+on:
+  workflow_dispatch:
+    inputs:
+      go_versions:
+        description: 'Go versions to test (space-separated, e.g., "1.21 1.22 1.23")'
+        required: false
+        default: ''
+        type: string
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Run Go versions compatibility test
+        run: |
+          VERSIONS="${{ github.event.inputs.go_versions }}"
+          ./test-go-versions.sh --output ./test-results $VERSIONS
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v6
+        with:
+          name: go-versions-test-results
+          path: |
+            test-results/
+          retention-days: 30

.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: release
+on:
+  push:
+    tags:
+      - "v2.*"
+  workflow_call:
+    inputs:
+      args:
+        description: "Extra arguments to pass goreleaser"
+        default: ""
+        required: false
+        type: string
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: "1.24"
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          distribution: goreleaser
+          version: '~> v2'
+          args: release ${{ inputs.args }} --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/workflow.yml

@@ -11,15 +11,22 @@ jobs:
   build:
     strategy:
       matrix:
-        os: [ 'ubuntu-latest', 'windows-latest', 'macos-latest']
-        go: [ '1.16', '1.17' ]
+        os: [ 'ubuntu-latest', 'windows-latest', 'macos-latest', 'macos-14' ]
+        go: [ '1.23', '1.24' ]
     runs-on: ${{ matrix.os }}
     name: ${{ matrix.go }}/${{ matrix.os }}
     steps:
-      - uses: actions/checkout@master
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
       - name: Setup go ${{ matrix.go }}
-        uses: actions/setup-go@master
+        uses: actions/setup-go@v6
         with:
           go-version: ${{ matrix.go }}
       - name: Run unit tests
         run: go test -race ./...
+  release-check:
+    if: ${{ github.ref != 'refs/heads/v2' }}
+    uses: ./.github/workflows/release.yml
+    with:
+      args: --snapshot

.gitignore

@@ -3,3 +3,6 @@ fuzz/
 cmd/tomll/tomll
 cmd/tomljson/tomljson
 cmd/tomltestgen/tomltestgen
+dist
+tests/
+test-results

.goreleaser.yaml

@@ -0,0 +1,127 @@
+version: 2
+before:
+  hooks:
+    - go mod tidy
+    - go fmt ./...
+    - go test ./...
+builds:
+  - id: tomll
+    main: ./cmd/tomll
+    binary: tomll
+    env:
+      - CGO_ENABLED=0
+    flags:
+      - -trimpath
+    ldflags:
+      - -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.CommitDate}}
+    mod_timestamp: '{{ .CommitTimestamp }}'
+    targets:
+      - linux_amd64
+      - linux_arm64
+      - linux_arm
+      - linux_riscv64
+      - windows_amd64
+      - windows_arm64
+      - windows_arm
+      - darwin_amd64
+      - darwin_arm64
+  - id: tomljson
+    main: ./cmd/tomljson
+    binary: tomljson
+    env:
+      - CGO_ENABLED=0
+    flags:
+      - -trimpath
+    ldflags:
+      - -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.CommitDate}}
+    mod_timestamp: '{{ .CommitTimestamp }}'
+    targets:
+      - linux_amd64
+      - linux_arm64
+      - linux_arm
+      - linux_riscv64
+      - windows_amd64
+      - windows_arm64
+      - windows_arm
+      - darwin_amd64
+      - darwin_arm64
+  - id: jsontoml
+    main: ./cmd/jsontoml
+    binary: jsontoml
+    env:
+      - CGO_ENABLED=0
+    flags:
+      - -trimpath
+    ldflags:
+      - -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.CommitDate}}
+    mod_timestamp: '{{ .CommitTimestamp }}'
+    targets:
+      - linux_amd64
+      - linux_arm64
+      - linux_riscv64
+      - linux_arm
+      - windows_amd64
+      - windows_arm64
+      - windows_arm
+      - darwin_amd64
+      - darwin_arm64
+universal_binaries:
+  - id: tomll
+    replace: true
+    name_template: tomll
+  - id: tomljson
+    replace: true
+    name_template: tomljson
+  - id: jsontoml
+    replace: true
+    name_template: jsontoml
+archives:
+- id: jsontoml
+  format: tar.xz
+  builds:
+    - jsontoml
+  files:
+  - none*
+  name_template: "{{ .Binary }}_{{.Version}}_{{ .Os }}_{{ .Arch }}"
+- id: tomljson
+  format: tar.xz
+  builds:
+    - tomljson
+  files:
+  - none*
+  name_template: "{{ .Binary }}_{{.Version}}_{{ .Os }}_{{ .Arch }}"
+- id: tomll
+  format: tar.xz
+  builds:
+    - tomll
+  files:
+  - none*
+  name_template: "{{ .Binary }}_{{.Version}}_{{ .Os }}_{{ .Arch }}"
+dockers:
+  - id: tools
+    goos: linux
+    goarch: amd64
+    ids:
+      - jsontoml
+      - tomljson
+      - tomll
+    image_templates:
+      - "ghcr.io/pelletier/go-toml:latest"
+      - "ghcr.io/pelletier/go-toml:{{ .Tag }}"
+      - "ghcr.io/pelletier/go-toml:v{{ .Major }}"
+    skip_push: false
+checksum:
+  name_template: 'sha256sums.txt'
+snapshot:
+  version_template: "{{ incpatch .Version }}-next"
+release:
+  github:
+    owner: pelletier
+    name: go-toml
+  draft: true
+  prerelease: auto
+  mode: replace
+changelog:
+  use: github-native
+announce:
+  skip: true

CONTRIBUTING.md

@@ -33,7 +33,7 @@ The documentation is present in the [README][readme] and thorough the source
 code. On release, it gets updated on [pkg.go.dev][pkg.go.dev]. To make a change
 to the documentation, create a pull request with your proposed changes. For
 simple changes like that, the easiest way to go is probably the "Fork this
-project and edit the file" button on Github, displayed at the top right of the
+project and edit the file" button on GitHub, displayed at the top right of the
 file. Unless it's a trivial change (for example a typo), provide a little bit of
 context in your pull request description or commit message.
 
@@ -92,6 +92,48 @@ However, given GitHub's new policy to _not_ run Actions on pull requests until a
 maintainer clicks on button, it is highly recommended that you run them locally
 as you make changes.
 
+### Test across Go versions
+
+The repository includes tooling to test go-toml across multiple Go versions
+(1.11 through 1.25) both locally and in GitHub Actions.
+
+#### Local testing with Docker
+
+Prerequisites: Docker installed and running, Bash shell, `rsync` command.
+
+```bash
+# Test all Go versions in parallel (default)
+./test-go-versions.sh
+
+# Test specific versions
+./test-go-versions.sh 1.21 1.22 1.23
+
+# Test sequentially (slower but uses less resources)
+./test-go-versions.sh --sequential
+
+# Verbose output with custom results directory
+./test-go-versions.sh --verbose --output ./my-results 1.24 1.25
+
+# Show all options
+./test-go-versions.sh --help
+```
+
+The script creates Docker containers for each Go version and runs the full test
+suite. Results are saved to a `test-results/` directory with individual logs and
+a comprehensive summary report.
+
+The script only exits with a non-zero status code if either of the two most
+recent Go versions fail.
+
+#### GitHub Actions testing (maintainers)
+
+1. Go to the **Actions** tab in the GitHub repository
+2. Select **"Go Versions Compatibility Test"** from the workflow list
+3. Click **"Run workflow"**
+4. Optionally customize:
+   - **Go versions**: Space-separated list (e.g., `1.21 1.22 1.23`)
+   - **Execution mode**: Parallel (faster) or sequential (more stable)
+
 ### Check coverage
 
 We use `go tool cover` to compute test coverage. Most code editors have a way to
@@ -111,7 +153,7 @@ code lowers the coverage.
 
 Go-toml aims to stay efficient. We rely on a set of scenarios executed with Go's
 builtin benchmark systems. Because of their noisy nature, containers provided by
-Github Actions cannot be reliably used for benchmarking. As a result, you are
+GitHub Actions cannot be reliably used for benchmarking. As a result, you are
 responsible for checking that your changes do not incur a performance penalty.
 You can run their following to execute benchmarks:
 
@@ -155,6 +197,8 @@ Checklist:
 - Does not introduce backward-incompatible changes (unless discussed).
 - Has relevant doc changes.
 - Benchstat does not show performance regression.
+- Pull request is [labeled appropriately][pr-labels].
+- Title will be understandable in the changelog.
 
 1. Merge using "squash and merge".
 2. Make sure to edit the commit message to keep all the useful information
@@ -163,13 +207,22 @@ Checklist:
 
 ### New release
 
-1. Go to [releases][releases]. Click on "X commits to master since this
-   release".
-2. Make note of all the changes. Look for backward incompatible changes,
-   new features, and bug fixes.
-3. Pick the new version using the above and semver.
-4. Create a [new release][new-release].
-5. Follow the same format as [1.1.0][release-110].
+1. Decide on the next version number. Use semver. Review commits since last
+   version to assess.
+2. Tag release. For example:
+   ```
+   git checkout v2
+   git pull
+   git tag v2.2.0
+   git push --tags
+   ```
+3. CI automatically builds a draft GitHub release. Review it and edit as
+   necessary. Look for "Other changes". That would indicate a pull request not
+   labeled properly. Tweak labels and pull request titles until changelog looks
+   good for users.
+4. Check "create discussion" box, in the "Releases" category.
+5. If new version is an alpha or beta only, check pre-release box.
+
 
 [issues-tracker]: https://github.com/pelletier/go-toml/issues
 [bug-report]: https://github.com/pelletier/go-toml/issues/new?template=bug_report.md
@@ -177,6 +230,6 @@ Checklist:
 [readme]: ./README.md
 [fork]: https://help.github.com/articles/fork-a-repo
 [pull-request]: https://help.github.com/en/articles/creating-a-pull-request
-[releases]: https://github.com/pelletier/go-toml/releases
 [new-release]: https://github.com/pelletier/go-toml/releases/new
-[release-110]: https://github.com/pelletier/go-toml/releases/tag/v1.1.0
+[gh]: https://github.com/cli/cli
+[pr-labels]: https://github.com/pelletier/go-toml/blob/v2/.github/release.yml

Dockerfile

@@ -0,0 +1,5 @@
+FROM scratch
+ENV PATH "$PATH:/bin"
+COPY tomll /bin/tomll
+COPY tomljson /bin/tomljson
+COPY jsontoml /bin/jsontoml

LICENSE

@@ -1,6 +1,7 @@
 The MIT License (MIT)
 
-Copyright (c) 2013 - 2021 Thomas Pelletier, Eric Anderton
+go-toml v2
+Copyright (c) 2021 - 2023 Thomas Pelletier
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -4,24 +4,14 @@ Go library for the [TOML](https://toml.io/en/) format.
 
 This library supports [TOML v1.0.0](https://toml.io/en/v1.0.0).
 
-## Development status
-
-This is the upcoming major version of go-toml. It is currently in active
-development. As of release v2.0.0-beta.1, the library has reached feature parity
-with v1, and fixes a lot known bugs and performance issues along the way.
-
-If you do not need the advanced document editing features of v1, you are
-encouraged to try out this version.
-
-[👉 Roadmap for v2](https://github.com/pelletier/go-toml/discussions/506)
-
 [🐞 Bug Reports](https://github.com/pelletier/go-toml/issues)
 
 [💬 Anything else](https://github.com/pelletier/go-toml/discussions)
 
 ## Documentation
 
-Full API, examples, and implementation notes are available in the Go documentation.
+Full API, examples, and implementation notes are available in the Go
+documentation.
 
 [![Go Reference](https://pkg.go.dev/badge/github.com/pelletier/go-toml/v2.svg)](https://pkg.go.dev/github.com/pelletier/go-toml/v2)
 
@@ -48,22 +38,22 @@ operations should not be shockingly slow. See [benchmarks](#benchmarks).
 ### Strict mode
 
 `Decoder` can be set to "strict mode", which makes it error when some parts of
-the TOML document was not prevent in the target structure. This is a great way
+the TOML document was not present in the target structure. This is a great way
 to check for typos. [See example in the documentation][strict].
 
-[strict]: https://pkg.go.dev/github.com/pelletier/go-toml/v2#example-Decoder.SetStrict
+[strict]: https://pkg.go.dev/github.com/pelletier/go-toml/v2#example-Decoder.DisallowUnknownFields
 
 ### Contextualized errors
 
-When decoding errors occur, go-toml returns [`DecodeError`][decode-err]), which
-contains a human readable contextualized version of the error. For example:
+When most decoding errors occur, go-toml returns [`DecodeError`][decode-err],
+which contains a human readable contextualized version of the error. For
+example:
 
 ```
-2| key1 = "value1"
-3| key2 = "missing2"
- | ~~~~ missing field
-4| key3 = "missing3"
-5| key4 = "value4"
+1| [server]
+2| path = 100
+ |        ~~~ cannot decode TOML integer into struct field toml_test.Server.Path of type string
+3| port = 50
 ```
 
 [decode-err]: https://pkg.go.dev/github.com/pelletier/go-toml/v2#DecodeError
@@ -82,22 +72,46 @@ representation.
 [tlt]: https://pkg.go.dev/github.com/pelletier/go-toml/v2#LocalTime
 [tldt]: https://pkg.go.dev/github.com/pelletier/go-toml/v2#LocalDateTime
 
+### Commented config
+
+Since TOML is often used for configuration files, go-toml can emit documents
+annotated with [comments and commented-out values][comments-example]. For
+example, it can generate the following file:
+
+```toml
+# Host IP to connect to.
+host = '127.0.0.1'
+# Port of the remote server.
+port = 4242
+
+# Encryption parameters (optional)
+# [TLS]
+# cipher = 'AEAD-AES128-GCM-SHA256'
+# version = 'TLS 1.3'
+```
+
+[comments-example]: https://pkg.go.dev/github.com/pelletier/go-toml/v2#example-Marshal-Commented
+
 ## Getting started
 
 Given the following struct, let's see how to read it and write it as TOML:
 
 ```go
 type MyConfig struct {
-      Version int
-      Name    string
-      Tags    []string
+	Version int
+	Name    string
+	Tags    []string
 }
 ```
 
 ### Unmarshaling
 
 [`Unmarshal`][unmarshal] reads a TOML document and fills a Go structure with its
-content. For example:
+content. 
+
+Note that the struct variable names are _capitalized_, while the variables in the toml document are _lowercase_.
+
+For example:
 
 ```go
 doc := `
@@ -109,7 +123,7 @@ tags = ["go", "toml"]
 var cfg MyConfig
 err := toml.Unmarshal([]byte(doc), &cfg)
 if err != nil {
-      panic(err)
+	panic(err)
 }
 fmt.Println("version:", cfg.Version)
 fmt.Println("name:", cfg.Name)
@@ -123,6 +137,62 @@ fmt.Println("tags:", cfg.Tags)
 
 [unmarshal]: https://pkg.go.dev/github.com/pelletier/go-toml/v2#Unmarshal
 
+
+Here is an example using tables with some simple nesting:
+
+```go
+doc := `
+age = 45
+fruits = ["apple", "pear"]
+
+# these are very important!
+[my-variables]
+first = 1
+second = 0.2
+third = "abc"
+
+# this is not so important.
+[my-variables.b]
+bfirst = 123
+`
+
+var Document struct {
+	Age int
+	Fruits []string
+
+	Myvariables struct {
+		First  int
+		Second float64
+		Third  string
+
+		B struct {
+			Bfirst int
+		}
+	} `toml:"my-variables"`
+}
+
+err := toml.Unmarshal([]byte(doc), &Document)
+if err != nil {
+	panic(err)
+}
+
+fmt.Println("age:", Document.Age)
+fmt.Println("fruits:", Document.Fruits)
+fmt.Println("my-variables.first:", Document.Myvariables.First)
+fmt.Println("my-variables.second:", Document.Myvariables.Second)
+fmt.Println("my-variables.third:", Document.Myvariables.Third)
+fmt.Println("my-variables.B.Bfirst:", Document.Myvariables.B.Bfirst)
+
+// Output:
+// age: 45
+// fruits: [apple pear]
+// my-variables.first: 1
+// my-variables.second: 0.2
+// my-variables.third: abc
+// my-variables.B.Bfirst: 123
+```
+
+
 ### Marshaling
 
 [`Marshal`][marshal] is the opposite of Unmarshal: it represents a Go structure
@@ -130,14 +200,14 @@ as a TOML document:
 
 ```go
 cfg := MyConfig{
-      Version: 2,
-      Name:    "go-toml",
-      Tags:    []string{"go", "toml"},
+	Version: 2,
+	Name:    "go-toml",
+	Tags:    []string{"go", "toml"},
 }
 
 b, err := toml.Marshal(cfg)
 if err != nil {
-      panic(err)
+	panic(err)
 }
 fmt.Println(string(b))
 
@@ -149,22 +219,33 @@ fmt.Println(string(b))
 
 [marshal]: https://pkg.go.dev/github.com/pelletier/go-toml/v2#Marshal
 
+## Unstable API
+
+This API does not yet follow the backward compatibility guarantees of this
+library. They provide early access to features that may have rough edges or an
+API subject to change.
+
+### Parser
+
+Parser is the unstable API that allows iterative parsing of a TOML document at
+the AST level. See https://pkg.go.dev/github.com/pelletier/go-toml/v2/unstable.
+
 ## Benchmarks
 
 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>1.9x</td></tr>
-        <tr><td>Marshal/ReferenceFile/map-2</td><td>1.7x</td><td>1.9x</td></tr>
-        <tr><td>Marshal/ReferenceFile/struct-2</td><td>2.4x</td><td>2.6x</td></tr>
-        <tr><td>Unmarshal/HugoFrontMatter-2</td><td>2.9x</td><td>2.5x</td></tr>
-        <tr><td>Unmarshal/ReferenceFile/map-2</td><td>2.7x</td><td>2.6x</td></tr>
-        <tr><td>Unmarshal/ReferenceFile/struct-2</td><td>4.8x</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>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>
 </table>
 <details><summary>See more</summary>
 <p>The table above has the results of the most common use-cases. The table below
@@ -172,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.7x</td><td>2.1x</td></tr>
-        <tr><td>Marshal/SimpleDocument/struct-2</td><td>2.5x</td><td>2.8x</td></tr>
-        <tr><td>Unmarshal/SimpleDocument/map-2</td><td>4.1x</td><td>3.1x</td></tr>
-        <tr><td>Unmarshal/SimpleDocument/struct-2</td><td>6.4x</td><td>4.3x</td></tr>
-        <tr><td>UnmarshalDataset/example-2</td><td>3.4x</td><td>3.2x</td></tr>
-        <tr><td>UnmarshalDataset/code-2</td><td>2.2x</td><td>2.5x</td></tr>
-        <tr><td>UnmarshalDataset/twitter-2</td><td>2.8x</td><td>2.7x</td></tr>
-        <tr><td>UnmarshalDataset/citm_catalog-2</td><td>2.2x</td><td>2.0x</td></tr>
-        <tr><td>UnmarshalDataset/canada-2</td><td>1.8x</td><td>1.4x</td></tr>
-        <tr><td>UnmarshalDataset/config-2</td><td>4.4x</td><td>2.9x</td></tr>
-        <tr><td>[Geo mean]</td><td>2.8x</td><td>2.6x</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>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>
 </table>
 <p>This table can be generated with <code>./ci.sh benchmark -a -html</code>.</p>
 </details>
@@ -206,6 +287,44 @@ In case of trouble: [Go Modules FAQ][mod-faq].
 
 [mod-faq]: https://github.com/golang/go/wiki/Modules#why-does-installing-a-tool-via-go-get-fail-with-error-cannot-find-main-module
 
+## Tools
+
+Go-toml provides three handy command line tools:
+
+ * `tomljson`: Reads a TOML file and outputs its JSON representation.
+
+	```
+	$ go install github.com/pelletier/go-toml/v2/cmd/tomljson@latest
+	$ tomljson --help
+	```
+
+ * `jsontoml`: Reads a JSON file and outputs a TOML representation.
+
+	```
+	$ go install github.com/pelletier/go-toml/v2/cmd/jsontoml@latest
+	$ jsontoml --help
+	```
+
+ * `tomll`: Lints and reformats a TOML file.
+
+	```
+	$ go install github.com/pelletier/go-toml/v2/cmd/tomll@latest
+	$ tomll --help
+	```
+
+### Docker image
+
+Those tools are also available as a [Docker image][docker]. For example, to use
+`tomljson`:
+
+```
+docker run -i ghcr.io/pelletier/go-toml:v2 tomljson < example.toml
+```
+
+Multiple versions are available on [ghcr.io][docker].
+
+[docker]: https://github.com/pelletier/go-toml/pkgs/container/go-toml
+
 ## Migrating from v1
 
 This section describes the differences between v1 and v2, with some pointers on
@@ -234,16 +353,16 @@ element in the interface to decode the object. For example:
 
 ```go
 type inner struct {
-  B interface{}
+	B interface{}
 }
 type doc struct {
-  A interface{}
+	A interface{}
 }
 
 d := doc{
-  A: inner{
-    B: "Before",
-  },
+	A: inner{
+		B: "Before",
+	},
 }
 
 data := `
@@ -282,7 +401,7 @@ contained in the doc is superior to the capacity of the array. For example:
 
 ```go
 type doc struct {
-  A [2]string
+	A [2]string
 }
 d := doc{}
 err := toml.Unmarshal([]byte(`A = ["one", "two", "many"]`), &d)
@@ -324,6 +443,29 @@ The recommended replacement is pre-filling the struct before unmarshaling.
 
 [go-defaults]: https://github.com/mcuadros/go-defaults
 
+#### `toml.Tree` replacement
+
+This structure was the initial attempt at providing a document model for
+go-toml. It allows manipulating the structure of any document, encoding and
+decoding from their TOML representation. While a more robust feature was
+initially planned in go-toml v2, this has been ultimately [removed from
+scope][nodoc] of this library, with no plan to add it back at the moment. The
+closest equivalent at the moment would be to unmarshal into an `interface{}` and
+use type assertions and/or reflection to manipulate the arbitrary
+structure. However this would fall short of providing all of the TOML features
+such as adding comments and be specific about whitespace.
+
+
+#### `toml.Position` are not retrievable anymore
+
+The API for retrieving the position (line, column) of a specific TOML element do
+not exist anymore. This was done to minimize the amount of concepts introduced
+by the library (query path), and avoid the performance hit related to storing
+positions in the absence of a document model, for a feature that seemed to have
+little use. Errors however have gained more detailed position
+information. Position retrieval seems better fitted for a document model, which
+has been [removed from the scope][nodoc] of go-toml v2 at the moment.
+
 ### Encoding / Marshal
 
 #### Default struct fields order
@@ -359,7 +501,8 @@ fmt.Println("v2:\n" + string(b))
 ```
 
 There is no way to make v2 encoder behave like v1. A workaround could be to
-manually sort the fields alphabetically in the struct definition.
+manually sort the fields alphabetically in the struct definition, or generate
+struct types using `reflect.StructOf`.
 
 #### No indentation by default
 
@@ -407,7 +550,9 @@ fmt.Println("v2 Encoder:\n" + string(buf.Bytes()))
 
 V1 always uses double quotes (`"`) around strings and keys that cannot be
 represented bare (unquoted). V2 uses single quotes instead by default (`'`),
-unless a character cannot be represented, then falls back to double quotes.
+unless a character cannot be represented, then falls back to double quotes. As a
+result of this change, `Encoder.QuoteMapKeys` has been removed, as it is not
+useful anymore.
 
 There is no way to make v2 encoder behave like v1.
 
@@ -422,6 +567,70 @@ There is no way to make v2 encoder behave like v1.
 
 [tm]: https://golang.org/pkg/encoding/#TextMarshaler
 
+#### `Encoder.CompactComments` has been removed
+
+Emitting compact comments is now the default behavior of go-toml. This option
+is not necessary anymore.
+
+#### Struct tags have been merged
+
+V1 used to provide multiple struct tags: `comment`, `commented`, `multiline`,
+`toml`, and `omitempty`. To behave more like the standard library, v2 has merged
+`toml`, `multiline`, `commented`, and `omitempty`. For example:
+
+```go
+type doc struct {
+	// v1
+	F string `toml:"field" multiline:"true" omitempty:"true" commented:"true"`
+	// v2
+	F string `toml:"field,multiline,omitempty,commented"`
+}
+```
+
+Has a result, the `Encoder.SetTag*` methods have been removed, as there is just
+one tag now.
+
+#### `Encoder.ArraysWithOneElementPerLine` has been renamed
+
+The new name is `Encoder.SetArraysMultiline`. The behavior should be the same.
+
+#### `Encoder.Indentation` has been renamed
+
+The new name is `Encoder.SetIndentSymbol`. The behavior should be the same.
+
+
+#### Embedded structs behave like stdlib
+
+V1 defaults to merging embedded struct fields into the embedding struct. This
+behavior was unexpected because it does not follow the standard library. To
+avoid breaking backward compatibility, the `Encoder.PromoteAnonymous` method was
+added to make the encoder behave correctly. Given backward compatibility is not
+a problem anymore, v2 does the right thing by default: it follows the behavior
+of `encoding/json`. `Encoder.PromoteAnonymous` has been removed.
+
+[nodoc]: https://github.com/pelletier/go-toml/discussions/506#discussioncomment-1526038
+
+### `query`
+
+go-toml v1 provided the [`go-toml/query`][query] package. It allowed to run
+JSONPath-style queries on TOML files. This feature is not available in v2. For a
+replacement, check out [dasel][dasel].
+
+This package has been removed because it was essentially not supported anymore
+(last commit May 2020), increased the complexity of the code base, and more
+complete solutions exist out there.
+
+[query]: https://github.com/pelletier/go-toml/tree/f99d6bbca119636aeafcf351ee52b3d202782627/query
+[dasel]: https://github.com/TomWright/dasel
+
+## Versioning
+
+Expect for parts explicitly marked otherwise, go-toml follows [Semantic
+Versioning](https://semver.org). The supported version of
+[TOML](https://github.com/toml-lang/toml) is indicated at the beginning of this
+document. The last two major versions of Go are supported (see [Go Release
+Policy](https://golang.org/doc/devel/release.html#policy)).
+
 ## License
 
 The MIT License (MIT). Read [LICENSE](LICENSE).

SECURITY.md

@@ -2,9 +2,6 @@
 
 ## Supported Versions
 
-Use this section to tell people about which versions of your project are
-currently being supported with security updates.
-
 | Version    | Supported          |
 | ---------- | ------------------ |
 | Latest 2.x | :white_check_mark: |

benchmark/bench_datasets_test.go

@@ -3,13 +3,13 @@ package benchmark_test
 import (
 	"compress/gzip"
 	"encoding/json"
-	"io/ioutil"
+	"io"
 	"os"
 	"path/filepath"
 	"testing"
 
 	"github.com/pelletier/go-toml/v2"
-	"github.com/stretchr/testify/require"
+	"github.com/pelletier/go-toml/v2/internal/assert"
 )
 
 var bench_inputs = []struct {
@@ -35,11 +35,11 @@ func TestUnmarshalDatasetCode(t *testing.T) {
 			buf := fixture(t, tc.name)
 
 			var v interface{}
-			require.NoError(t, toml.Unmarshal(buf, &v))
+			assert.NoError(t, toml.Unmarshal(buf, &v))
 
 			b, err := json.Marshal(v)
-			require.NoError(t, err)
-			require.Equal(t, len(b), tc.jsonLen)
+			assert.NoError(t, err)
+			assert.Equal(t, len(b), tc.jsonLen)
 		})
 	}
 }
@@ -53,7 +53,7 @@ func BenchmarkUnmarshalDataset(b *testing.B) {
 			b.ResetTimer()
 			for i := 0; i < b.N; i++ {
 				var v interface{}
-				require.NoError(b, toml.Unmarshal(buf, &v))
+				assert.NoError(b, toml.Unmarshal(buf, &v))
 			}
 		})
 	}
@@ -68,13 +68,13 @@ func fixture(tb testing.TB, path string) []byte {
 	if os.IsNotExist(err) {
 		tb.Skip("benchmark fixture not found:", file)
 	}
-	require.NoError(tb, err)
+	assert.NoError(tb, err)
 	defer f.Close()
 
 	gz, err := gzip.NewReader(f)
-	require.NoError(tb, err)
+	assert.NoError(tb, err)
 
-	buf, err := ioutil.ReadAll(gz)
-	require.NoError(tb, err)
+	buf, err := io.ReadAll(gz)
+	assert.NoError(tb, err)
 	return buf
 }

benchmark/benchmark_test.go

@@ -2,12 +2,12 @@ package benchmark_test
 
 import (
 	"bytes"
-	"io/ioutil"
+	"os"
 	"testing"
 	"time"
 
 	"github.com/pelletier/go-toml/v2"
-	"github.com/stretchr/testify/require"
+	"github.com/pelletier/go-toml/v2/internal/assert"
 )
 
 func TestUnmarshalSimple(t *testing.T) {
@@ -59,7 +59,7 @@ func BenchmarkUnmarshal(b *testing.B) {
 	})
 
 	b.Run("ReferenceFile", func(b *testing.B) {
-		bytes, err := ioutil.ReadFile("benchmark.toml")
+		bytes, err := os.ReadFile("benchmark.toml")
 		if err != nil {
 			b.Fatal(err)
 		}
@@ -165,7 +165,7 @@ func BenchmarkMarshal(b *testing.B) {
 	})
 
 	b.Run("ReferenceFile", func(b *testing.B) {
-		bytes, err := ioutil.ReadFile("benchmark.toml")
+		bytes, err := os.ReadFile("benchmark.toml")
 		if err != nil {
 			b.Fatal(err)
 		}
@@ -344,11 +344,11 @@ type benchmarkDoc struct {
 }
 
 func TestUnmarshalReferenceFile(t *testing.T) {
-	bytes, err := ioutil.ReadFile("benchmark.toml")
-	require.NoError(t, err)
+	bytes, err := os.ReadFile("benchmark.toml")
+	assert.NoError(t, err)
 	d := benchmarkDoc{}
 	err = toml.Unmarshal(bytes, &d)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 
 	expected := benchmarkDoc{
 		Table: struct {
@@ -627,7 +627,7 @@ trimmed in raw strings.
 		},
 	}
 
-	require.Equal(t, expected, d)
+	assert.Equal(t, expected, d)
 }
 
 var hugoFrontMatterbytes = []byte(`

ci.sh

@@ -76,8 +76,10 @@ cover() {
     fi
 
     pushd "$dir"
-    go test -covermode=atomic -coverprofile=coverage.out ./...
+    go test -covermode=atomic  -coverpkg=./... -coverprofile=coverage.out.tmp ./...
+    grep -Ev '(fuzz|testsuite|tomltestgen|gotoml-test-decoder|gotoml-test-encoder)' coverage.out.tmp > coverage.out
     go tool cover -func=coverage.out
+    echo "Coverage profile for ${branch}: ${dir}/coverage.out" >&2
     popd
 
     if [ "${branch}" != "HEAD" ]; then
@@ -103,16 +105,23 @@ coverage() {
 
 	    echo ""
 
-	    target_pct="$(cat ${target_out} |sed -E 's/.*total.*\t([0-9.]+)%/\1/;t;d')"
-	    head_pct="$(cat ${head_out} |sed -E 's/.*total.*\t([0-9.]+)%/\1/;t;d')"
+	    target_pct="$(tail -n2 ${target_out} | head -n1 | sed -E 's/.*total.*\t([0-9.]+)%.*/\1/')"
+	    head_pct="$(tail -n2 ${head_out} | head -n1 | sed -E 's/.*total.*\t([0-9.]+)%/\1/')"
 	    echo "Results: ${target} ${target_pct}% HEAD ${head_pct}%"
 
 	    delta_pct=$(echo "$head_pct - $target_pct" | bc -l)
 	    echo "Delta: ${delta_pct}"
 
 	    if [[ $delta_pct = \-* ]]; then
-		echo "Regression!";
-		return 1
+		    echo "Regression!";
+
+            target_diff="${output_dir}/target.diff.txt"
+            head_diff="${output_dir}/head.diff.txt"
+            cat "${target_out}" | grep -E '^github.com/pelletier/go-toml' | tr -s "\t " | cut -f 2,3 | sort > "${target_diff}"
+            cat "${head_out}" | grep -E '^github.com/pelletier/go-toml' | tr -s "\t " | cut -f 2,3 | sort > "${head_diff}"
+
+            diff --side-by-side --suppress-common-lines "${target_diff}" "${head_diff}"
+		    return 1
 	    fi
 	    return 0
 	    ;;
@@ -143,7 +152,7 @@ bench() {
     fi
 
     export GOMAXPROCS=2
-    nice -n -19 taskset --cpu-list 0,1 go test '-bench=^Benchmark(Un)?[mM]arshal' -count=5 -run=Nothing ./... | tee "${out}"
+    go test '-bench=^Benchmark(Un)?[mM]arshal' -count=10 -run=Nothing ./... | tee "${out}"
     popd
 
     if [ "${branch}" != "HEAD" ]; then
@@ -152,10 +161,12 @@ bench() {
 }
 
 fmktemp() {
-    if mktemp --version|grep GNU >/dev/null; then
-        mktemp --suffix=-$1;
+    if mktemp --version &> /dev/null; then
+	# GNU
+        mktemp --suffix=-$1
     else
-        mktemp -t $1;
+	# BSD
+	mktemp -t $1
     fi
 }
 
@@ -175,12 +186,14 @@ with open(sys.argv[1]) as f:
             lines.append(line.split(','))
 
 results = []
-for line in reversed(lines[1:]):
+for line in reversed(lines[2:]):
+    if len(line) < 8 or line[0] == "":
+        continue
     v2 = float(line[1])
     results.append([
         line[0].replace("-32", ""),
         "%.1fx" % (float(line[3])/v2),  # v1
-        "%.1fx" % (float(line[5])/v2),  # bs
+        "%.1fx" % (float(line[7])/v2),  # bs
     ])
 # move geomean to the end
 results.append(results[0])
@@ -251,10 +264,10 @@ benchmark() {
 
         if [ "$1" = "-html" ]; then
             tmpcsv=`fmktemp csv`
-            benchstat -csv -geomean go-toml-v2.txt go-toml-v1.txt bs-toml.txt > $tmpcsv
+            benchstat -format csv go-toml-v2.txt go-toml-v1.txt bs-toml.txt > $tmpcsv
             benchstathtml $tmpcsv
         else
-            benchstat -geomean go-toml-v2.txt go-toml-v1.txt bs-toml.txt
+            benchstat go-toml-v2.txt go-toml-v1.txt bs-toml.txt
         fi
 
         rm -f go-toml-v2.txt go-toml-v1.txt bs-toml.txt

cmd/gotoml-test-decoder/main.go

@@ -6,7 +6,7 @@ import (
 	"os"
 	"path"
 
-	"github.com/pelletier/go-toml/v2/testsuite"
+	"github.com/pelletier/go-toml/v2/internal/testsuite"
 )
 
 func main() {

cmd/gotoml-test-encoder/gotoml-test-encoder.go

@@ -0,0 +1,30 @@
+package main
+
+import (
+	"flag"
+	"log"
+	"os"
+	"path"
+
+	"github.com/pelletier/go-toml/v2/internal/testsuite"
+)
+
+func main() {
+	log.SetFlags(0)
+	flag.Usage = usage
+	flag.Parse()
+	if flag.NArg() != 0 {
+		flag.Usage()
+	}
+
+	err := testsuite.EncodeStdin()
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+
+func usage() {
+	log.Printf("Usage: %s < toml-file\n", path.Base(os.Args[0]))
+	flag.PrintDefaults()
+	os.Exit(1)
+}

cmd/jsontoml/main.go

@@ -0,0 +1,66 @@
+// Package jsontoml is a program that converts JSON to TOML.
+//
+// # Usage
+//
+// Reading from stdin:
+//
+//	cat file.json | jsontoml > file.toml
+//
+// Reading from a file:
+//
+//	jsontoml file.json > file.toml
+//
+// # Installation
+//
+// Using Go:
+//
+//	go install github.com/pelletier/go-toml/v2/cmd/jsontoml@latest
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"io"
+
+	"github.com/pelletier/go-toml/v2"
+	"github.com/pelletier/go-toml/v2/internal/cli"
+)
+
+const usage = `jsontoml can be used in two ways:
+Reading from stdin:
+  cat file.json | jsontoml > file.toml
+
+Reading from a file:
+  jsontoml file.json > file.toml
+`
+
+var useJsonNumber bool
+
+func main() {
+	flag.BoolVar(&useJsonNumber, "use-json-number", false, "unmarshal numbers into `json.Number` type instead of as `float64`")
+
+	p := cli.Program{
+		Usage: usage,
+		Fn:    convert,
+	}
+	p.Execute()
+}
+
+func convert(r io.Reader, w io.Writer) error {
+	var v interface{}
+
+	d := json.NewDecoder(r)
+	e := toml.NewEncoder(w)
+
+	if useJsonNumber {
+		d.UseNumber()
+		e.SetMarshalJsonNumbers(true)
+	}
+
+	err := d.Decode(&v)
+	if err != nil {
+		return err
+	}
+
+	return e.Encode(v)
+}

cmd/jsontoml/main_test.go

@@ -0,0 +1,62 @@
+package main
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"github.com/pelletier/go-toml/v2/internal/assert"
+)
+
+func TestConvert(t *testing.T) {
+	examples := []struct {
+		name          string
+		input         string
+		expected      string
+		errors        bool
+		useJsonNumber bool
+	}{
+		{
+			name: "valid json",
+			input: `
+{
+  "mytoml": {
+    "a": 42
+  }
+}`,
+			expected: `[mytoml]
+a = 42.0
+`,
+		},
+		{
+			name:          "use json number",
+			useJsonNumber: true,
+			input: `
+{
+  "mytoml": {
+    "a": 42
+  }
+}`,
+			expected: `[mytoml]
+a = 42
+`,
+		},
+		{
+			name:   "invalid json",
+			input:  `{ foo`,
+			errors: true,
+		},
+	}
+
+	for _, e := range examples {
+		b := new(bytes.Buffer)
+		useJsonNumber = e.useJsonNumber
+		err := convert(strings.NewReader(e.input), b)
+		if e.errors {
+			assert.Error(t, err)
+		} else {
+			assert.NoError(t, err)
+			assert.Equal(t, e.expected, b.String())
+		}
+	}
+}

cmd/tomljson/main.go

@@ -0,0 +1,63 @@
+// Package tomljson is a program that converts TOML to JSON.
+//
+// # Usage
+//
+// Reading from stdin:
+//
+//	cat file.toml | tomljson > file.json
+//
+// Reading from a file:
+//
+//	tomljson file.toml > file.json
+//
+// # Installation
+//
+// Using Go:
+//
+//	go install github.com/pelletier/go-toml/v2/cmd/tomljson@latest
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+
+	"github.com/pelletier/go-toml/v2"
+	"github.com/pelletier/go-toml/v2/internal/cli"
+)
+
+const usage = `tomljson can be used in two ways:
+Reading from stdin:
+  cat file.toml | tomljson > file.json
+
+Reading from a file:
+  tomljson file.toml > file.json
+`
+
+func main() {
+	p := cli.Program{
+		Usage: usage,
+		Fn:    convert,
+	}
+	p.Execute()
+}
+
+func convert(r io.Reader, w io.Writer) error {
+	var v interface{}
+
+	d := toml.NewDecoder(r)
+	err := d.Decode(&v)
+	if err != nil {
+		var derr *toml.DecodeError
+		if errors.As(err, &derr) {
+			row, col := derr.Position()
+			return fmt.Errorf("%s\nerror occurred at row %d column %d", derr.String(), row, col)
+		}
+		return err
+	}
+
+	e := json.NewEncoder(w)
+	e.SetIndent("", "  ")
+	return e.Encode(v)
+}

cmd/tomljson/main_test.go

@@ -0,0 +1,60 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"strings"
+	"testing"
+
+	"github.com/pelletier/go-toml/v2/internal/assert"
+)
+
+func TestConvert(t *testing.T) {
+	examples := []struct {
+		name     string
+		input    io.Reader
+		expected string
+		errors   bool
+	}{
+		{
+			name: "valid toml",
+			input: strings.NewReader(`
+[mytoml]
+a = 42`),
+			expected: `{
+  "mytoml": {
+    "a": 42
+  }
+}
+`,
+		},
+		{
+			name:   "invalid toml",
+			input:  strings.NewReader(`bad = []]`),
+			errors: true,
+		},
+		{
+			name:   "bad reader",
+			input:  &badReader{},
+			errors: true,
+		},
+	}
+
+	for _, e := range examples {
+		b := new(bytes.Buffer)
+		err := convert(e.input, b)
+		if e.errors {
+			assert.Error(t, err)
+		} else {
+			assert.NoError(t, err)
+			assert.Equal(t, e.expected, b.String())
+		}
+	}
+}
+
+type badReader struct{}
+
+func (r *badReader) Read([]byte) (int, error) {
+	return 0, fmt.Errorf("reader failed on purpose")
+}

cmd/tomll/main.go

@@ -0,0 +1,58 @@
+// Package tomll is a linter program for TOML.
+//
+// # Usage
+//
+// Reading from stdin, writing to stdout:
+//
+//	cat file.toml | tomll
+//
+// Reading and updating a list of files in place:
+//
+//	tomll a.toml b.toml c.toml
+//
+// # Installation
+//
+// Using Go:
+//
+//	go install github.com/pelletier/go-toml/v2/cmd/tomll@latest
+package main
+
+import (
+	"io"
+
+	"github.com/pelletier/go-toml/v2"
+	"github.com/pelletier/go-toml/v2/internal/cli"
+)
+
+const usage = `tomll can be used in two ways:
+
+Reading from stdin, writing to stdout:
+  cat file.toml | tomll > file.toml
+
+Reading and updating a list of files in place:
+  tomll a.toml b.toml c.toml
+
+When given a list of files, tomll will modify all files in place without asking.
+`
+
+func main() {
+	p := cli.Program{
+		Usage:   usage,
+		Fn:      convert,
+		Inplace: true,
+	}
+	p.Execute()
+}
+
+func convert(r io.Reader, w io.Writer) error {
+	var v interface{}
+
+	d := toml.NewDecoder(r)
+	err := d.Decode(&v)
+	if err != nil {
+		return err
+	}
+
+	e := toml.NewEncoder(w)
+	return e.Encode(v)
+}

cmd/tomll/main_test.go

@@ -0,0 +1,44 @@
+package main
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"github.com/pelletier/go-toml/v2/internal/assert"
+)
+
+func TestConvert(t *testing.T) {
+	examples := []struct {
+		name     string
+		input    string
+		expected string
+		errors   bool
+	}{
+		{
+			name: "valid toml",
+			input: `
+mytoml.a = 42.0
+`,
+			expected: `[mytoml]
+a = 42.0
+`,
+		},
+		{
+			name:   "invalid toml",
+			input:  `[what`,
+			errors: true,
+		},
+	}
+
+	for _, e := range examples {
+		b := new(bytes.Buffer)
+		err := convert(strings.NewReader(e.input), b)
+		if e.errors {
+			assert.Error(t, err)
+		} else {
+			assert.NoError(t, err)
+			assert.Equal(t, e.expected, b.String())
+		}
+	}
+}

cmd/tomltestgen/main.go

@@ -3,21 +3,17 @@
 //
 // Within the go-toml package, run `go generate`.  Otherwise, use:
 //
-//     go run github.com/pelletier/go-toml/cmd/tomltestgen -o toml_testgen_test.go
+//	go run github.com/pelletier/go-toml/cmd/tomltestgen -o toml_testgen_test.go
 package main
 
 import (
-	"archive/zip"
 	"bytes"
 	"flag"
 	"fmt"
 	"go/format"
-	"io"
-	"io/ioutil"
 	"log"
-	"net/http"
 	"os"
-	"regexp"
+	"path/filepath"
 	"strconv"
 	"strings"
 	"text/template"
@@ -43,8 +39,7 @@ type testsCollection struct {
 	Count     int
 }
 
-const srcTemplate = "// +build testsuite\n\n" +
-	"// Generated by tomltestgen for toml-test ref {{.Ref}} on {{.Timestamp}}\n" +
+const srcTemplate = "// Generated by tomltestgen for toml-test ref {{.Ref}} on {{.Timestamp}}\n" +
 	"package toml_test\n" +
 	" import (\n" +
 	"	\"testing\"\n" +
@@ -65,30 +60,6 @@ const srcTemplate = "// +build testsuite\n\n" +
 	"}\n" +
 	"{{end}}\n"
 
-func downloadTmpFile(url string) string {
-	log.Println("starting to download file from", url)
-	resp, err := http.Get(url)
-	if err != nil {
-		panic(err)
-	}
-	defer resp.Body.Close()
-
-	tmpfile, err := ioutil.TempFile("", "toml-test-*.zip")
-	if err != nil {
-		panic(err)
-	}
-	defer tmpfile.Close()
-
-	copiedLen, err := io.Copy(tmpfile, resp.Body)
-	if err != nil {
-		panic(err)
-	}
-	if resp.ContentLength > 0 && copiedLen != resp.ContentLength {
-		panic(fmt.Errorf("copied %d bytes, request body had %d", copiedLen, resp.ContentLength))
-	}
-	return tmpfile.Name()
-}
-
 func kebabToCamel(kebab string) string {
 	camel := ""
 	nextUpper := true
@@ -108,19 +79,6 @@ func kebabToCamel(kebab string) string {
 	return camel
 }
 
-func readFileFromZip(f *zip.File) string {
-	reader, err := f.Open()
-	if err != nil {
-		panic(err)
-	}
-	defer reader.Close()
-	bytes, err := ioutil.ReadAll(reader)
-	if err != nil {
-		panic(err)
-	}
-	return string(bytes)
-}
-
 func templateGoStr(input string) string {
 	return strconv.Quote(input)
 }
@@ -139,61 +97,59 @@ func main() {
 	flag.Usage = usage
 	flag.Parse()
 
-	url := "https://codeload.github.com/BurntSushi/toml-test/zip/" + *ref
-	resultFile := downloadTmpFile(url)
-	defer os.Remove(resultFile)
-	log.Println("file written to", resultFile)
-
-	zipReader, err := zip.OpenReader(resultFile)
-	if err != nil {
-		panic(err)
-	}
-	defer zipReader.Close()
-
 	collection := testsCollection{
 		Ref:       *ref,
 		Timestamp: time.Now().Format(time.RFC3339),
 	}
 
-	zipFilesMap := map[string]*zip.File{}
+	dirContent, _ := filepath.Glob("tests/invalid/**/*.toml")
+	for _, f := range dirContent {
+		filename := strings.TrimPrefix(f, "tests/valid/")
+		name := kebabToCamel(strings.TrimSuffix(filename, ".toml"))
+		name = strings.ReplaceAll(name, ".", "_")
 
-	for _, f := range zipReader.File {
-		zipFilesMap[f.Name] = f
+		log.Printf("> [%s] %s\n", "invalid", name)
+
+		tomlContent, err := os.ReadFile(f)
+		if err != nil {
+			fmt.Printf("failed to read test file: %s\n", err)
+			os.Exit(1)
+		}
+
+		collection.Invalid = append(collection.Invalid, invalid{
+			Name:  name,
+			Input: string(tomlContent),
+		})
+		collection.Count++
 	}
 
-	testFileRegexp := regexp.MustCompile(`([^/]+/tests/(valid|invalid)/(.+))\.(toml)`)
-	for _, f := range zipReader.File {
-		groups := testFileRegexp.FindStringSubmatch(f.Name)
-		if len(groups) > 0 {
-			name := kebabToCamel(groups[3])
-			testType := groups[2]
+	dirContent, _ = filepath.Glob("tests/valid/**/*.toml")
+	for _, f := range dirContent {
+		filename := strings.TrimPrefix(f, "tests/valid/")
+		name := kebabToCamel(strings.TrimSuffix(filename, ".toml"))
+		name = strings.ReplaceAll(name, ".", "_")
 
-			log.Printf("> [%s] %s\n", testType, name)
+		log.Printf("> [%s] %s\n", "valid", name)
 
-			tomlContent := readFileFromZip(f)
-
-			switch testType {
-			case "invalid":
-				collection.Invalid = append(collection.Invalid, invalid{
-					Name:  name,
-					Input: tomlContent,
-				})
-				collection.Count++
-			case "valid":
-				baseFilePath := groups[1]
-				jsonFilePath := baseFilePath + ".json"
-				jsonContent := readFileFromZip(zipFilesMap[jsonFilePath])
-
-				collection.Valid = append(collection.Valid, valid{
-					Name:    name,
-					Input:   tomlContent,
-					JsonRef: jsonContent,
-				})
-				collection.Count++
-			default:
-				panic(fmt.Sprintf("unknown test type: %s", testType))
-			}
+		tomlContent, err := os.ReadFile(f)
+		if err != nil {
+			fmt.Printf("failed reading test file: %s\n", err)
+			os.Exit(1)
 		}
+
+		filename = strings.TrimSuffix(f, ".toml")
+		jsonContent, err := os.ReadFile(filename + ".json")
+		if err != nil {
+			fmt.Printf("failed reading validation json: %s\n", err)
+			os.Exit(1)
+		}
+
+		collection.Valid = append(collection.Valid, valid{
+			Name:    name,
+			Input:   string(tomlContent),
+			JsonRef: string(jsonContent),
+		})
+		collection.Count++
 	}
 
 	log.Printf("Collected %d tests from toml-test\n", collection.Count)
@@ -203,7 +159,7 @@ func main() {
 	}
 	t := template.Must(template.New("src").Funcs(funcMap).Parse(srcTemplate))
 	buf := new(bytes.Buffer)
-	err = t.Execute(buf, collection)
+	err := t.Execute(buf, collection)
 	if err != nil {
 		panic(err)
 	}
@@ -217,7 +173,7 @@ func main() {
 		return
 	}
 
-	err = os.WriteFile(*out, outputBytes, 0644)
+	err = os.WriteFile(*out, outputBytes, 0o644)
 	if err != nil {
 		panic(err)
 	}

decode.go

@@ -5,6 +5,8 @@ import (
 	"math"
 	"strconv"
 	"time"
+
+	"github.com/pelletier/go-toml/v2/unstable"
 )
 
 func parseInteger(b []byte) (int64, error) {
@@ -32,33 +34,45 @@ func parseLocalDate(b []byte) (LocalDate, error) {
 	var date LocalDate
 
 	if len(b) != 10 || b[4] != '-' || b[7] != '-' {
-		return date, newDecodeError(b, "dates are expected to have the format YYYY-MM-DD")
+		return date, unstable.NewParserError(b, "dates are expected to have the format YYYY-MM-DD")
 	}
 
-	date.Year = parseDecimalDigits(b[0:4])
+	var err error
 
-	v := parseDecimalDigits(b[5:7])
+	date.Year, err = parseDecimalDigits(b[0:4])
+	if err != nil {
+		return LocalDate{}, err
+	}
 
-	date.Month = v
+	date.Month, err = parseDecimalDigits(b[5:7])
+	if err != nil {
+		return LocalDate{}, err
+	}
 
-	date.Day = parseDecimalDigits(b[8:10])
+	date.Day, err = parseDecimalDigits(b[8:10])
+	if err != nil {
+		return LocalDate{}, err
+	}
 
 	if !isValidDate(date.Year, date.Month, date.Day) {
-		return LocalDate{}, newDecodeError(b, "impossible date")
+		return LocalDate{}, unstable.NewParserError(b, "impossible date")
 	}
 
 	return date, nil
 }
 
-func parseDecimalDigits(b []byte) int {
+func parseDecimalDigits(b []byte) (int, error) {
 	v := 0
 
-	for _, c := range b {
+	for i, c := range b {
+		if c < '0' || c > '9' {
+			return 0, unstable.NewParserError(b[i:i+1], "expected digit (0-9)")
+		}
 		v *= 10
 		v += int(c - '0')
 	}
 
-	return v
+	return v, nil
 }
 
 func parseDateTime(b []byte) (time.Time, error) {
@@ -85,22 +99,59 @@ func parseDateTime(b []byte) (time.Time, error) {
 	} else {
 		const dateTimeByteLen = 6
 		if len(b) != dateTimeByteLen {
-			return time.Time{}, newDecodeError(b, "invalid date-time timezone")
+			return time.Time{}, unstable.NewParserError(b, "invalid date-time timezone")
 		}
-		direction := 1
-		if b[0] == '-' {
+		var direction int
+		switch b[0] {
+		case '-':
 			direction = -1
+		case '+':
+			direction = +1
+		default:
+			return time.Time{}, unstable.NewParserError(b[:1], "invalid timezone offset character")
+		}
+
+		if b[3] != ':' {
+			return time.Time{}, unstable.NewParserError(b[3:4], "expected a : separator")
+		}
+
+		hours, err := parseDecimalDigits(b[1:3])
+		if err != nil {
+			return time.Time{}, err
+		}
+		if hours > 23 {
+			return time.Time{}, unstable.NewParserError(b[:1], "invalid timezone offset hours")
+		}
+
+		minutes, err := parseDecimalDigits(b[4:6])
+		if err != nil {
+			return time.Time{}, err
+		}
+		if minutes > 59 {
+			return time.Time{}, unstable.NewParserError(b[:1], "invalid timezone offset minutes")
 		}
 
-		hours := digitsToInt(b[1:3])
-		minutes := digitsToInt(b[4:6])
 		seconds := direction * (hours*3600 + minutes*60)
-		zone = time.FixedZone("", seconds)
+		if seconds == 0 {
+			zone = time.UTC
+		} else {
+			zone = time.FixedZone("", seconds)
+		}
 		b = b[dateTimeByteLen:]
 	}
 
 	if len(b) > 0 {
-		return time.Time{}, newDecodeError(b, "extra bytes at the end of the timezone")
+		return time.Time{}, unstable.NewParserError(b, "extra bytes at the end of the timezone")
+	}
+
+	// Normalize leap seconds (second=60) to second=59 to prevent overflow
+	// when Go's time.Date normalizes the time. This is necessary because
+	// time.Date(9999, 12, 31, 23, 59, 60, 0, UTC) normalizes to year 10000,
+	// which is outside the valid TOML date range (0000-9999).
+	// See: https://github.com/pelletier/go-toml/issues/1015
+	second := dt.Second
+	if second == 60 {
+		second = 59
 	}
 
 	t := time.Date(
@@ -109,7 +160,7 @@ func parseDateTime(b []byte) (time.Time, error) {
 		dt.Day,
 		dt.Hour,
 		dt.Minute,
-		dt.Second,
+		second,
 		dt.Nanosecond,
 		zone)
 
@@ -121,7 +172,7 @@ func parseLocalDateTime(b []byte) (LocalDateTime, []byte, error) {
 
 	const localDateTimeByteMinLen = 11
 	if len(b) < localDateTimeByteMinLen {
-		return dt, nil, newDecodeError(b, "local datetimes are expected to have the format YYYY-MM-DDTHH:MM:SS[.NNNNNNNNN]")
+		return dt, nil, unstable.NewParserError(b, "local datetimes are expected to have the format YYYY-MM-DDTHH:MM:SS[.NNNNNNNNN]")
 	}
 
 	date, err := parseLocalDate(b[:10])
@@ -132,7 +183,7 @@ func parseLocalDateTime(b []byte) (LocalDateTime, []byte, error) {
 
 	sep := b[10]
 	if sep != 'T' && sep != ' ' && sep != 't' {
-		return dt, nil, newDecodeError(b[10:11], "datetime separator is expected to be T or a space")
+		return dt, nil, unstable.NewParserError(b[10:11], "datetime separator is expected to be T or a space")
 	}
 
 	t, rest, err := parseLocalTime(b[11:])
@@ -156,61 +207,86 @@ func parseLocalTime(b []byte) (LocalTime, []byte, error) {
 	// check if b matches to have expected format HH:MM:SS[.NNNNNN]
 	const localTimeByteLen = 8
 	if len(b) < localTimeByteLen {
-		return t, nil, newDecodeError(b, "times are expected to have the format HH:MM:SS[.NNNNNN]")
+		return t, nil, unstable.NewParserError(b, "times are expected to have the format HH:MM:SS[.NNNNNN]")
+	}
+
+	var err error
+
+	t.Hour, err = parseDecimalDigits(b[0:2])
+	if err != nil {
+		return t, nil, err
 	}
 
-	t.Hour = parseDecimalDigits(b[0:2])
 	if t.Hour > 23 {
-		return t, nil, newDecodeError(b[0:2], "hour cannot be greater 23")
+		return t, nil, unstable.NewParserError(b[0:2], "hour cannot be greater 23")
 	}
 	if b[2] != ':' {
-		return t, nil, newDecodeError(b[2:3], "expecting colon between hours and minutes")
+		return t, nil, unstable.NewParserError(b[2:3], "expecting colon between hours and minutes")
 	}
 
-	t.Minute = parseDecimalDigits(b[3:5])
+	t.Minute, err = parseDecimalDigits(b[3:5])
+	if err != nil {
+		return t, nil, err
+	}
 	if t.Minute > 59 {
-		return t, nil, newDecodeError(b[3:5], "minutes cannot be greater 59")
+		return t, nil, unstable.NewParserError(b[3:5], "minutes cannot be greater 59")
 	}
 	if b[5] != ':' {
-		return t, nil, newDecodeError(b[5:6], "expecting colon between minutes and seconds")
+		return t, nil, unstable.NewParserError(b[5:6], "expecting colon between minutes and seconds")
 	}
 
-	t.Second = parseDecimalDigits(b[6:8])
-	if t.Second > 59 {
-		return t, nil, newDecodeError(b[3:5], "seconds cannot be greater 59")
+	t.Second, err = parseDecimalDigits(b[6:8])
+	if err != nil {
+		return t, nil, err
 	}
 
-	const minLengthWithFrac = 9
-	if len(b) >= minLengthWithFrac && b[minLengthWithFrac-1] == '.' {
+	if t.Second > 60 {
+		return t, nil, unstable.NewParserError(b[6:8], "seconds cannot be greater 60")
+	}
+
+	b = b[8:]
+
+	if len(b) >= 1 && b[0] == '.' {
 		frac := 0
+		precision := 0
 		digits := 0
 
-		for i, c := range b[minLengthWithFrac:] {
+		for i, c := range b[1:] {
 			if !isDigit(c) {
 				if i == 0 {
-					return t, nil, newDecodeError(b[i:i+1], "need at least one digit after fraction point")
+					return t, nil, unstable.NewParserError(b[0:1], "need at least one digit after fraction point")
 				}
-
 				break
 			}
+			digits++
 
 			const maxFracPrecision = 9
 			if i >= maxFracPrecision {
-				return t, nil, newDecodeError(b[i:i+1], "maximum precision for date time is nanosecond")
+				// go-toml allows decoding fractional seconds
+				// beyond the supported precision of 9
+				// digits. It truncates the fractional component
+				// to the supported precision and ignores the
+				// remaining digits.
+				//
+				// https://github.com/pelletier/go-toml/discussions/707
+				continue
 			}
 
 			frac *= 10
 			frac += int(c - '0')
-			digits++
+			precision++
 		}
 
-		t.Nanosecond = frac * nspow[digits]
-		t.Precision = digits
+		if precision == 0 {
+			return t, nil, unstable.NewParserError(b[:1], "nanoseconds need at least one digit")
+		}
 
-		return t, b[9+digits:], nil
+		t.Nanosecond = frac * nspow[precision]
+		t.Precision = precision
+
+		return t, b[1+digits:], nil
 	}
-
-	return t, b[8:], nil
+	return t, b, nil
 }
 
 //nolint:cyclop
@@ -225,40 +301,40 @@ func parseFloat(b []byte) (float64, error) {
 	}
 
 	if cleaned[0] == '.' {
-		return 0, newDecodeError(b, "float cannot start with a dot")
+		return 0, unstable.NewParserError(b, "float cannot start with a dot")
 	}
 
 	if cleaned[len(cleaned)-1] == '.' {
-		return 0, newDecodeError(b, "float cannot end with a dot")
+		return 0, unstable.NewParserError(b, "float cannot end with a dot")
 	}
 
 	dotAlreadySeen := false
 	for i, c := range cleaned {
 		if c == '.' {
 			if dotAlreadySeen {
-				return 0, newDecodeError(b[i:i+1], "float can have at most one decimal point")
+				return 0, unstable.NewParserError(b[i:i+1], "float can have at most one decimal point")
 			}
 			if !isDigit(cleaned[i-1]) {
-				return 0, newDecodeError(b[i-1:i+1], "float decimal point must be preceded by a digit")
+				return 0, unstable.NewParserError(b[i-1:i+1], "float decimal point must be preceded by a digit")
 			}
 			if !isDigit(cleaned[i+1]) {
-				return 0, newDecodeError(b[i:i+2], "float decimal point must be followed by a digit")
+				return 0, unstable.NewParserError(b[i:i+2], "float decimal point must be followed by a digit")
 			}
 			dotAlreadySeen = true
 		}
 	}
 
 	start := 0
-	if b[0] == '+' || b[0] == '-' {
+	if cleaned[0] == '+' || cleaned[0] == '-' {
 		start = 1
 	}
-	if b[start] == '0' && isDigit(b[start+1]) {
-		return 0, newDecodeError(b, "float integer part cannot have leading zeroes")
+	if cleaned[start] == '0' && len(cleaned) > start+1 && isDigit(cleaned[start+1]) {
+		return 0, unstable.NewParserError(b, "float integer part cannot have leading zeroes")
 	}
 
 	f, err := strconv.ParseFloat(string(cleaned), 64)
 	if err != nil {
-		return 0, newDecodeError(b, "unable to parse float: %w", err)
+		return 0, unstable.NewParserError(b, "unable to parse float: %w", err)
 	}
 
 	return f, nil
@@ -272,7 +348,7 @@ func parseIntHex(b []byte) (int64, error) {
 
 	i, err := strconv.ParseInt(string(cleaned), 16, 64)
 	if err != nil {
-		return 0, newDecodeError(b, "couldn't parse hexadecimal number: %w", err)
+		return 0, unstable.NewParserError(b, "couldn't parse hexadecimal number: %w", err)
 	}
 
 	return i, nil
@@ -286,7 +362,7 @@ func parseIntOct(b []byte) (int64, error) {
 
 	i, err := strconv.ParseInt(string(cleaned), 8, 64)
 	if err != nil {
-		return 0, newDecodeError(b, "couldn't parse octal number: %w", err)
+		return 0, unstable.NewParserError(b, "couldn't parse octal number: %w", err)
 	}
 
 	return i, nil
@@ -300,7 +376,7 @@ func parseIntBin(b []byte) (int64, error) {
 
 	i, err := strconv.ParseInt(string(cleaned), 2, 64)
 	if err != nil {
-		return 0, newDecodeError(b, "couldn't parse binary number: %w", err)
+		return 0, unstable.NewParserError(b, "couldn't parse binary number: %w", err)
 	}
 
 	return i, nil
@@ -323,24 +399,33 @@ func parseIntDec(b []byte) (int64, error) {
 	}
 
 	if len(cleaned) > startIdx+1 && cleaned[startIdx] == '0' {
-		return 0, newDecodeError(b, "leading zero not allowed on decimal number")
+		return 0, unstable.NewParserError(b, "leading zero not allowed on decimal number")
 	}
 
 	i, err := strconv.ParseInt(string(cleaned), 10, 64)
 	if err != nil {
-		return 0, newDecodeError(b, "couldn't parse decimal number: %w", err)
+		return 0, unstable.NewParserError(b, "couldn't parse decimal number: %w", err)
 	}
 
 	return i, nil
 }
 
 func checkAndRemoveUnderscoresIntegers(b []byte) ([]byte, error) {
-	if b[0] == '_' {
-		return nil, newDecodeError(b[0:1], "number cannot start with underscore")
+	start := 0
+	if b[start] == '+' || b[start] == '-' {
+		start++
+	}
+
+	if len(b) == start {
+		return b, nil
+	}
+
+	if b[start] == '_' {
+		return nil, unstable.NewParserError(b[start:start+1], "number cannot start with underscore")
 	}
 
 	if b[len(b)-1] == '_' {
-		return nil, newDecodeError(b[len(b)-1:], "number cannot end with underscore")
+		return nil, unstable.NewParserError(b[len(b)-1:], "number cannot end with underscore")
 	}
 
 	// fast path
@@ -362,7 +447,7 @@ func checkAndRemoveUnderscoresIntegers(b []byte) ([]byte, error) {
 		c := b[i]
 		if c == '_' {
 			if !before {
-				return nil, newDecodeError(b[i-1:i+1], "number must have at least one digit between underscores")
+				return nil, unstable.NewParserError(b[i-1:i+1], "number must have at least one digit between underscores")
 			}
 			before = false
 		} else {
@@ -376,11 +461,11 @@ func checkAndRemoveUnderscoresIntegers(b []byte) ([]byte, error) {
 
 func checkAndRemoveUnderscoresFloats(b []byte) ([]byte, error) {
 	if b[0] == '_' {
-		return nil, newDecodeError(b[0:1], "number cannot start with underscore")
+		return nil, unstable.NewParserError(b[0:1], "number cannot start with underscore")
 	}
 
 	if b[len(b)-1] == '_' {
-		return nil, newDecodeError(b[len(b)-1:], "number cannot end with underscore")
+		return nil, unstable.NewParserError(b[len(b)-1:], "number cannot end with underscore")
 	}
 
 	// fast path
@@ -403,20 +488,27 @@ func checkAndRemoveUnderscoresFloats(b []byte) ([]byte, error) {
 		switch c {
 		case '_':
 			if !before {
-				return nil, newDecodeError(b[i-1:i+1], "number must have at least one digit between underscores")
+				return nil, unstable.NewParserError(b[i-1: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")
+			}
+			before = false
+		case '+', '-':
+			// signed exponents
+			cleaned = append(cleaned, c)
 			before = false
 		case 'e', 'E':
 			if i < len(b)-1 && b[i+1] == '_' {
-				return nil, newDecodeError(b[i+1:i+2], "cannot have underscore after exponent")
+				return nil, unstable.NewParserError(b[i+1:i+2], "cannot have underscore after exponent")
 			}
 			cleaned = append(cleaned, c)
 		case '.':
 			if i < len(b)-1 && b[i+1] == '_' {
-				return nil, newDecodeError(b[i+1:i+2], "cannot have underscore after decimal point")
+				return nil, unstable.NewParserError(b[i+1:i+2], "cannot have underscore after decimal point")
 			}
 			if i > 0 && b[i-1] == '_' {
-				return nil, newDecodeError(b[i-1:i], "cannot have underscore before decimal point")
+				return nil, unstable.NewParserError(b[i-1:i], "cannot have underscore before decimal point")
 			}
 			cleaned = append(cleaned, c)
 		default:
@@ -430,7 +522,7 @@ func checkAndRemoveUnderscoresFloats(b []byte) ([]byte, error) {
 
 // isValidDate checks if a provided date is a date that exists.
 func isValidDate(year int, month int, day int) bool {
-	return day <= daysIn(month, year)
+	return month > 0 && month < 13 && day > 0 && day <= daysIn(month, year)
 }
 
 // daysBefore[m] counts the number of days in a non-leap year
@@ -462,3 +554,7 @@ func daysIn(m int, year int) int {
 func isLeap(year int) bool {
 	return year%4 == 0 && (year%100 != 0 || year%400 == 0)
 }
+
+func isDigit(r byte) bool {
+	return r >= '0' && r <= '9'
+}

errors.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	"github.com/pelletier/go-toml/v2/internal/danger"
+	"github.com/pelletier/go-toml/v2/unstable"
 )
 
 // DecodeError represents an error encountered during the parsing or decoding
@@ -27,7 +28,7 @@ type DecodeError struct {
 // corresponding field in the target value. It contains all the missing fields
 // in Errors.
 //
-// Emitted by Decoder when SetStrict(true) was called.
+// Emitted by Decoder when DisallowUnknownFields() was called.
 type StrictMissingError struct {
 	// One error per field that could not be found.
 	Errors []DecodeError
@@ -53,27 +54,19 @@ func (s *StrictMissingError) String() string {
 	return buf.String()
 }
 
-type Key []string
-
-// internal version of DecodeError that is used as the base to create a
-// DecodeError with full context.
-type decodeError struct {
-	highlight []byte
-	message   string
-	key       Key // optional
-}
-
-func (de *decodeError) Error() string {
-	return de.message
-}
-
-func newDecodeError(highlight []byte, format string, args ...interface{}) error {
-	return &decodeError{
-		highlight: highlight,
-		message:   fmt.Errorf(format, args...).Error(),
+// Unwrap returns wrapped decode errors
+//
+// Implements errors.Join() interface.
+func (s *StrictMissingError) Unwrap() []error {
+	var errs []error
+	for i := range s.Errors {
+		errs = append(errs, &s.Errors[i])
 	}
+	return errs
 }
 
+type Key []string
+
 // Error returns the error message contained in the DecodeError.
 func (e *DecodeError) Error() string {
 	return "toml: " + e.message
@@ -96,20 +89,21 @@ func (e *DecodeError) Key() Key {
 	return e.key
 }
 
-// decodeErrorFromHighlight creates a DecodeError referencing a highlighted
+// wrapDecodeError creates a DecodeError referencing a highlighted
 // range of bytes from document.
 //
 // highlight needs to be a sub-slice of document, or this function panics.
 //
 // The function copies all bytes used in DecodeError, so that document and
 // highlight can be freely deallocated.
+//
 //nolint:funlen
-func wrapDecodeError(document []byte, de *decodeError) *DecodeError {
-	offset := danger.SubsliceOffset(document, de.highlight)
+func wrapDecodeError(document []byte, de *unstable.ParserError) *DecodeError {
+	offset := danger.SubsliceOffset(document, de.Highlight)
 
 	errMessage := de.Error()
 	errLine, errColumn := positionAtEnd(document[:offset])
-	before, after := linesOfContext(document, de.highlight, offset, 3)
+	before, after := linesOfContext(document, de.Highlight, offset, 3)
 
 	var buf strings.Builder
 
@@ -139,7 +133,7 @@ func wrapDecodeError(document []byte, de *decodeError) *DecodeError {
 		buf.Write(before[0])
 	}
 
-	buf.Write(de.highlight)
+	buf.Write(de.Highlight)
 
 	if len(after) > 0 {
 		buf.Write(after[0])
@@ -157,7 +151,7 @@ func wrapDecodeError(document []byte, de *decodeError) *DecodeError {
 		buf.WriteString(strings.Repeat(" ", len(before[0])))
 	}
 
-	buf.WriteString(strings.Repeat("~", len(de.highlight)))
+	buf.WriteString(strings.Repeat("~", len(de.Highlight)))
 
 	if len(errMessage) > 0 {
 		buf.WriteString(" ")
@@ -182,7 +176,7 @@ func wrapDecodeError(document []byte, de *decodeError) *DecodeError {
 		message: errMessage,
 		line:    errLine,
 		column:  errColumn,
-		key:     de.key,
+		key:     de.Key,
 		human:   buf.String(),
 	}
 }

errors_test.go

@@ -7,7 +7,8 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/stretchr/testify/assert"
+	"github.com/pelletier/go-toml/v2/internal/assert"
+	"github.com/pelletier/go-toml/v2/unstable"
 )
 
 //nolint:funlen
@@ -170,9 +171,9 @@ line 5`,
 			doc := b.Bytes()
 			hl := doc[start:end]
 
-			err := wrapDecodeError(doc, &decodeError{
-				highlight: hl,
-				message:   e.msg,
+			err := wrapDecodeError(doc, &unstable.ParserError{
+				Highlight: hl,
+				Message:   e.msg,
 			})
 
 			var derr *DecodeError
@@ -204,6 +205,21 @@ func TestDecodeError_Accessors(t *testing.T) {
 	assert.Equal(t, "bar", e.String())
 }
 
+func TestStrictErrorUnwrap(t *testing.T) {
+	fo := bytes.NewBufferString(`
+Missing = 1
+OtherMissing = 1
+`)
+	var out struct{}
+	err := NewDecoder(fo).DisallowUnknownFields().Decode(&out)
+	assert.Error(t, err)
+
+	strictErr := &StrictMissingError{}
+	assert.True(t, errors.As(err, &strictErr))
+
+	assert.Equal(t, 2, len(strictErr.Unwrap()))
+}
+
 func ExampleDecodeError() {
 	doc := `name = 123__456`
 
@@ -212,12 +228,12 @@ func ExampleDecodeError() {
 
 	fmt.Println(err)
 
-	//nolint:errorlint
-	de := err.(*DecodeError)
-	fmt.Println(de.String())
-
-	row, col := de.Position()
-	fmt.Println("error occurred at row", row, "column", col)
+	var derr *DecodeError
+	if errors.As(err, &derr) {
+		fmt.Println(derr.String())
+		row, col := derr.Position()
+		fmt.Println("error occurred at row", row, "column", col)
+	}
 	// Output:
 	// toml: number must have at least one digit between underscores
 	// 1| name = 123__456

example_text_marshaling_test.go

@@ -0,0 +1,37 @@
+package toml_test
+
+import (
+	"fmt"
+	"log"
+	"strconv"
+
+	"github.com/pelletier/go-toml/v2"
+)
+
+type customInt int
+
+func (i *customInt) UnmarshalText(b []byte) error {
+	x, err := strconv.ParseInt(string(b), 10, 32)
+	if err != nil {
+		return err
+	}
+	*i = customInt(x * 100)
+	return nil
+}
+
+type doc struct {
+	Value customInt
+}
+
+func ExampleUnmarshal_textUnmarshal() {
+	var x doc
+
+	data := []byte(`value  = "42"`)
+	err := toml.Unmarshal(data, &x)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println(x)
+	// Output:
+	// {4200}
+}

fast_test.go

@@ -4,21 +4,28 @@ import (
 	"testing"
 
 	"github.com/pelletier/go-toml/v2"
-	"github.com/stretchr/testify/require"
+	"github.com/pelletier/go-toml/v2/internal/assert"
 )
 
-func TestFastSimple(t *testing.T) {
+func TestFastSimpleInt(t *testing.T) {
 	m := map[string]int64{}
 	err := toml.Unmarshal([]byte(`a = 42`), &m)
-	require.NoError(t, err)
-	require.Equal(t, map[string]int64{"a": 42}, m)
+	assert.NoError(t, err)
+	assert.Equal(t, map[string]int64{"a": 42}, m)
+}
+
+func TestFastSimpleFloat(t *testing.T) {
+	m := map[string]float64{}
+	err := toml.Unmarshal([]byte("a = 42\nb = 1.1\nc = 12341234123412341234123412341234"), &m)
+	assert.NoError(t, err)
+	assert.Equal(t, map[string]float64{"a": 42, "b": 1.1, "c": 1.2341234123412342e+31}, m)
 }
 
 func TestFastSimpleString(t *testing.T) {
 	m := map[string]string{}
 	err := toml.Unmarshal([]byte(`a = "hello"`), &m)
-	require.NoError(t, err)
-	require.Equal(t, map[string]string{"a": "hello"}, m)
+	assert.NoError(t, err)
+	assert.Equal(t, map[string]string{"a": "hello"}, m)
 }
 
 func TestFastSimpleInterface(t *testing.T) {
@@ -26,8 +33,8 @@ func TestFastSimpleInterface(t *testing.T) {
 	err := toml.Unmarshal([]byte(`
 	a = "hello"
 	b = 42`), &m)
-	require.NoError(t, err)
-	require.Equal(t, map[string]interface{}{
+	assert.NoError(t, err)
+	assert.Equal(t, map[string]interface{}{
 		"a": "hello",
 		"b": int64(42),
 	}, m)
@@ -39,8 +46,8 @@ func TestFastMultipartKeyInterface(t *testing.T) {
 	a.interim = "test"
 	a.b.c = "hello"
 	b = 42`), &m)
-	require.NoError(t, err)
-	require.Equal(t, map[string]interface{}{
+	assert.NoError(t, err)
+	assert.Equal(t, map[string]interface{}{
 		"a": map[string]interface{}{
 			"interim": "test",
 			"b": map[string]interface{}{
@@ -59,8 +66,8 @@ func TestFastExistingMap(t *testing.T) {
 	ints.one = 1
 	ints.two = 2
 	strings.yo = "hello"`), &m)
-	require.NoError(t, err)
-	require.Equal(t, map[string]interface{}{
+	assert.NoError(t, err)
+	assert.Equal(t, map[string]interface{}{
 		"ints": map[string]interface{}{
 			"one": int64(1),
 			"two": int64(2),
@@ -83,9 +90,9 @@ func TestFastArrayTable(t *testing.T) {
 	m := map[string]interface{}{}
 
 	err := toml.Unmarshal(b, &m)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 
-	require.Equal(t, map[string]interface{}{
+	assert.Equal(t, map[string]interface{}{
 		"root": map[string]interface{}{
 			"nested": []interface{}{
 				map[string]interface{}{

fuzz_test.go

@@ -0,0 +1,53 @@
+package toml_test
+
+import (
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/pelletier/go-toml/v2"
+	"github.com/pelletier/go-toml/v2/internal/assert"
+)
+
+func FuzzUnmarshal(f *testing.F) {
+	file, err := os.ReadFile("benchmark/benchmark.toml")
+	if err != nil {
+		panic(err)
+	}
+	f.Add(file)
+
+	f.Fuzz(func(t *testing.T, b []byte) {
+		if strings.Contains(string(b), "nan") {
+			// Current limitation of testify.
+			// https://github.com/stretchr/testify/issues/624
+			t.Skip("can't compare NaNs")
+		}
+
+		t.Log("INITIAL DOCUMENT ===========================")
+		t.Log(string(b))
+
+		var v interface{}
+		err := toml.Unmarshal(b, &v)
+		if err != nil {
+			return
+		}
+
+		t.Log("DECODED VALUE ===========================")
+		t.Logf("%#+v", v)
+
+		encoded, err := toml.Marshal(v)
+		if err != nil {
+			t.Fatalf("cannot marshal unmarshaled document: %s", err)
+		}
+
+		t.Log("ENCODED DOCUMENT ===========================")
+		t.Log(string(encoded))
+
+		var v2 interface{}
+		err = toml.Unmarshal(encoded, &v2)
+		if err != nil {
+			t.Fatalf("failed round trip: %s", err)
+		}
+		assert.Equal(t, v, v2)
+	})
+}

go.mod

@@ -1,6 +1,3 @@
 module github.com/pelletier/go-toml/v2
 
-go 1.16
-
-// latest (v1.7.0) doesn't have the fix for time.Time
-require github.com/stretchr/testify v1.7.1-0.20210427113832-6241f9ab9942
+go 1.21.0

go.sum

@@ -1,11 +0,0 @@
-github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
-github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/testify v1.7.1-0.20210427113832-6241f9ab9942 h1:t0lM6y/M5IiUZyvbBTcngso8SZEZICH7is9B6g/obVU=
-github.com/stretchr/testify v1.7.1-0.20210427113832-6241f9ab9942/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
-gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c h1:dUUwHk2QECo/6vqA44rthZ8ie2QXMNeKRTHCNY2nXvo=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/assert/assertions.go

@@ -0,0 +1,135 @@
+package assert
+
+import (
+	"bytes"
+	"fmt"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// True asserts that an expression is true.
+func True(t testing.TB, ok bool, msgAndArgs ...any) {
+	if ok {
+		return
+	}
+	t.Helper()
+	t.Fatal(formatMsgAndArgs("Expected expression to be true", msgAndArgs...))
+}
+
+// False asserts that an expression is false.
+func False(t testing.TB, ok bool, msgAndArgs ...any) {
+	if !ok {
+		return
+	}
+	t.Helper()
+	t.Fatal(formatMsgAndArgs("Expected expression to be false", msgAndArgs...))
+}
+
+// Equal asserts that "expected" and "actual" are equal.
+func Equal[T any](t testing.TB, expected, actual T, msgAndArgs ...any) {
+	if objectsAreEqual(expected, actual) {
+		return
+	}
+	t.Helper()
+	msg := formatMsgAndArgs("Expected values to be equal:", msgAndArgs...)
+	t.Fatalf("%s\n%s", msg, diff(expected, actual))
+}
+
+// Error asserts that an error is not nil.
+func Error(t testing.TB, err error, msgAndArgs ...any) {
+	if err != nil {
+		return
+	}
+	t.Helper()
+	t.Fatal(formatMsgAndArgs("Expected an error", msgAndArgs...))
+}
+
+// NoError asserts that an error is nil.
+func NoError(t testing.TB, err error, msgAndArgs ...any) {
+	if err == nil {
+		return
+	}
+	t.Helper()
+	msg := formatMsgAndArgs("Unexpected error:", msgAndArgs...)
+	t.Fatalf("%s\n%+v", msg, err)
+}
+
+// Panics asserts that the given function panics.
+func Panics(t testing.TB, fn func(), msgAndArgs ...any) {
+	t.Helper()
+	defer func() {
+		if recover() == nil {
+			msg := formatMsgAndArgs("Expected function to panic", msgAndArgs...)
+			t.Fatal(msg)
+		}
+	}()
+	fn()
+}
+
+// Zero asserts that a value is its zero value.
+func Zero[T any](t testing.TB, value T, msgAndArgs ...any) {
+	var zero T
+	if objectsAreEqual(value, zero) {
+		return
+	}
+	val := reflect.ValueOf(value)
+	if (val.Kind() == reflect.Slice || val.Kind() == reflect.Map || val.Kind() == reflect.Array) && val.Len() == 0 {
+		return
+	}
+	t.Helper()
+	msg := formatMsgAndArgs("Expected zero value but got:", msgAndArgs...)
+	t.Fatalf("%s\n%v", msg, value)
+}
+
+func NotZero[T any](t testing.TB, value T, msgAndArgs ...any) {
+	var zero T
+	if !objectsAreEqual(value, zero) {
+		val := reflect.ValueOf(value)
+		if !((val.Kind() == reflect.Slice || val.Kind() == reflect.Map || val.Kind() == reflect.Array) && val.Len() == 0) {
+			return
+		}
+	}
+	t.Helper()
+	msg := formatMsgAndArgs("Unexpected zero value:", msgAndArgs...)
+	t.Fatalf("%s\n%v", msg, value)
+}
+
+func formatMsgAndArgs(msg string, args ...any) string {
+	if len(args) == 0 {
+		return msg
+	}
+	format, ok := args[0].(string)
+	if !ok {
+		panic("message argument must be a fmt string")
+	}
+	return fmt.Sprintf(format, args[1:]...)
+}
+
+func diff(expected, actual any) string {
+	lines := []string{
+		"expected:",
+		fmt.Sprintf("%v", expected),
+		"actual:",
+		fmt.Sprintf("%v", actual),
+	}
+	return strings.Join(lines, "\n")
+}
+
+func objectsAreEqual(expected, actual any) bool {
+	if expected == nil || actual == nil {
+		return expected == actual
+	}
+	if exp, eok := expected.([]byte); eok {
+		if act, aok := actual.([]byte); aok {
+			return bytes.Equal(exp, act)
+		}
+	}
+	if exp, eok := expected.(string); eok {
+		if act, aok := actual.(string); aok {
+			return exp == act
+		}
+	}
+
+	return reflect.DeepEqual(expected, actual)
+}

internal/assert/assertions_test.go

@@ -0,0 +1,184 @@
+package assert
+
+import (
+	"fmt"
+	"testing"
+)
+
+type Data struct {
+	Label string
+	Value int64
+}
+
+func TestBadMessage(t *testing.T) {
+	invalidMessage := func() { True(t, false, 1234) }
+	assertOk(t, "Non-fmt message value", func(t testing.TB) {
+		Panics(t, invalidMessage)
+	})
+	assertFail(t, "Non-fmt message value", func(t testing.TB) {
+		True(t, false, "example %s", "message")
+	})
+}
+
+func TestTrue(t *testing.T) {
+	assertOk(t, "Succeed", func(t testing.TB) {
+		True(t, 1 > 0)
+	})
+	assertFail(t, "Fail", func(t testing.TB) {
+		True(t, 1 < 0)
+	})
+}
+
+func TestFalse(t *testing.T) {
+	assertOk(t, "Succeed", func(t testing.TB) {
+		False(t, 1 < 0)
+	})
+	assertFail(t, "Fail", func(t testing.TB) {
+		False(t, 1 > 0)
+	})
+}
+
+func TestEqual(t *testing.T) {
+	assertOk(t, "Nil", func(t testing.TB) {
+		Equal(t, interface{}(nil), interface{}(nil))
+	})
+	assertOk(t, "Identical structs", func(t testing.TB) {
+		Equal(t, Data{"expected", 1234}, Data{"expected", 1234})
+	})
+	assertFail(t, "Different structs", func(t testing.TB) {
+		Equal(t, Data{"expected", 1234}, Data{"actual", 1234})
+	})
+	assertOk(t, "Identical numbers", func(t testing.TB) {
+		Equal(t, 1234, 1234)
+	})
+	assertFail(t, "Identical numbers", func(t testing.TB) {
+		Equal(t, 1234, 1324)
+	})
+	assertOk(t, "Zero-length byte arrays", func(t testing.TB) {
+		Equal(t, []byte(nil), []byte(""))
+	})
+	assertOk(t, "Identical byte arrays", func(t testing.TB) {
+		Equal(t, []byte{1, 2, 3, 4}, []byte{1, 2, 3, 4})
+	})
+	assertFail(t, "Different byte arrays", func(t testing.TB) {
+		Equal(t, []byte{1, 2, 3, 4}, []byte{1, 3, 2, 4})
+	})
+	assertOk(t, "Identical strings", func(t testing.TB) {
+		Equal(t, "example", "example")
+	})
+	assertFail(t, "Identical strings", func(t testing.TB) {
+		Equal(t, "example", "elpmaxe")
+	})
+}
+
+func TestError(t *testing.T) {
+	assertOk(t, "Error", func(t testing.TB) {
+		Error(t, fmt.Errorf("example"))
+	})
+	assertFail(t, "Nil", func(t testing.TB) {
+		Error(t, nil)
+	})
+}
+
+func TestNoError(t *testing.T) {
+	assertFail(t, "Error", func(t testing.TB) {
+		NoError(t, fmt.Errorf("example"))
+	})
+	assertOk(t, "Nil", func(t testing.TB) {
+		NoError(t, nil)
+	})
+}
+
+func TestPanics(t *testing.T) {
+	willPanic := func() { panic("example") }
+	wontPanic := func() {}
+	assertOk(t, "Will panic", func(t testing.TB) {
+		Panics(t, willPanic)
+	})
+	assertFail(t, "Won't panic", func(t testing.TB) {
+		Panics(t, wontPanic)
+	})
+}
+
+func TestZero(t *testing.T) {
+	assertOk(t, "Empty struct", func(t testing.TB) {
+		Zero(t, Data{})
+	})
+	assertFail(t, "Non-empty struct", func(t testing.TB) {
+		Zero(t, Data{Label: "example"})
+	})
+	assertOk(t, "Nil slice", func(t testing.TB) {
+		var slice []int
+		Zero(t, slice)
+	})
+	assertFail(t, "Non-empty slice", func(t testing.TB) {
+		slice := []int{1, 2, 3, 4}
+		Zero(t, slice)
+	})
+	assertOk(t, "Zero-length slice", func(t testing.TB) {
+		slice := []int{}
+		Zero(t, slice)
+	})
+}
+
+func TestNotZero(t *testing.T) {
+	assertFail(t, "Empty struct", func(t testing.TB) {
+		zero := Data{}
+		NotZero(t, zero)
+	})
+	assertOk(t, "Non-empty struct", func(t testing.TB) {
+		notZero := Data{Label: "example"}
+		NotZero(t, notZero)
+	})
+	assertFail(t, "Nil slice", func(t testing.TB) {
+		var slice []int
+		NotZero(t, slice)
+	})
+	assertFail(t, "Zero-length slice", func(t testing.TB) {
+		slice := []int{}
+		NotZero(t, slice)
+	})
+	assertOk(t, "Non-empty slice", func(t testing.TB) {
+		slice := []int{1, 2, 3, 4}
+		NotZero(t, slice)
+	})
+}
+
+type testCase struct {
+	*testing.T
+	failed string
+}
+
+func (t *testCase) Fatal(args ...interface{}) {
+	t.failed = fmt.Sprint(args...)
+}
+
+func (t *testCase) Fatalf(message string, args ...interface{}) {
+	t.failed = fmt.Sprintf(message, args...)
+}
+
+func assertFail(t *testing.T, name string, fn func(t testing.TB)) {
+	t.Helper()
+	t.Run(name, func(t *testing.T) {
+		t.Helper()
+		test := &testCase{T: t}
+		fn(test)
+		if test.failed == "" {
+			t.Fatal("Test expected to fail but did not")
+		} else {
+			t.Log(test.failed)
+		}
+	})
+}
+
+func assertOk(t *testing.T, name string, fn func(t testing.TB)) {
+	t.Helper()
+	t.Run(name, func(t *testing.T) {
+		t.Helper()
+		test := &testCase{T: t}
+		fn(test)
+		if test.failed != "" {
+			t.Fatal("Test expected to succeed but did not:\n", test.failed)
+		}
+	})
+}

internal/ast/ast.go

@@ -1,152 +0,0 @@
-package ast
-
-import (
-	"fmt"
-	"unsafe"
-
-	"github.com/pelletier/go-toml/v2/internal/danger"
-)
-
-// Iterator starts uninitialized, you need to call Next() first.
-//
-// For example:
-//
-// it := n.Children()
-// for it.Next() {
-// 		it.Node()
-// }
-type Iterator struct {
-	started bool
-	node    *Node
-}
-
-// Next moves the iterator forward and returns true if points to a node, false
-// otherwise.
-func (c *Iterator) Next() bool {
-	if !c.started {
-		c.started = true
-	} else if c.node.Valid() {
-		c.node = c.node.Next()
-	}
-	return c.node.Valid()
-}
-
-// IsLast returns true if the current node of the iterator is the last one.
-// Subsequent call to Next() will return false.
-func (c *Iterator) IsLast() bool {
-	return c.node.next == 0
-}
-
-// Node returns a copy of the node pointed at by the iterator.
-func (c *Iterator) Node() *Node {
-	return c.node
-}
-
-// Root contains a full AST.
-//
-// It is immutable once constructed with Builder.
-type Root struct {
-	nodes []Node
-}
-
-// Iterator over the top level nodes.
-func (r *Root) Iterator() Iterator {
-	it := Iterator{}
-	if len(r.nodes) > 0 {
-		it.node = &r.nodes[0]
-	}
-	return it
-}
-
-func (r *Root) at(idx Reference) *Node {
-	return &r.nodes[idx]
-}
-
-// Arrays have one child per element in the array.
-// InlineTables have one child per key-value pair in the table.
-// KeyValues have at least two children. The first one is the value. The
-// rest make a potentially dotted key.
-// Table and Array table have one child per element of the key they
-// represent (same as KeyValue, but without the last node being the value).
-// children []Node
-type Node struct {
-	Kind Kind
-	Raw  Range  // Raw bytes from the input.
-	Data []byte // Node value (could be either allocated or referencing the input).
-
-	// References to other nodes, as offsets in the backing array from this
-	// node. References can go backward, so those can be negative.
-	next  int // 0 if last element
-	child int // 0 if no child
-}
-
-type Range struct {
-	Offset uint32
-	Length uint32
-}
-
-// Next returns a copy of the next node, or an invalid Node if there is no
-// next node.
-func (n *Node) Next() *Node {
-	if n.next == 0 {
-		return nil
-	}
-	ptr := unsafe.Pointer(n)
-	size := unsafe.Sizeof(Node{})
-	return (*Node)(danger.Stride(ptr, size, n.next))
-}
-
-// Child returns a copy of the first child node of this node. Other children
-// can be accessed calling Next on the first child.
-// Returns an invalid Node if there is none.
-func (n *Node) Child() *Node {
-	if n.child == 0 {
-		return nil
-	}
-	ptr := unsafe.Pointer(n)
-	size := unsafe.Sizeof(Node{})
-	return (*Node)(danger.Stride(ptr, size, n.child))
-}
-
-// Valid returns true if the node's kind is set (not to Invalid).
-func (n *Node) Valid() bool {
-	return n != nil
-}
-
-// Key returns the child nodes making the Key on a supported node. Panics
-// otherwise.
-// They are guaranteed to be all be of the Kind Key. A simple key would return
-// just one element.
-func (n *Node) Key() Iterator {
-	switch n.Kind {
-	case KeyValue:
-		value := n.Child()
-		if !value.Valid() {
-			panic(fmt.Errorf("KeyValue should have at least two children"))
-		}
-		return Iterator{node: value.Next()}
-	case Table, ArrayTable:
-		return Iterator{node: n.Child()}
-	default:
-		panic(fmt.Errorf("Key() is not supported on a %s", n.Kind))
-	}
-}
-
-// Value returns a pointer to the value node of a KeyValue.
-// Guaranteed to be non-nil.
-// Panics if not called on a KeyValue node, or if the Children are malformed.
-func (n *Node) Value() *Node {
-	assertKind(KeyValue, *n)
-	return n.Child()
-}
-
-// Children returns an iterator over a node's children.
-func (n *Node) Children() Iterator {
-	return Iterator{node: n.Child()}
-}
-
-func assertKind(k Kind, n Node) {
-	if n.Kind != k {
-		panic(fmt.Errorf("method was expecting a %s, not a %s", k, n.Kind))
-	}
-}

internal/ast/builder.go

@@ -1,51 +0,0 @@
-package ast
-
-type Reference int
-
-const InvalidReference Reference = -1
-
-func (r Reference) Valid() bool {
-	return r != InvalidReference
-}
-
-type Builder struct {
-	tree    Root
-	lastIdx int
-}
-
-func (b *Builder) Tree() *Root {
-	return &b.tree
-}
-
-func (b *Builder) NodeAt(ref Reference) *Node {
-	return b.tree.at(ref)
-}
-
-func (b *Builder) Reset() {
-	b.tree.nodes = b.tree.nodes[:0]
-	b.lastIdx = 0
-}
-
-func (b *Builder) Push(n Node) Reference {
-	b.lastIdx = len(b.tree.nodes)
-	b.tree.nodes = append(b.tree.nodes, n)
-	return Reference(b.lastIdx)
-}
-
-func (b *Builder) PushAndChain(n Node) Reference {
-	newIdx := len(b.tree.nodes)
-	b.tree.nodes = append(b.tree.nodes, n)
-	if b.lastIdx >= 0 {
-		b.tree.nodes[b.lastIdx].next = newIdx - b.lastIdx
-	}
-	b.lastIdx = newIdx
-	return Reference(b.lastIdx)
-}
-
-func (b *Builder) AttachChild(parent Reference, child Reference) {
-	b.tree.nodes[parent].child = int(child) - int(parent)
-}
-
-func (b *Builder) Chain(from Reference, to Reference) {
-	b.tree.nodes[from].next = int(to) - int(from)
-}

internal/characters/ascii.go

@@ -0,0 +1,42 @@
+package characters
+
+var invalidAsciiTable = [256]bool{
+	0x00: true,
+	0x01: true,
+	0x02: true,
+	0x03: true,
+	0x04: true,
+	0x05: true,
+	0x06: true,
+	0x07: true,
+	0x08: true,
+	// 0x09 TAB
+	// 0x0A LF
+	0x0B: true,
+	0x0C: true,
+	// 0x0D CR
+	0x0E: true,
+	0x0F: true,
+	0x10: true,
+	0x11: true,
+	0x12: true,
+	0x13: true,
+	0x14: true,
+	0x15: true,
+	0x16: true,
+	0x17: true,
+	0x18: true,
+	0x19: true,
+	0x1A: true,
+	0x1B: true,
+	0x1C: true,
+	0x1D: true,
+	0x1E: true,
+	0x1F: true,
+	// 0x20 - 0x7E Printable ASCII characters
+	0x7F: true,
+}
+
+func InvalidAscii(b byte) bool {
+	return invalidAsciiTable[b]
+}

internal/characters/utf8.go

@@ -1,4 +1,4 @@
-package toml
+package characters
 
 import (
 	"unicode/utf8"
@@ -32,7 +32,7 @@ func (u utf8Err) Zero() bool {
 // 0x9 => tab, ok
 // 0xA - 0x1F => invalid
 // 0x7F => invalid
-func utf8TomlValidAlreadyEscaped(p []byte) (err utf8Err) {
+func Utf8TomlValidAlreadyEscaped(p []byte) (err utf8Err) {
 	// Fast path. Check for and skip 8 bytes of ASCII characters per iteration.
 	offset := 0
 	for len(p) >= 8 {
@@ -48,7 +48,7 @@ func utf8TomlValidAlreadyEscaped(p []byte) (err utf8Err) {
 		}
 
 		for i, b := range p[:8] {
-			if invalidAscii(b) {
+			if InvalidAscii(b) {
 				err.Index = offset + i
 				err.Size = 1
 				return
@@ -62,7 +62,7 @@ func utf8TomlValidAlreadyEscaped(p []byte) (err utf8Err) {
 	for i := 0; i < n; {
 		pi := p[i]
 		if pi < utf8.RuneSelf {
-			if invalidAscii(pi) {
+			if InvalidAscii(pi) {
 				err.Index = offset + i
 				err.Size = 1
 				return
@@ -106,11 +106,11 @@ func utf8TomlValidAlreadyEscaped(p []byte) (err utf8Err) {
 }
 
 // Return the size of the next rune if valid, 0 otherwise.
-func utf8ValidNext(p []byte) int {
+func Utf8ValidNext(p []byte) int {
 	c := p[0]
 
 	if c < utf8.RuneSelf {
-		if invalidAscii(c) {
+		if InvalidAscii(c) {
 			return 0
 		}
 		return 1
@@ -140,10 +140,6 @@ func utf8ValidNext(p []byte) int {
 	return size
 }
 
-func invalidAscii(b byte) bool {
-	return b <= 0x08 || (b > 0x0A && b < 0x0D) || (b > 0x0D && b <= 0x1F) || b == 0x7F
-}
-
 // acceptRange gives the range of valid values for the second byte in a UTF-8
 // sequence.
 type acceptRange struct {

internal/cli/cli.go

@@ -0,0 +1,87 @@
+package cli
+
+import (
+	"bytes"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/pelletier/go-toml/v2"
+)
+
+type ConvertFn func(r io.Reader, w io.Writer) error
+
+type Program struct {
+	Usage string
+	Fn    ConvertFn
+	// Inplace allows the command to take more than one file as argument and
+	// perform conversion in place on each provided file.
+	Inplace bool
+}
+
+func (p *Program) Execute() {
+	flag.Usage = func() { fmt.Fprint(os.Stderr, p.Usage) }
+	flag.Parse()
+	os.Exit(p.main(flag.Args(), os.Stdin, os.Stdout, os.Stderr))
+}
+
+func (p *Program) main(files []string, input io.Reader, output, error io.Writer) int {
+	err := p.run(files, input, output)
+	if err != nil {
+
+		var derr *toml.DecodeError
+		if errors.As(err, &derr) {
+			fmt.Fprintln(error, derr.String())
+			row, col := derr.Position()
+			fmt.Fprintln(error, "error occurred at row", row, "column", col)
+		} else {
+			fmt.Fprintln(error, err.Error())
+		}
+
+		return -1
+	}
+	return 0
+}
+
+func (p *Program) run(files []string, input io.Reader, output io.Writer) error {
+	if len(files) > 0 {
+		if p.Inplace {
+			return p.runAllFilesInPlace(files)
+		}
+		f, err := os.Open(files[0])
+		if err != nil {
+			return err
+		}
+		defer f.Close()
+		input = f
+	}
+	return p.Fn(input, output)
+}
+
+func (p *Program) runAllFilesInPlace(files []string) error {
+	for _, path := range files {
+		err := p.runFileInPlace(path)
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (p *Program) runFileInPlace(path string) error {
+	in, err := os.ReadFile(path)
+	if err != nil {
+		return err
+	}
+
+	out := new(bytes.Buffer)
+
+	err = p.Fn(bytes.NewReader(in), out)
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(path, out.Bytes(), 0600)
+}

internal/cli/cli_test.go

@@ -0,0 +1,170 @@
+package cli
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"os"
+	"path"
+	"strings"
+	"testing"
+
+	"github.com/pelletier/go-toml/v2"
+	"github.com/pelletier/go-toml/v2/internal/assert"
+)
+
+func processMain(args []string, input io.Reader, stdout, stderr io.Writer, f ConvertFn) int {
+	p := Program{Fn: f}
+	return p.main(args, input, stdout, stderr)
+}
+
+func TestProcessMainStdin(t *testing.T) {
+	stdout := new(bytes.Buffer)
+	stderr := new(bytes.Buffer)
+	input := strings.NewReader("this is the input")
+
+	exit := processMain([]string{}, input, stdout, stderr, func(r io.Reader, w io.Writer) error {
+		return nil
+	})
+
+	assert.Equal(t, 0, exit)
+	assert.Zero(t, stdout.String())
+	assert.Zero(t, stderr.String())
+}
+
+func TestProcessMainStdinErr(t *testing.T) {
+	stdout := new(bytes.Buffer)
+	stderr := new(bytes.Buffer)
+	input := strings.NewReader("this is the input")
+
+	exit := processMain([]string{}, input, stdout, stderr, func(r io.Reader, w io.Writer) error {
+		return fmt.Errorf("something bad")
+	})
+
+	assert.Equal(t, -1, exit)
+	assert.Zero(t, stdout.String())
+	assert.NotZero(t, stderr.String())
+}
+
+func TestProcessMainStdinDecodeErr(t *testing.T) {
+	stdout := new(bytes.Buffer)
+	stderr := new(bytes.Buffer)
+	input := strings.NewReader("this is the input")
+
+	exit := processMain([]string{}, input, stdout, stderr, func(r io.Reader, w io.Writer) error {
+		var v interface{}
+		return toml.Unmarshal([]byte(`qwe = 001`), &v)
+	})
+
+	assert.Equal(t, -1, exit)
+	assert.Zero(t, stdout.String())
+	assert.True(t, strings.Contains(stderr.String(), "error occurred at"))
+}
+
+func TestProcessMainFileExists(t *testing.T) {
+	tmpfile, err := os.CreateTemp("", "example")
+	assert.NoError(t, err)
+	defer os.Remove(tmpfile.Name())
+	_, err = tmpfile.Write([]byte(`some data`))
+	assert.NoError(t, err)
+
+	stdout := new(bytes.Buffer)
+	stderr := new(bytes.Buffer)
+
+	exit := processMain([]string{tmpfile.Name()}, nil, stdout, stderr, func(r io.Reader, w io.Writer) error {
+		return nil
+	})
+
+	assert.Equal(t, 0, exit)
+	assert.Zero(t, stdout.String())
+	assert.Zero(t, stderr.String())
+}
+
+func TestProcessMainFileDoesNotExist(t *testing.T) {
+	stdout := new(bytes.Buffer)
+	stderr := new(bytes.Buffer)
+
+	exit := processMain([]string{"/lets/hope/this/does/not/exist"}, nil, stdout, stderr, func(r io.Reader, w io.Writer) error {
+		return nil
+	})
+
+	assert.Equal(t, -1, exit)
+	assert.Zero(t, stdout.String())
+	assert.NotZero(t, stderr.String())
+}
+
+func TestProcessMainFilesInPlace(t *testing.T) {
+	dir, err := os.MkdirTemp("", "")
+	assert.NoError(t, err)
+	defer os.RemoveAll(dir)
+
+	path1 := path.Join(dir, "file1")
+	path2 := path.Join(dir, "file2")
+
+	err = os.WriteFile(path1, []byte("content 1"), 0600)
+	assert.NoError(t, err)
+	err = os.WriteFile(path2, []byte("content 2"), 0600)
+	assert.NoError(t, err)
+
+	p := Program{
+		Fn:      dummyFileFn,
+		Inplace: true,
+	}
+
+	exit := p.main([]string{path1, path2}, os.Stdin, os.Stdout, os.Stderr)
+
+	assert.Equal(t, 0, exit)
+
+	v1, err := os.ReadFile(path1)
+	assert.NoError(t, err)
+	assert.Equal(t, "1", string(v1))
+
+	v2, err := os.ReadFile(path2)
+	assert.NoError(t, err)
+	assert.Equal(t, "2", string(v2))
+}
+
+func TestProcessMainFilesInPlaceErrRead(t *testing.T) {
+	p := Program{
+		Fn:      dummyFileFn,
+		Inplace: true,
+	}
+
+	exit := p.main([]string{"/this/path/is/invalid"}, os.Stdin, os.Stdout, os.Stderr)
+
+	assert.Equal(t, -1, exit)
+}
+
+func TestProcessMainFilesInPlaceFailFn(t *testing.T) {
+	dir, err := os.MkdirTemp("", "")
+	assert.NoError(t, err)
+	defer os.RemoveAll(dir)
+
+	path1 := path.Join(dir, "file1")
+
+	err = os.WriteFile(path1, []byte("content 1"), 0600)
+	assert.NoError(t, err)
+
+	p := Program{
+		Fn:      func(io.Reader, io.Writer) error { return fmt.Errorf("oh no") },
+		Inplace: true,
+	}
+
+	exit := p.main([]string{path1}, os.Stdin, os.Stdout, os.Stderr)
+
+	assert.Equal(t, -1, exit)
+
+	v1, err := os.ReadFile(path1)
+	assert.NoError(t, err)
+	assert.Equal(t, "content 1", string(v1))
+}
+
+func dummyFileFn(r io.Reader, w io.Writer) error {
+	b, err := io.ReadAll(r)
+	if err != nil {
+		return err
+	}
+	v := strings.SplitN(string(b), " ", 2)[1]
+	_, err = w.Write([]byte(v))
+	return err
+}

internal/danger/danger_test.go

@@ -4,9 +4,7 @@ import (
 	"testing"
 	"unsafe"
 
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-
+	"github.com/pelletier/go-toml/v2/internal/assert"
 	"github.com/pelletier/go-toml/v2/internal/danger"
 )
 
@@ -72,7 +70,7 @@ func TestSubsliceOffsetInvalid(t *testing.T) {
 	for _, e := range examples {
 		t.Run(e.desc, func(t *testing.T) {
 			d, s := e.test()
-			require.Panics(t, func() {
+			assert.Panics(t, func() {
 				danger.SubsliceOffset(d, s)
 			})
 		})
@@ -83,9 +81,9 @@ func TestStride(t *testing.T) {
 	a := []byte{1, 2, 3, 4}
 	x := &a[1]
 	n := (*byte)(danger.Stride(unsafe.Pointer(x), unsafe.Sizeof(byte(0)), 1))
-	require.Equal(t, &a[2], n)
+	assert.Equal(t, &a[2], n)
 	n = (*byte)(danger.Stride(unsafe.Pointer(x), unsafe.Sizeof(byte(0)), -1))
-	require.Equal(t, &a[0], n)
+	assert.Equal(t, &a[0], n)
 }
 
 func TestBytesRange(t *testing.T) {
@@ -166,12 +164,12 @@ func TestBytesRange(t *testing.T) {
 		t.Run(e.desc, func(t *testing.T) {
 			start, end := e.test()
 			if e.expected == nil {
-				require.Panics(t, func() {
+				assert.Panics(t, func() {
 					danger.BytesRange(start, end)
 				})
 			} else {
 				res := danger.BytesRange(start, end)
-				require.Equal(t, e.expected, res)
+				assert.Equal(t, e.expected, res)
 			}
 		})
 	}

internal/danger/typeid.go

@@ -0,0 +1,23 @@
+package danger
+
+import (
+	"reflect"
+	"unsafe"
+)
+
+// typeID is used as key in encoder and decoder caches to enable using
+// the optimize runtime.mapaccess2_fast64 function instead of the more
+// expensive lookup if we were to use reflect.Type as map key.
+//
+// typeID holds the pointer to the reflect.Type value, which is unique
+// in the program.
+//
+// https://github.com/segmentio/encoding/blob/master/json/codec.go#L59-L61
+type TypeID unsafe.Pointer
+
+func MakeTypeID(t reflect.Type) TypeID {
+	// reflect.Type has the fields:
+	// typ unsafe.Pointer
+	// ptr unsafe.Pointer
+	return TypeID((*[2]unsafe.Pointer)(unsafe.Pointer(&t))[1])
+}

internal/imported_tests/marshal_imported_test.go

@@ -9,7 +9,7 @@ import (
 	"time"
 
 	"github.com/pelletier/go-toml/v2"
-	"github.com/stretchr/testify/require"
+	"github.com/pelletier/go-toml/v2/internal/assert"
 )
 
 func TestDocMarshal(t *testing.T) {
@@ -67,6 +67,7 @@ func TestDocMarshal(t *testing.T) {
 	}
 
 	marshalTestToml := `title = 'TOML Marshal Testing'
+
 [basic_lists]
 floats = [12.3, 45.6, 78.9]
 bools = [true, false, true]
@@ -89,7 +90,6 @@ name = 'Second'
 [subdoc.first]
 name = 'First'
 
-
 [basic]
 uint = 5001
 bool = true
@@ -101,33 +101,34 @@ date = 1979-05-27T07:32:00Z
 
 [[subdoclist]]
 name = 'List.First'
+
 [[subdoclist]]
 name = 'List.Second'
-
 `
 
 	result, err := toml.Marshal(docData)
-	require.NoError(t, err)
-	require.Equal(t, marshalTestToml, string(result))
+	assert.NoError(t, err)
+	assert.Equal(t, marshalTestToml, string(result))
 }
 
 func TestBasicMarshalQuotedKey(t *testing.T) {
 	result, err := toml.Marshal(quotedKeyMarshalTestData)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 
 	expected := `'Z.string-àéù' = 'Hello'
 'Yfloat-𝟘' = 3.5
+
 ['Xsubdoc-àéù']
 String2 = 'One'
 
 [['W.sublist-𝟘']]
 String2 = 'Two'
+
 [['W.sublist-𝟘']]
 String2 = 'Three'
-
 `
 
-	require.Equal(t, string(expected), string(result))
+	assert.Equal(t, string(expected), string(result))
 
 }
 
@@ -152,18 +153,18 @@ func TestEmptyMarshal(t *testing.T) {
 		Map:        map[string]string{},
 	}
 	result, err := toml.Marshal(doc)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 
 	expected := `title = 'Placeholder'
 bool = false
 int = 0
 string = ''
 stringlist = []
-[map]
 
+[map]
 `
 
-	require.Equal(t, string(expected), string(result))
+	assert.Equal(t, string(expected), string(result))
 }
 
 type textMarshaler struct {
@@ -186,13 +187,13 @@ func TestTextMarshaler(t *testing.T) {
 	t.Run("at root", func(t *testing.T) {
 		_, err := toml.Marshal(m)
 		// in v2 we do not allow TextMarshaler at root
-		require.Error(t, err)
+		assert.Error(t, err)
 	})
 
 	t.Run("leaf", func(t *testing.T) {
 		res, err := toml.Marshal(wrap{m})
-		require.NoError(t, err)
+		assert.NoError(t, err)
 
-		require.Equal(t, "TM = 'Sally Fields'\n", string(res))
+		assert.Equal(t, "TM = 'Sally Fields'\n", string(res))
 	})
 }

internal/imported_tests/unmarshal_imported_test.go

@@ -16,8 +16,7 @@ import (
 	"time"
 
 	"github.com/pelletier/go-toml/v2"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
+	"github.com/pelletier/go-toml/v2/internal/assert"
 )
 
 type basicMarshalTestStruct struct {
@@ -123,7 +122,7 @@ func TestInterface(t *testing.T) {
 	var config Conf
 	config.Inter = &NestedStruct{}
 	err := toml.Unmarshal(doc, &config)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	expected := Conf{
 		Name: "rui",
 		Age:  18,
@@ -139,8 +138,8 @@ func TestInterface(t *testing.T) {
 func TestBasicUnmarshal(t *testing.T) {
 	result := basicMarshalTestStruct{}
 	err := toml.Unmarshal(basicTestToml, &result)
-	require.NoError(t, err)
-	require.Equal(t, basicTestData, result)
+	assert.NoError(t, err)
+	assert.Equal(t, basicTestData, result)
 }
 
 type quotedKeyMarshalTestStruct struct {
@@ -151,6 +150,7 @@ type quotedKeyMarshalTestStruct struct {
 }
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var quotedKeyMarshalTestData = quotedKeyMarshalTestStruct{
 	String:  "Hello",
@@ -160,6 +160,7 @@ var quotedKeyMarshalTestData = quotedKeyMarshalTestStruct{
 }
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var quotedKeyMarshalTestToml = []byte(`"Yfloat-𝟘" = 3.5
 "Z.string-àéù" = "Hello"
@@ -272,6 +273,7 @@ var docData = testDoc{
 }
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var mapTestDoc = testMapDoc{
 	Title: "TOML Marshal Testing",
@@ -297,7 +299,7 @@ func TestDocUnmarshal(t *testing.T) {
 	result := testDoc{}
 	err := toml.Unmarshal(marshalTestToml, &result)
 	expected := docData
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	assert.Equal(t, expected, result)
 }
 
@@ -337,7 +339,7 @@ shouldntBeHere = 2
 func TestUnexportedUnmarshal(t *testing.T) {
 	result := unexportedMarshalTestStruct{}
 	err := toml.Unmarshal(unexportedTestToml, &result)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	assert.Equal(t, unexportedTestData, result)
 }
 
@@ -453,39 +455,10 @@ func TestEmptytomlUnmarshal(t *testing.T) {
 
 	result := emptyMarshalTestStruct{}
 	err := toml.Unmarshal(emptyTestToml, &result)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	assert.Equal(t, emptyTestData, result)
 }
 
-func TestEmptyUnmarshalOmit(t *testing.T) {
-	t.Skipf("Have not figured yet if omitempty is a good idea")
-
-	type emptyMarshalTestStruct2 struct {
-		Title      string                  `toml:"title"`
-		Bool       bool                    `toml:"bool,omitempty"`
-		Int        int                     `toml:"int, omitempty"`
-		String     string                  `toml:"string,omitempty "`
-		StringList []string                `toml:"stringlist,omitempty"`
-		Ptr        *basicMarshalTestStruct `toml:"ptr,omitempty"`
-		Map        map[string]string       `toml:"map,omitempty"`
-	}
-
-	emptyTestData2 := emptyMarshalTestStruct2{
-		Title:      "Placeholder",
-		Bool:       false,
-		Int:        0,
-		String:     "",
-		StringList: []string{},
-		Ptr:        nil,
-		Map:        map[string]string{},
-	}
-
-	result := emptyMarshalTestStruct2{}
-	err := toml.Unmarshal(emptyTestToml, &result)
-	require.NoError(t, err)
-	assert.Equal(t, emptyTestData2, result)
-}
-
 type pointerMarshalTestStruct struct {
 	Str       *string
 	List      *[]string
@@ -530,7 +503,7 @@ Str = "Hello"
 func TestPointerUnmarshal(t *testing.T) {
 	result := pointerMarshalTestStruct{}
 	err := toml.Unmarshal(pointerTestToml, &result)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	assert.Equal(t, pointerTestData, result)
 }
 
@@ -566,7 +539,7 @@ StringPtr = [["Three", "Four"]]
 func TestNestedUnmarshal(t *testing.T) {
 	result := nestedMarshalTestStruct{}
 	err := toml.Unmarshal(nestedTestToml, &result)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	assert.Equal(t, nestedTestData, result)
 }
 
@@ -588,10 +561,12 @@ func (c customMarshaler) MarshalTOML() ([]byte, error) {
 var customMarshalerData = customMarshaler{FirstName: "Sally", LastName: "Fields"}
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var customMarshalerToml = []byte(`Sally Fields`)
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var nestedCustomMarshalerData = customMarshalerParent{
 	Self:    customMarshaler{FirstName: "Maiku", LastName: "Suteda"},
@@ -599,6 +574,7 @@ var nestedCustomMarshalerData = customMarshalerParent{
 }
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var nestedCustomMarshalerToml = []byte(`friends = ["Sally Fields"]
 me = "Maiku Suteda"
@@ -640,6 +616,7 @@ func TestUnmarshalTextMarshaler(t *testing.T) {
 }
 
 // TODO: Remove nolint once type and methods are used by a test
+//
 //nolint:unused
 type precedentMarshaler struct {
 	FirstName string
@@ -658,6 +635,7 @@ func (m precedentMarshaler) MarshalTOML() ([]byte, error) {
 }
 
 // TODO: Remove nolint once type and method are used by a test
+//
 //nolint:unused
 type customPointerMarshaler struct {
 	FirstName string
@@ -670,6 +648,7 @@ func (m *customPointerMarshaler) MarshalTOML() ([]byte, error) {
 }
 
 // TODO: Remove nolint once type and method are used by a test
+//
 //nolint:unused
 type textPointerMarshaler struct {
 	FirstName string
@@ -682,6 +661,7 @@ func (m *textPointerMarshaler) MarshalText() ([]byte, error) {
 }
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var commentTestToml = []byte(`
 # it's a comment on type
@@ -719,6 +699,7 @@ type mapsTestStruct struct {
 }
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var mapsTestData = mapsTestStruct{
 	Simple: map[string]string{
@@ -742,6 +723,7 @@ var mapsTestData = mapsTestStruct{
 }
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var mapsTestToml = []byte(`
 [Other]
@@ -764,6 +746,7 @@ var mapsTestToml = []byte(`
 `)
 
 // TODO: Remove nolint once type is used by a test
+//
 //nolint:deadcode,unused
 type structArrayNoTag struct {
 	A struct {
@@ -773,6 +756,7 @@ type structArrayNoTag struct {
 }
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var customTagTestToml = []byte(`
 [postgres]
@@ -787,6 +771,7 @@ var customTagTestToml = []byte(`
 `)
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var customCommentTagTestToml = []byte(`
 # db connection
@@ -800,6 +785,7 @@ var customCommentTagTestToml = []byte(`
 `)
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var customCommentedTagTestToml = []byte(`
 [postgres]
@@ -847,13 +833,14 @@ func TestUnmarshalTabInStringAndQuotedKey(t *testing.T) {
 		t.Run(test.desc, func(t *testing.T) {
 			result := Test{}
 			err := toml.Unmarshal(test.input, &result)
-			require.NoError(t, err)
+			assert.NoError(t, err)
 			assert.Equal(t, test.expected, result)
 		})
 	}
 }
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var customMultilineTagTestToml = []byte(`int_slice = [
   1,
@@ -863,6 +850,7 @@ var customMultilineTagTestToml = []byte(`int_slice = [
 `)
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var testDocBasicToml = []byte(`
 [document]
@@ -875,12 +863,14 @@ var testDocBasicToml = []byte(`
 `)
 
 // TODO: Remove nolint once type is used by a test
+//
 //nolint:deadcode
 type testDocCustomTag struct {
 	Doc testDocBasicsCustomTag `file:"document"`
 }
 
 // TODO: Remove nolint once type is used by a test
+//
 //nolint:deadcode
 type testDocBasicsCustomTag struct {
 	Bool       bool      `file:"bool_val"`
@@ -893,6 +883,7 @@ type testDocBasicsCustomTag struct {
 }
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,varcheck
 var testDocCustomTagData = testDocCustomTag{
 	Doc: testDocBasicsCustomTag{
@@ -956,6 +947,29 @@ func TestUnmarshalMapWithTypedKey(t *testing.T) {
 	}
 }
 
+func TestUnmarshalTypeTableHeader(t *testing.T) {
+	testToml := []byte(`
+		[test]
+		a = 1
+		`)
+
+	type header string
+	var result map[header]map[string]int
+	err := toml.Unmarshal(testToml, &result)
+	if err != nil {
+		t.Errorf("Received unexpected error: %s", err)
+		return
+	}
+
+	expected := map[header]map[string]int{
+		"test": {"a": 1},
+	}
+
+	if !reflect.DeepEqual(result, expected) {
+		t.Errorf("Bad unmarshal: expected %v, got %v", expected, result)
+	}
+}
+
 func TestUnmarshalNonPointer(t *testing.T) {
 	a := 1
 	err := toml.Unmarshal([]byte{}, a)
@@ -972,6 +986,7 @@ func TestUnmarshalInvalidPointerKind(t *testing.T) {
 }
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused
 type testDuration struct {
 	Nanosec   time.Duration  `toml:"nanosec"`
@@ -986,6 +1001,7 @@ type testDuration struct {
 }
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var testDurationToml = []byte(`
 nanosec = "1ns"
@@ -1000,6 +1016,7 @@ a_string = "15s"
 `)
 
 // TODO: Remove nolint once var is used by a test
+//
 //nolint:deadcode,unused,varcheck
 var testDurationToml2 = []byte(`a_string = "15s"
 hour = "1h0m0s"
@@ -1013,6 +1030,7 @@ sec = "1s"
 `)
 
 // TODO: Remove nolint once type is used by a test
+//
 //nolint:deadcode,unused
 type testBadDuration struct {
 	Val time.Duration `toml:"val"`
@@ -1066,16 +1084,12 @@ func TestUnmarshalCheckConversionFloatInt(t *testing.T) {
 			desc:  "int",
 			input: `I = 1e300`,
 		},
-		{
-			desc:  "float",
-			input: `F = 9223372036854775806`,
-		},
 	}
 
 	for _, test := range testCases {
 		t.Run(test.desc, func(t *testing.T) {
 			err := toml.Unmarshal([]byte(test.input), &conversionCheck{})
-			require.Error(t, err)
+			assert.Error(t, err)
 		})
 	}
 }
@@ -1110,7 +1124,7 @@ func TestUnmarshalOverflow(t *testing.T) {
 	for _, test := range testCases {
 		t.Run(test.desc, func(t *testing.T) {
 			err := toml.Unmarshal([]byte(test.input), &overflow{})
-			require.Error(t, err)
+			assert.Error(t, err)
 		})
 	}
 }
@@ -1730,7 +1744,7 @@ Age = 23
 	}
 	actual := OuterStruct{}
 	err := toml.Unmarshal(doc, &actual)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	assert.Equal(t, expected, actual)
 }
 
@@ -1815,7 +1829,7 @@ InnerField = "After4"
 	}
 
 	err := toml.Unmarshal(doc, &actual)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	assert.Equal(t, expected, actual)
 }
 
@@ -1864,7 +1878,7 @@ type arrayTooSmallStruct struct {
 func TestUnmarshalSlice(t *testing.T) {
 	var actual sliceStruct
 	err := toml.Unmarshal(sliceTomlDemo, &actual)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	expected := sliceStruct{
 		Slice:          []string{"Howdy", "Hey There"},
 		SlicePtr:       &[]string{"Howdy", "Hey There"},
@@ -1915,7 +1929,7 @@ func TestUnmarshalMixedTypeSlice(t *testing.T) {
 		},
 	}
 	err := toml.Unmarshal(doc, &actual)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	assert.Equal(t, expected, actual)
 }
 
@@ -1924,7 +1938,7 @@ func TestUnmarshalArray(t *testing.T) {
 
 	var actual arrayStruct
 	err = toml.Unmarshal(sliceTomlDemo, &actual)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 
 	expected := arrayStruct{
 		Slice:          [4]string{"Howdy", "Hey There"},
@@ -1954,7 +1968,7 @@ func decoder(doc string) *toml.Decoder {
 
 func strictDecoder(doc string) *toml.Decoder {
 	d := decoder(doc)
-	d.SetStrict(true)
+	d.DisallowUnknownFields()
 	return d
 }
 
@@ -1983,8 +1997,13 @@ func TestDecoderStrict(t *testing.T) {
 	}
 
 	err := strictDecoder(input).Decode(&doc)
-	require.Error(t, err)
-	require.IsType(t, &toml.StrictMissingError{}, err)
+	assert.Error(t, err)
+
+	assert.Equal(t,
+		reflect.TypeOf(err), reflect.TypeOf(&toml.StrictMissingError{}),
+		"Expected a *toml.StrictMissingError, got: %v", reflect.TypeOf(err),
+	)
+
 	se := err.(*toml.StrictMissingError)
 
 	keys := []toml.Key{}
@@ -2000,10 +2019,10 @@ func TestDecoderStrict(t *testing.T) {
 		{"undecoded", "array"},
 	}
 
-	require.Equal(t, expectedKeys, keys)
+	assert.Equal(t, expectedKeys, keys)
 
 	err = decoder(input).Decode(&doc)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 
 	var m map[string]interface{}
 	err = decoder(input).Decode(&m)
@@ -2021,7 +2040,7 @@ func TestDecoderStrictValid(t *testing.T) {
 	}
 
 	err := strictDecoder(input).Decode(&doc)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 }
 
 type docUnmarshalTOML struct {
@@ -2072,7 +2091,7 @@ func TestCustomUnmarshal(t *testing.T) {
 
 	var d parent
 	err := toml.Unmarshal([]byte(input), &d)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	assert.Equal(t, "ok1", d.Doc.Decoded.Key)
 	assert.Equal(t, "ok2", d.DocPointer.Decoded.Key)
 }
@@ -2138,7 +2157,7 @@ Int = 21
 Float = 2.0
 `
 	err := toml.Unmarshal([]byte(input), &doc)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 	assert.Equal(t, 12, doc.UnixTime.Value)
 	assert.Equal(t, 42, doc.Version.Value)
 	assert.Equal(t, 1, doc.Bool.Value)
@@ -2208,7 +2227,10 @@ func TestUnmarshalEmptyInterface(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	require.IsType(t, map[string]interface{}{}, v)
+	assert.Equal(t,
+		reflect.TypeOf(map[string]interface{}{}), reflect.TypeOf(v),
+		"Expected map[string]interface{}{} type, got: %v", reflect.TypeOf(v),
+	)
 
 	x := v.(map[string]interface{})
 	assert.Equal(t, "pelletier", x["User"])
@@ -2261,7 +2283,7 @@ func (c *Custom) UnmarshalTOML(v interface{}) error {
 	return nil
 }
 
-func TestGithubIssue431(t *testing.T) {
+func TestGitHubIssue431(t *testing.T) {
 	doc := `key = "value"`
 	var c Config
 	if err := toml.Unmarshal([]byte(doc), &c); err != nil {
@@ -2299,7 +2321,7 @@ type config437 struct {
 	} `toml:"HTTP"`
 }
 
-func TestGithubIssue437(t *testing.T) {
+func TestGitHubIssue437(t *testing.T) {
 	t.Skipf("unmarshalTOML not implemented")
 	src := `
 [HTTP]

internal/testsuite/rm.go

@@ -4,6 +4,8 @@ import (
 	"fmt"
 	"strconv"
 	"time"
+
+	"github.com/pelletier/go-toml/v2"
 )
 
 // Remove JSON tags to a data structure as returned by toml-test.
@@ -40,7 +42,7 @@ func rmTag(typedJson interface{}) (interface{}, error) {
 		}
 		return m, nil
 
-	// Array: remove tags from all itenm.
+	// Array: remove tags from all items.
 	case []interface{}:
 		a := make([]interface{}, len(v))
 		for i := range v {
@@ -76,14 +78,31 @@ func untag(typed map[string]interface{}) (interface{}, error) {
 			return nil, fmt.Errorf("untag: %w", err)
 		}
 		return f, nil
+
+		//toml.LocalDate{Year:2020, Month:12, Day:12}
 	case "datetime":
-		return parseTime(v, "2006-01-02T15:04:05.999999999Z07:00", false)
+		return time.Parse("2006-01-02T15:04:05.999999999Z07:00", v)
 	case "datetime-local":
-		return parseTime(v, "2006-01-02T15:04:05.999999999", true)
+		var t toml.LocalDateTime
+		err := t.UnmarshalText([]byte(v))
+		if err != nil {
+			return nil, fmt.Errorf("untag: %w", err)
+		}
+		return t, nil
 	case "date-local":
-		return parseTime(v, "2006-01-02", true)
+		var t toml.LocalDate
+		err := t.UnmarshalText([]byte(v))
+		if err != nil {
+			return nil, fmt.Errorf("untag: %w", err)
+		}
+		return t, nil
 	case "time-local":
-		return parseTime(v, "15:04:05.999999999", true)
+		var t toml.LocalTime
+		err := t.UnmarshalText([]byte(v))
+		if err != nil {
+			return nil, fmt.Errorf("untag: %w", err)
+		}
+		return t, nil
 	case "bool":
 		switch v {
 		case "true":

internal/testsuite/testsuite.go

@@ -10,7 +10,7 @@ import (
 	"github.com/pelletier/go-toml/v2"
 )
 
-// Marshal is a helpfer function for calling toml.Marshal
+// Marshal is a helper function for calling toml.Marshal
 //
 // Only needed to avoid package import loops.
 func Marshal(v interface{}) ([]byte, error) {
@@ -43,8 +43,26 @@ func DecodeStdin() error {
 	j := json.NewEncoder(os.Stdout)
 	j.SetIndent("", "  ")
 	if err := j.Encode(addTag("", decoded)); err != nil {
-		fmt.Errorf("Error encoding JSON: %s", err)
+		return fmt.Errorf("Error encoding JSON: %s", err)
 	}
 
 	return nil
 }
+
+// EncodeStdin is a helper function for the toml-test binary interface.  Tagged
+// JSON is read from STDIN and a resulting TOML representation is written to
+// STDOUT.
+func EncodeStdin() error {
+	var j interface{}
+	err := json.NewDecoder(os.Stdin).Decode(&j)
+	if err != nil {
+		return err
+	}
+
+	rm, err := rmTag(j)
+	if err != nil {
+		return fmt.Errorf("removing tags: %w", err)
+	}
+
+	return toml.NewEncoder(os.Stdout).Encode(rm)
+}

internal/tracker/key.go

@@ -1,8 +1,6 @@
 package tracker
 
-import (
-	"github.com/pelletier/go-toml/v2/internal/ast"
-)
+import "github.com/pelletier/go-toml/v2/unstable"
 
 // KeyTracker is a tracker that keeps track of the current Key as the AST is
 // walked.
@@ -11,19 +9,19 @@ type KeyTracker struct {
 }
 
 // UpdateTable sets the state of the tracker with the AST table node.
-func (t *KeyTracker) UpdateTable(node *ast.Node) {
+func (t *KeyTracker) UpdateTable(node *unstable.Node) {
 	t.reset()
 	t.Push(node)
 }
 
 // UpdateArrayTable sets the state of the tracker with the AST array table node.
-func (t *KeyTracker) UpdateArrayTable(node *ast.Node) {
+func (t *KeyTracker) UpdateArrayTable(node *unstable.Node) {
 	t.reset()
 	t.Push(node)
 }
 
 // Push the given key on the stack.
-func (t *KeyTracker) Push(node *ast.Node) {
+func (t *KeyTracker) Push(node *unstable.Node) {
 	it := node.Key()
 	for it.Next() {
 		t.k = append(t.k, string(it.Node().Data))
@@ -31,7 +29,7 @@ func (t *KeyTracker) Push(node *ast.Node) {
 }
 
 // Pop key from stack.
-func (t *KeyTracker) Pop(node *ast.Node) {
+func (t *KeyTracker) Pop(node *unstable.Node) {
 	it := node.Key()
 	for it.Next() {
 		t.k = t.k[:len(t.k)-1]

internal/tracker/seen.go

@@ -3,8 +3,9 @@ package tracker
 import (
 	"bytes"
 	"fmt"
+	"sync"
 
-	"github.com/pelletier/go-toml/v2/internal/ast"
+	"github.com/pelletier/go-toml/v2/unstable"
 )
 
 type keyKind uint8
@@ -54,80 +55,130 @@ func (k keyKind) String() string {
 type SeenTracker struct {
 	entries    []entry
 	currentIdx int
-	nextID     int
+}
+
+var pool = sync.Pool{
+	New: func() interface{} {
+		return &SeenTracker{}
+	},
+}
+
+func (s *SeenTracker) reset() {
+	// Always contains a root element at index 0.
+	s.currentIdx = 0
+	if len(s.entries) == 0 {
+		s.entries = make([]entry, 1, 2)
+	} else {
+		s.entries = s.entries[:1]
+	}
+	s.entries[0].child = -1
+	s.entries[0].next = -1
 }
 
 type entry struct {
-	id       int
-	parent   int
+	// Use -1 to indicate no child or no sibling.
+	child int
+	next  int
+
 	name     []byte
 	kind     keyKind
 	explicit bool
+	kv       bool
 }
 
-// Remove all descendent of node at position idx.
-func (s *SeenTracker) clear(idx int) {
-	p := s.entries[idx].id
-	rest := clear(p, s.entries[idx+1:])
-	s.entries = s.entries[:idx+1+len(rest)]
-}
-
-func clear(parentID int, entries []entry) []entry {
-	for i := 0; i < len(entries); {
-		if entries[i].parent == parentID {
-			id := entries[i].id
-			copy(entries[i:], entries[i+1:])
-			entries = entries[:len(entries)-1]
-			rest := clear(id, entries[i:])
-			entries = entries[:i+len(rest)]
-		} else {
-			i++
+// Find the index of the child of parentIdx with key k. Returns -1 if
+// it does not exist.
+func (s *SeenTracker) find(parentIdx int, k []byte) int {
+	for i := s.entries[parentIdx].child; i >= 0; i = s.entries[i].next {
+		if bytes.Equal(s.entries[i].name, k) {
+			return i
 		}
 	}
-	return entries
+	return -1
 }
 
-func (s *SeenTracker) create(parentIdx int, name []byte, kind keyKind, explicit bool) int {
-	parentID := s.id(parentIdx)
+// Remove all descendants of node at position idx.
+func (s *SeenTracker) clear(idx int) {
+	if idx >= len(s.entries) {
+		return
+	}
+
+	for i := s.entries[idx].child; i >= 0; {
+		next := s.entries[i].next
+		n := s.entries[0].next
+		s.entries[0].next = i
+		s.entries[i].next = n
+		s.entries[i].name = nil
+		s.clear(i)
+		i = next
+	}
+
+	s.entries[idx].child = -1
+}
+
+func (s *SeenTracker) create(parentIdx int, name []byte, kind keyKind, explicit bool, kv bool) int {
+	e := entry{
+		child: -1,
+		next:  s.entries[parentIdx].child,
 
-	idx := len(s.entries)
-	s.entries = append(s.entries, entry{
-		id:       s.nextID,
-		parent:   parentID,
 		name:     name,
 		kind:     kind,
 		explicit: explicit,
-	})
-	s.nextID++
+		kv:       kv,
+	}
+	var idx int
+	if s.entries[0].next >= 0 {
+		idx = s.entries[0].next
+		s.entries[0].next = s.entries[idx].next
+		s.entries[idx] = e
+	} else {
+		idx = len(s.entries)
+		s.entries = append(s.entries, e)
+	}
+
+	s.entries[parentIdx].child = idx
+
 	return idx
 }
 
-// CheckExpression takes a top-level node and checks that it does not contain keys
-// that have been seen in previous calls, and validates that types are consistent.
-func (s *SeenTracker) CheckExpression(node *ast.Node) error {
+func (s *SeenTracker) setExplicitFlag(parentIdx int) {
+	for i := s.entries[parentIdx].child; i >= 0; i = s.entries[i].next {
+		if s.entries[i].kv {
+			s.entries[i].explicit = true
+			s.entries[i].kv = false
+		}
+		s.setExplicitFlag(i)
+	}
+}
+
+// CheckExpression takes a top-level node and checks that it does not contain
+// keys that have been seen in previous calls, and validates that types are
+// consistent. It returns true if it is the first time this node's key is seen.
+// Useful to clear array tables on first use.
+func (s *SeenTracker) CheckExpression(node *unstable.Node) (bool, error) {
 	if s.entries == nil {
-		// Skip ID = 0 to remove the confusion between nodes whose parent has
-		// id 0 and root nodes (parent id is 0 because it's the zero value).
-		s.nextID = 1
-		// Start unscoped, so idx is negative.
-		s.currentIdx = -1
+		s.reset()
 	}
 	switch node.Kind {
-	case ast.KeyValue:
+	case unstable.KeyValue:
 		return s.checkKeyValue(node)
-	case ast.Table:
+	case unstable.Table:
 		return s.checkTable(node)
-	case ast.ArrayTable:
+	case unstable.ArrayTable:
 		return s.checkArrayTable(node)
 	default:
 		panic(fmt.Errorf("this should not be a top level node type: %s", node.Kind))
 	}
 }
 
-func (s *SeenTracker) checkTable(node *ast.Node) error {
+func (s *SeenTracker) checkTable(node *unstable.Node) (bool, error) {
+	if s.currentIdx >= 0 {
+		s.setExplicitFlag(s.currentIdx)
+	}
+
 	it := node.Key()
 
-	parentIdx := -1
+	parentIdx := 0
 
 	// This code is duplicated in checkArrayTable. This is because factoring
 	// it in a function requires to copy the iterator, or allocate it to the
@@ -142,7 +193,12 @@ func (s *SeenTracker) checkTable(node *ast.Node) error {
 		idx := s.find(parentIdx, k)
 
 		if idx < 0 {
-			idx = s.create(parentIdx, k, tableKind, false)
+			idx = s.create(parentIdx, k, tableKind, false, false)
+		} else {
+			entry := s.entries[idx]
+			if entry.kind == valueKind {
+				return false, fmt.Errorf("toml: expected %s to be a table, not a %s", string(k), entry.kind)
+			}
 		}
 		parentIdx = idx
 	}
@@ -150,28 +206,34 @@ func (s *SeenTracker) checkTable(node *ast.Node) error {
 	k := it.Node().Data
 	idx := s.find(parentIdx, k)
 
+	first := false
 	if idx >= 0 {
 		kind := s.entries[idx].kind
 		if kind != tableKind {
-			return fmt.Errorf("toml: key %s should be a table, not a %s", string(k), kind)
+			return false, fmt.Errorf("toml: key %s should be a table, not a %s", string(k), kind)
 		}
 		if s.entries[idx].explicit {
-			return fmt.Errorf("toml: table %s already exists", string(k))
+			return false, fmt.Errorf("toml: table %s already exists", string(k))
 		}
 		s.entries[idx].explicit = true
 	} else {
-		idx = s.create(parentIdx, k, tableKind, true)
+		idx = s.create(parentIdx, k, tableKind, true, false)
+		first = true
 	}
 
 	s.currentIdx = idx
 
-	return nil
+	return first, nil
 }
 
-func (s *SeenTracker) checkArrayTable(node *ast.Node) error {
+func (s *SeenTracker) checkArrayTable(node *unstable.Node) (bool, error) {
+	if s.currentIdx >= 0 {
+		s.setExplicitFlag(s.currentIdx)
+	}
+
 	it := node.Key()
 
-	parentIdx := -1
+	parentIdx := 0
 
 	for it.Next() {
 		if it.IsLast() {
@@ -183,77 +245,114 @@ func (s *SeenTracker) checkArrayTable(node *ast.Node) error {
 		idx := s.find(parentIdx, k)
 
 		if idx < 0 {
-			idx = s.create(parentIdx, k, tableKind, false)
+			idx = s.create(parentIdx, k, tableKind, false, false)
+		} else {
+			entry := s.entries[idx]
+			if entry.kind == valueKind {
+				return false, fmt.Errorf("toml: expected %s to be a table, not a %s", string(k), entry.kind)
+			}
 		}
+
 		parentIdx = idx
 	}
 
 	k := it.Node().Data
 	idx := s.find(parentIdx, k)
 
-	if idx >= 0 {
+	firstTime := idx < 0
+	if firstTime {
+		idx = s.create(parentIdx, k, arrayTableKind, true, false)
+	} else {
 		kind := s.entries[idx].kind
 		if kind != arrayTableKind {
-			return fmt.Errorf("toml: key %s already exists as a %s,  but should be an array table", kind, string(k))
+			return false, fmt.Errorf("toml: key %s already exists as a %s,  but should be an array table", kind, string(k))
 		}
 		s.clear(idx)
-	} else {
-		idx = s.create(parentIdx, k, arrayTableKind, true)
 	}
 
 	s.currentIdx = idx
 
-	return nil
+	return firstTime, nil
 }
 
-func (s *SeenTracker) checkKeyValue(node *ast.Node) error {
-	it := node.Key()
-
+func (s *SeenTracker) checkKeyValue(node *unstable.Node) (bool, error) {
 	parentIdx := s.currentIdx
+	it := node.Key()
 
 	for it.Next() {
 		k := it.Node().Data
 
 		idx := s.find(parentIdx, k)
 
-		if idx >= 0 {
-			if s.entries[idx].kind != tableKind {
-				return fmt.Errorf("toml: expected %s to be a table, not a %s", string(k), s.entries[idx].kind)
-			}
-			if s.entries[idx].explicit {
-				return fmt.Errorf("toml: cannot redefine table %s that has already been explicitly defined", string(k))
-			}
+		if idx < 0 {
+			idx = s.create(parentIdx, k, tableKind, false, true)
 		} else {
-			idx = s.create(parentIdx, k, tableKind, false)
+			entry := s.entries[idx]
+			if it.IsLast() {
+				return false, fmt.Errorf("toml: key %s is already defined", string(k))
+			} else if entry.kind != tableKind {
+				return false, fmt.Errorf("toml: expected %s to be a table, not a %s", string(k), entry.kind)
+			} else if entry.explicit {
+				return false, fmt.Errorf("toml: cannot redefine table %s that has already been explicitly defined", string(k))
+			}
 		}
+
 		parentIdx = idx
 	}
 
-	kind := valueKind
+	s.entries[parentIdx].kind = valueKind
 
-	if node.Value().Kind == ast.InlineTable {
-		kind = tableKind
+	value := node.Value()
+
+	switch value.Kind {
+	case unstable.InlineTable:
+		return s.checkInlineTable(value)
+	case unstable.Array:
+		return s.checkArray(value)
 	}
-	s.entries[parentIdx].kind = kind
 
-	return nil
+	return false, nil
 }
 
-func (s *SeenTracker) id(idx int) int {
-	if idx >= 0 {
-		return s.entries[idx].id
+func (s *SeenTracker) checkArray(node *unstable.Node) (first bool, err error) {
+	it := node.Children()
+	for it.Next() {
+		n := it.Node()
+		switch n.Kind {
+		case unstable.InlineTable:
+			first, err = s.checkInlineTable(n)
+			if err != nil {
+				return false, err
+			}
+		case unstable.Array:
+			first, err = s.checkArray(n)
+			if err != nil {
+				return false, err
+			}
+		}
 	}
-	return 0
+	return first, nil
 }
 
-func (s *SeenTracker) find(parentIdx int, k []byte) int {
-	parentID := s.id(parentIdx)
+func (s *SeenTracker) checkInlineTable(node *unstable.Node) (first bool, err error) {
+	s = pool.Get().(*SeenTracker)
+	s.reset()
 
-	for i := parentIdx + 1; i < len(s.entries); i++ {
-		if s.entries[i].parent == parentID && bytes.Equal(s.entries[i].name, k) {
-			return i
+	it := node.Children()
+	for it.Next() {
+		n := it.Node()
+		first, err = s.checkKeyValue(n)
+		if err != nil {
+			return false, err
 		}
 	}
 
-	return -1
+	// As inline tables are self-contained, the tracker does not
+	// need to retain the details of what they contain. The
+	// keyValue element that creates the inline table is kept to
+	// mark the presence of the inline table and prevent
+	// redefinition of its keys: check* functions cannot walk into
+	// a value.
+	pool.Put(s)
+	return first, nil
 }

internal/tracker/seen_test.go

@@ -0,0 +1,20 @@
+package tracker
+
+import (
+	"testing"
+	"unsafe"
+
+	"github.com/pelletier/go-toml/v2/internal/assert"
+)
+
+func TestEntrySize(t *testing.T) {
+	// Validate no regression on the size of entry{}. This is a critical bit for
+	// performance of unmarshaling documents. Should only be increased with care
+	// and a very good reason.
+	maxExpectedEntrySize := 48
+	assert.True(t,
+		int(unsafe.Sizeof(entry{})) <= maxExpectedEntrySize,
+		"Expected entry to be less than or equal to %d, got: %d",
+		maxExpectedEntrySize, int(unsafe.Sizeof(entry{})),
+	)
+}

localtime.go

@@ -4,6 +4,8 @@ import (
 	"fmt"
 	"strings"
 	"time"
+
+	"github.com/pelletier/go-toml/v2/unstable"
 )
 
 // LocalDate represents a calendar day in no specific timezone.
@@ -75,7 +77,7 @@ func (d LocalTime) MarshalText() ([]byte, error) {
 func (d *LocalTime) UnmarshalText(b []byte) error {
 	res, left, err := parseLocalTime(b)
 	if err == nil && len(left) != 0 {
-		err = newDecodeError(left, "extra characters")
+		err = unstable.NewParserError(left, "extra characters")
 	}
 	if err != nil {
 		return err
@@ -92,7 +94,13 @@ type LocalDateTime struct {
 
 // AsTime converts d into a specific time instance in zone.
 func (d LocalDateTime) AsTime(zone *time.Location) time.Time {
-	return time.Date(d.Year, time.Month(d.Month), d.Day, d.Hour, d.Minute, d.Second, d.Nanosecond, zone)
+	// Normalize leap seconds (second=60) to second=59 to prevent overflow
+	// when Go's time.Date normalizes the time.
+	second := d.Second
+	if second == 60 {
+		second = 59
+	}
+	return time.Date(d.Year, time.Month(d.Month), d.Day, d.Hour, d.Minute, second, d.Nanosecond, zone)
 }
 
 // String returns RFC 3339 representation of d.
@@ -109,7 +117,7 @@ func (d LocalDateTime) MarshalText() ([]byte, error) {
 func (d *LocalDateTime) UnmarshalText(data []byte) error {
 	res, left, err := parseLocalDateTime(data)
 	if err == nil && len(left) != 0 {
-		err = newDecodeError(left, "extra characters")
+		err = unstable.NewParserError(left, "extra characters")
 	}
 	if err != nil {
 		return err

localtime_test.go

@@ -5,73 +5,73 @@ import (
 	"time"
 
 	"github.com/pelletier/go-toml/v2"
-	"github.com/stretchr/testify/require"
+	"github.com/pelletier/go-toml/v2/internal/assert"
 )
 
 func TestLocalDate_AsTime(t *testing.T) {
 	d := toml.LocalDate{2021, 6, 8}
 	cast := d.AsTime(time.UTC)
-	require.Equal(t, time.Date(2021, time.June, 8, 0, 0, 0, 0, time.UTC), cast)
+	assert.Equal(t, time.Date(2021, time.June, 8, 0, 0, 0, 0, time.UTC), cast)
 }
 
 func TestLocalDate_String(t *testing.T) {
 	d := toml.LocalDate{2021, 6, 8}
-	require.Equal(t, "2021-06-08", d.String())
+	assert.Equal(t, "2021-06-08", d.String())
 }
 
 func TestLocalDate_MarshalText(t *testing.T) {
 	d := toml.LocalDate{2021, 6, 8}
 	b, err := d.MarshalText()
-	require.NoError(t, err)
-	require.Equal(t, []byte("2021-06-08"), b)
+	assert.NoError(t, err)
+	assert.Equal(t, []byte("2021-06-08"), b)
 }
 
 func TestLocalDate_UnmarshalMarshalText(t *testing.T) {
 	d := toml.LocalDate{}
 	err := d.UnmarshalText([]byte("2021-06-08"))
-	require.NoError(t, err)
-	require.Equal(t, toml.LocalDate{2021, 6, 8}, d)
+	assert.NoError(t, err)
+	assert.Equal(t, toml.LocalDate{2021, 6, 8}, d)
 
 	err = d.UnmarshalText([]byte("what"))
-	require.Error(t, err)
+	assert.Error(t, err)
 }
 
 func TestLocalTime_String(t *testing.T) {
 	d := toml.LocalTime{20, 12, 1, 2, 9}
-	require.Equal(t, "20:12:01.000000002", d.String())
+	assert.Equal(t, "20:12:01.000000002", d.String())
 	d = toml.LocalTime{20, 12, 1, 0, 0}
-	require.Equal(t, "20:12:01", d.String())
+	assert.Equal(t, "20:12:01", d.String())
 	d = toml.LocalTime{20, 12, 1, 0, 9}
-	require.Equal(t, "20:12:01.000000000", d.String())
+	assert.Equal(t, "20:12:01.000000000", d.String())
 	d = toml.LocalTime{20, 12, 1, 100, 0}
-	require.Equal(t, "20:12:01.0000001", d.String())
+	assert.Equal(t, "20:12:01.0000001", d.String())
 }
 
 func TestLocalTime_MarshalText(t *testing.T) {
 	d := toml.LocalTime{20, 12, 1, 2, 9}
 	b, err := d.MarshalText()
-	require.NoError(t, err)
-	require.Equal(t, []byte("20:12:01.000000002"), b)
+	assert.NoError(t, err)
+	assert.Equal(t, []byte("20:12:01.000000002"), b)
 }
 
 func TestLocalTime_UnmarshalMarshalText(t *testing.T) {
 	d := toml.LocalTime{}
 	err := d.UnmarshalText([]byte("20:12:01.000000002"))
-	require.NoError(t, err)
-	require.Equal(t, toml.LocalTime{20, 12, 1, 2, 9}, d)
+	assert.NoError(t, err)
+	assert.Equal(t, toml.LocalTime{20, 12, 1, 2, 9}, d)
 
 	err = d.UnmarshalText([]byte("what"))
-	require.Error(t, err)
+	assert.Error(t, err)
 
 	err = d.UnmarshalText([]byte("20:12:01.000000002 bad"))
-	require.Error(t, err)
+	assert.Error(t, err)
 }
 
 func TestLocalTime_RoundTrip(t *testing.T) {
 	var d struct{ A toml.LocalTime }
 	err := toml.Unmarshal([]byte("a=20:12:01.500"), &d)
-	require.NoError(t, err)
-	require.Equal(t, "20:12:01.500", d.A.String())
+	assert.NoError(t, err)
+	assert.Equal(t, "20:12:01.500", d.A.String())
 }
 
 func TestLocalDateTime_AsTime(t *testing.T) {
@@ -80,7 +80,7 @@ func TestLocalDateTime_AsTime(t *testing.T) {
 		toml.LocalTime{20, 12, 1, 2, 9},
 	}
 	cast := d.AsTime(time.UTC)
-	require.Equal(t, time.Date(2021, time.June, 8, 20, 12, 1, 2, time.UTC), cast)
+	assert.Equal(t, time.Date(2021, time.June, 8, 20, 12, 1, 2, time.UTC), cast)
 }
 
 func TestLocalDateTime_String(t *testing.T) {
@@ -88,7 +88,7 @@ func TestLocalDateTime_String(t *testing.T) {
 		toml.LocalDate{2021, 6, 8},
 		toml.LocalTime{20, 12, 1, 2, 9},
 	}
-	require.Equal(t, "2021-06-08T20:12:01.000000002", d.String())
+	assert.Equal(t, "2021-06-08T20:12:01.000000002", d.String())
 }
 
 func TestLocalDateTime_MarshalText(t *testing.T) {
@@ -97,22 +97,22 @@ func TestLocalDateTime_MarshalText(t *testing.T) {
 		toml.LocalTime{20, 12, 1, 2, 9},
 	}
 	b, err := d.MarshalText()
-	require.NoError(t, err)
-	require.Equal(t, []byte("2021-06-08T20:12:01.000000002"), b)
+	assert.NoError(t, err)
+	assert.Equal(t, []byte("2021-06-08T20:12:01.000000002"), b)
 }
 
 func TestLocalDateTime_UnmarshalMarshalText(t *testing.T) {
 	d := toml.LocalDateTime{}
 	err := d.UnmarshalText([]byte("2021-06-08 20:12:01.000000002"))
-	require.NoError(t, err)
-	require.Equal(t, toml.LocalDateTime{
+	assert.NoError(t, err)
+	assert.Equal(t, toml.LocalDateTime{
 		toml.LocalDate{2021, 6, 8},
 		toml.LocalTime{20, 12, 1, 2, 9},
 	}, d)
 
 	err = d.UnmarshalText([]byte("what"))
-	require.Error(t, err)
+	assert.Error(t, err)
 
 	err = d.UnmarshalText([]byte("2021-06-08 20:12:01.000000002 bad"))
-	require.Error(t, err)
+	assert.Error(t, err)
 }

marshaler.go

@@ -3,14 +3,18 @@ package toml
 import (
 	"bytes"
 	"encoding"
+	"encoding/json"
 	"fmt"
 	"io"
 	"math"
 	"reflect"
-	"sort"
+	"slices"
 	"strconv"
 	"strings"
 	"time"
+	"unicode"
+
+	"github.com/pelletier/go-toml/v2/internal/characters"
 )
 
 // Marshal serializes a Go value as a TOML document.
@@ -34,10 +38,11 @@ type Encoder struct {
 	w io.Writer
 
 	// global settings
-	tablesInline    bool
-	arraysMultiline bool
-	indentSymbol    string
-	indentTables    bool
+	tablesInline       bool
+	arraysMultiline    bool
+	indentSymbol       string
+	indentTables       bool
+	marshalJsonNumbers bool
 }
 
 // NewEncoder returns a new Encoder that writes to w.
@@ -53,9 +58,10 @@ func NewEncoder(w io.Writer) *Encoder {
 // This behavior can be controlled on an individual struct field basis with the
 // inline tag:
 //
-//   MyField `inline:"true"`
-func (enc *Encoder) SetTablesInline(inline bool) {
+//	MyField `toml:",inline"`
+func (enc *Encoder) SetTablesInline(inline bool) *Encoder {
 	enc.tablesInline = inline
+	return enc
 }
 
 // SetArraysMultiline forces the encoder to emit all arrays with one element per
@@ -63,28 +69,42 @@ func (enc *Encoder) SetTablesInline(inline bool) {
 //
 // This behavior can be controlled on an individual struct field basis with the multiline tag:
 //
-//   MyField `multiline:"true"`
-func (enc *Encoder) SetArraysMultiline(multiline bool) {
+//	MyField `multiline:"true"`
+func (enc *Encoder) SetArraysMultiline(multiline bool) *Encoder {
 	enc.arraysMultiline = multiline
+	return enc
 }
 
 // SetIndentSymbol defines the string that should be used for indentation. The
 // provided string is repeated for each indentation level. Defaults to two
 // spaces.
-func (enc *Encoder) SetIndentSymbol(s string) {
+func (enc *Encoder) SetIndentSymbol(s string) *Encoder {
 	enc.indentSymbol = s
+	return enc
 }
 
 // SetIndentTables forces the encoder to intent tables and array tables.
-func (enc *Encoder) SetIndentTables(indent bool) {
+func (enc *Encoder) SetIndentTables(indent bool) *Encoder {
 	enc.indentTables = indent
+	return enc
+}
+
+// SetMarshalJsonNumbers forces the encoder to serialize `json.Number` as a
+// float or integer instead of relying on TextMarshaler to emit a string.
+//
+// *Unstable:* This method does not follow the compatibility guarantees of
+// semver. It can be changed or removed without a new major version being
+// issued.
+func (enc *Encoder) SetMarshalJsonNumbers(indent bool) *Encoder {
+	enc.marshalJsonNumbers = indent
+	return enc
 }
 
 // Encode writes a TOML representation of v to the stream.
 //
 // If v cannot be represented to TOML it returns an error.
 //
-// Encoding rules
+// # Encoding rules
 //
 // A top level slice containing only maps or structs is encoded as [[table
 // array]].
@@ -99,27 +119,57 @@ func (enc *Encoder) SetIndentTables(indent bool) {
 // Intermediate tables are always printed.
 //
 // By default, strings are encoded as literal string, unless they contain either
-// a newline character or a single quote. In that case they are emitted as quoted
-// strings.
+// a newline character or a single quote. In that case they are emitted as
+// quoted strings.
+//
+// Unsigned integers larger than math.MaxInt64 cannot be encoded. Doing so
+// results in an error. This rule exists because the TOML specification only
+// requires parsers to support at least the 64 bits integer range. Allowing
+// larger numbers would create non-standard TOML documents, which may not be
+// readable (at best) by other implementations. To encode such numbers, a
+// solution is a custom type that implements encoding.TextMarshaler.
 //
 // When encoding structs, fields are encoded in order of definition, with their
 // exact name.
 //
-// Struct tags
+// Tables and array tables are separated by empty lines. However, consecutive
+// subtables definitions are not. For example:
 //
-// The following struct tags are available to tweak encoding on a per-field
-// basis:
+//	[top1]
 //
-//   toml:"foo"
-//     Changes the name of the key to use for the field to foo.
+//	[top2]
+//	[top2.child1]
 //
-//   multiline:"true"
-//     When the field contains a string, it will be emitted as a quoted
-//     multi-line TOML string.
+//	[[array]]
 //
-//   inline:"true"
-//     When the field would normally be encoded as a table, it is instead
-//     encoded as an inline table.
+//	[[array]]
+//	[array.child2]
+//
+// # Struct tags
+//
+// The encoding of each public struct field can be customized by the format
+// string in the "toml" key of the struct field's tag. This follows
+// encoding/json's convention. The format string starts with the name of the
+// field, optionally followed by a comma-separated list of options. The name may
+// be empty in order to provide options without overriding the default name.
+//
+// The "multiline" option emits strings as quoted multi-line TOML strings. It
+// has no effect on fields that would not be encoded as strings.
+//
+// The "inline" option turns fields that would be emitted as tables into inline
+// tables instead. It has no effect on other fields.
+//
+// The "omitempty" option prevents empty values or groups from being emitted.
+//
+// The "omitzero" option prevents zero values or groups from being emitted.
+//
+// The "commented" option prefixes the value and all its children with a comment
+// symbol.
+//
+// In addition to the "toml" tag struct tag, a "comment" tag can be used to emit
+// a TOML comment before the value being annotated. Comments are ignored inside
+// inline tables. For array tables, the comment is only present before the first
+// element of the array.
 func (enc *Encoder) Encode(v interface{}) error {
 	var (
 		b   []byte
@@ -147,6 +197,10 @@ func (enc *Encoder) Encode(v interface{}) error {
 
 type valueOptions struct {
 	multiline bool
+	omitempty bool
+	omitzero  bool
+	commented bool
+	comment   string
 }
 
 type encoderCtx struct {
@@ -171,6 +225,9 @@ type encoderCtx struct {
 	// Indentation level
 	indent int
 
+	// Prefix the current value with a comment.
+	commented bool
+
 	// Options coming from struct tags
 	options valueOptions
 }
@@ -196,16 +253,41 @@ func (ctx *encoderCtx) isRoot() bool {
 	return len(ctx.parentKey) == 0 && !ctx.hasKey
 }
 
-//nolint:cyclop,funlen
 func (enc *Encoder) encode(b []byte, ctx encoderCtx, v reflect.Value) ([]byte, error) {
-	if !v.IsZero() {
-		i, ok := v.Interface().(time.Time)
-		if ok {
-			return i.AppendFormat(b, time.RFC3339), nil
+	i := v.Interface()
+
+	switch x := i.(type) {
+	case time.Time:
+		if x.Nanosecond() > 0 {
+			return x.AppendFormat(b, time.RFC3339Nano), nil
+		}
+		return x.AppendFormat(b, time.RFC3339), nil
+	case LocalTime:
+		return append(b, x.String()...), nil
+	case LocalDate:
+		return append(b, x.String()...), nil
+	case LocalDateTime:
+		return append(b, x.String()...), nil
+	case json.Number:
+		if enc.marshalJsonNumbers {
+			if x == "" { /// Useful zero value.
+				return append(b, "0"...), nil
+			} else if v, err := x.Int64(); err == nil {
+				return enc.encode(b, ctx, reflect.ValueOf(v))
+			} else if f, err := x.Float64(); err == nil {
+				return enc.encode(b, ctx, reflect.ValueOf(f))
+			} else {
+				return nil, fmt.Errorf("toml: unable to convert %q to int64 or float64", x)
+			}
 		}
 	}
 
-	if v.Type().Implements(textMarshalerType) {
+	hasTextMarshaler := v.Type().Implements(textMarshalerType)
+	if hasTextMarshaler || (v.CanAddr() && reflect.PointerTo(v.Type()).Implements(textMarshalerType)) {
+		if !hasTextMarshaler {
+			v = v.Addr()
+		}
+
 		if ctx.isRoot() {
 			return nil, fmt.Errorf("toml: type %s implementing the TextMarshaler interface cannot be a root element", v.Type())
 		}
@@ -226,7 +308,7 @@ func (enc *Encoder) encode(b []byte, ctx encoderCtx, v reflect.Value) ([]byte, e
 		return enc.encodeMap(b, ctx, v)
 	case reflect.Struct:
 		return enc.encodeStruct(b, ctx, v)
-	case reflect.Slice:
+	case reflect.Slice, reflect.Array:
 		return enc.encodeSlice(b, ctx, v)
 	case reflect.Interface:
 		if v.IsNil() {
@@ -245,16 +327,31 @@ func (enc *Encoder) encode(b []byte, ctx encoderCtx, v reflect.Value) ([]byte, e
 	case reflect.String:
 		b = enc.encodeString(b, v.String(), ctx.options)
 	case reflect.Float32:
-		if math.Trunc(v.Float()) == v.Float() {
-			b = strconv.AppendFloat(b, v.Float(), 'f', 1, 32)
+		f := v.Float()
+
+		if math.IsNaN(f) {
+			b = append(b, "nan"...)
+		} else if f > math.MaxFloat32 {
+			b = append(b, "inf"...)
+		} else if f < -math.MaxFloat32 {
+			b = append(b, "-inf"...)
+		} else if math.Trunc(f) == f {
+			b = strconv.AppendFloat(b, f, 'f', 1, 32)
 		} else {
-			b = strconv.AppendFloat(b, v.Float(), 'f', -1, 32)
+			b = strconv.AppendFloat(b, f, 'f', -1, 32)
 		}
 	case reflect.Float64:
-		if math.Trunc(v.Float()) == v.Float() {
-			b = strconv.AppendFloat(b, v.Float(), 'f', 1, 64)
+		f := v.Float()
+		if math.IsNaN(f) {
+			b = append(b, "nan"...)
+		} else if f > math.MaxFloat64 {
+			b = append(b, "inf"...)
+		} else if f < -math.MaxFloat64 {
+			b = append(b, "-inf"...)
+		} else if math.Trunc(f) == f {
+			b = strconv.AppendFloat(b, f, 'f', 1, 64)
 		} else {
-			b = strconv.AppendFloat(b, v.Float(), 'f', -1, 64)
+			b = strconv.AppendFloat(b, f, 'f', -1, 64)
 		}
 	case reflect.Bool:
 		if v.Bool() {
@@ -263,7 +360,11 @@ func (enc *Encoder) encode(b []byte, ctx encoderCtx, v reflect.Value) ([]byte, e
 			b = append(b, "false"...)
 		}
 	case reflect.Uint64, reflect.Uint32, reflect.Uint16, reflect.Uint8, reflect.Uint:
-		b = strconv.AppendUint(b, v.Uint(), 10)
+		x := v.Uint()
+		if x > uint64(math.MaxInt64) {
+			return nil, fmt.Errorf("toml: not encoding uint (%d) greater than max int64 (%d)", x, int64(math.MaxInt64))
+		}
+		b = strconv.AppendUint(b, x, 10)
 	case reflect.Int64, reflect.Int32, reflect.Int16, reflect.Int8, reflect.Int:
 		b = strconv.AppendInt(b, v.Int(), 10)
 	default:
@@ -282,19 +383,24 @@ func isNil(v reflect.Value) bool {
 	}
 }
 
+func shouldOmitEmpty(options valueOptions, v reflect.Value) bool {
+	return options.omitempty && isEmptyValue(v)
+}
+
+func shouldOmitZero(options valueOptions, v reflect.Value) bool {
+	return options.omitzero && v.IsZero()
+}
+
 func (enc *Encoder) encodeKv(b []byte, ctx encoderCtx, options valueOptions, v reflect.Value) ([]byte, error) {
 	var err error
 
-	if !ctx.hasKey {
-		panic("caller of encodeKv should have set the key in the context")
-	}
-	b = enc.indent(ctx.indent, b)
-
-	b, err = enc.encodeKey(b, ctx.key)
-	if err != nil {
-		return nil, err
+	if !ctx.inline {
+		b = enc.encodeComment(ctx.indent, options.comment, b)
+		b = enc.commented(ctx.commented, b)
+		b = enc.indent(ctx.indent, b)
 	}
 
+	b = enc.encodeKey(b, ctx.key)
 	b = append(b, " = "...)
 
 	// create a copy of the context because the value of a KV shouldn't
@@ -312,6 +418,61 @@ func (enc *Encoder) encodeKv(b []byte, ctx encoderCtx, options valueOptions, v r
 	return b, nil
 }
 
+func (enc *Encoder) commented(commented bool, b []byte) []byte {
+	if commented {
+		return append(b, "# "...)
+	}
+	return b
+}
+
+func isEmptyValue(v reflect.Value) bool {
+	switch v.Kind() {
+	case reflect.Struct:
+		return isEmptyStruct(v)
+	case reflect.Array, reflect.Map, reflect.Slice, reflect.String:
+		return v.Len() == 0
+	case reflect.Bool:
+		return !v.Bool()
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return v.Int() == 0
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
+		return v.Uint() == 0
+	case reflect.Float32, reflect.Float64:
+		return v.Float() == 0
+	case reflect.Interface, reflect.Ptr:
+		return v.IsNil()
+	}
+	return false
+}
+
+func isEmptyStruct(v reflect.Value) bool {
+	// TODO: merge with walkStruct and cache.
+	typ := v.Type()
+	for i := 0; i < typ.NumField(); i++ {
+		fieldType := typ.Field(i)
+
+		// only consider exported fields
+		if fieldType.PkgPath != "" {
+			continue
+		}
+
+		tag := fieldType.Tag.Get("toml")
+
+		// special field name to skip field
+		if tag == "-" {
+			continue
+		}
+
+		f := v.Field(i)
+
+		if !isEmptyValue(f) {
+			return false
+		}
+	}
+
+	return true
+}
+
 const literalQuote = '\''
 
 func (enc *Encoder) encodeString(b []byte, v string, options valueOptions) []byte {
@@ -323,7 +484,13 @@ func (enc *Encoder) encodeString(b []byte, v string, options valueOptions) []byt
 }
 
 func needsQuoting(v string) bool {
-	return strings.ContainsAny(v, "'\b\f\n\r\t")
+	// TODO: vectorize
+	for _, b := range []byte(v) {
+		if b == '\'' || b == '\r' || b == '\n' || characters.InvalidAscii(b) {
+			return true
+		}
+	}
+	return false
 }
 
 // caller should have checked that the string does not contain new lines or ' .
@@ -335,7 +502,6 @@ func (enc *Encoder) encodeLiteralString(b []byte, v string) []byte {
 	return b
 }
 
-//nolint:cyclop
 func (enc *Encoder) encodeQuotedString(multiline bool, b []byte, v string) []byte {
 	stringQuote := `"`
 
@@ -358,12 +524,26 @@ func (enc *Encoder) encodeQuotedString(multiline bool, b []byte, v string) []byt
 		del = 0x7f
 	)
 
-	for _, r := range []byte(v) {
+	bv := []byte(v)
+	for i := 0; i < len(bv); i++ {
+		r := bv[i]
 		switch r {
 		case '\\':
 			b = append(b, `\\`...)
 		case '"':
-			b = append(b, `\"`...)
+			if multiline {
+				// Quotation marks do not need to be quoted in multiline strings unless
+				// it contains 3 consecutive. If 3+ quotes appear, quote all of them
+				// because it's visually better
+				if i+2 > len(bv) || bv[i+1] != '"' || bv[i+2] != '"' {
+					b = append(b, r)
+				} else {
+					b = append(b, `\"\"\"`...)
+					i += 2
+				}
+			} else {
+				b = append(b, `\"`...)
+			}
 		case '\b':
 			b = append(b, `\b`...)
 		case '\f':
@@ -395,7 +575,7 @@ func (enc *Encoder) encodeQuotedString(multiline bool, b []byte, v string) []byt
 	return b
 }
 
-// called should have checked that the string is in A-Z / a-z / 0-9 / - / _ .
+// caller should have checked that the string is in A-Z / a-z / 0-9 / - / _ .
 func (enc *Encoder) encodeUnquotedKey(b []byte, v string) []byte {
 	return append(b, v...)
 }
@@ -405,24 +585,19 @@ func (enc *Encoder) encodeTableHeader(ctx encoderCtx, b []byte) ([]byte, error)
 		return b, nil
 	}
 
+	b = enc.encodeComment(ctx.indent, ctx.options.comment, b)
+
+	b = enc.commented(ctx.commented, b)
+
 	b = enc.indent(ctx.indent, b)
 
 	b = append(b, '[')
 
-	var err error
-
-	b, err = enc.encodeKey(b, ctx.parentKey[0])
-	if err != nil {
-		return nil, err
-	}
+	b = enc.encodeKey(b, ctx.parentKey[0])
 
 	for _, k := range ctx.parentKey[1:] {
 		b = append(b, '.')
-
-		b, err = enc.encodeKey(b, k)
-		if err != nil {
-			return nil, err
-		}
+		b = enc.encodeKey(b, k)
 	}
 
 	b = append(b, "]\n"...)
@@ -431,19 +606,19 @@ func (enc *Encoder) encodeTableHeader(ctx encoderCtx, b []byte) ([]byte, error)
 }
 
 //nolint:cyclop
-func (enc *Encoder) encodeKey(b []byte, k string) ([]byte, error) {
+func (enc *Encoder) encodeKey(b []byte, k string) []byte {
 	needsQuotation := false
 	cannotUseLiteral := false
 
+	if len(k) == 0 {
+		return append(b, "''"...)
+	}
+
 	for _, c := range k {
 		if (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-' || c == '_' {
 			continue
 		}
 
-		if c == '\n' {
-			return nil, fmt.Errorf("toml: new line characters in keys are not supported")
-		}
-
 		if c == literalQuote {
 			cannotUseLiteral = true
 		}
@@ -451,21 +626,49 @@ func (enc *Encoder) encodeKey(b []byte, k string) ([]byte, error) {
 		needsQuotation = true
 	}
 
+	if needsQuotation && needsQuoting(k) {
+		cannotUseLiteral = true
+	}
+
 	switch {
 	case cannotUseLiteral:
-		return enc.encodeQuotedString(false, b, k), nil
+		return enc.encodeQuotedString(false, b, k)
 	case needsQuotation:
-		return enc.encodeLiteralString(b, k), nil
+		return enc.encodeLiteralString(b, k)
 	default:
-		return enc.encodeUnquotedKey(b, k), nil
+		return enc.encodeUnquotedKey(b, k)
 	}
 }
 
-func (enc *Encoder) encodeMap(b []byte, ctx encoderCtx, v reflect.Value) ([]byte, error) {
-	if v.Type().Key().Kind() != reflect.String {
-		return nil, fmt.Errorf("toml: type %s is not supported as a map key", v.Type().Key().Kind())
-	}
+func (enc *Encoder) keyToString(k reflect.Value) (string, error) {
+	keyType := k.Type()
+	switch {
+	case keyType.Kind() == reflect.String:
+		return k.String(), nil
 
+	case keyType.Implements(textMarshalerType):
+		keyB, err := k.Interface().(encoding.TextMarshaler).MarshalText()
+		if err != nil {
+			return "", fmt.Errorf("toml: error marshalling key %v from text: %w", k, err)
+		}
+		return string(keyB), nil
+
+	case keyType.Kind() == reflect.Int || keyType.Kind() == reflect.Int8 || keyType.Kind() == reflect.Int16 || keyType.Kind() == reflect.Int32 || keyType.Kind() == reflect.Int64:
+		return strconv.FormatInt(k.Int(), 10), nil
+
+	case keyType.Kind() == reflect.Uint || keyType.Kind() == reflect.Uint8 || keyType.Kind() == reflect.Uint16 || keyType.Kind() == reflect.Uint32 || keyType.Kind() == reflect.Uint64:
+		return strconv.FormatUint(k.Uint(), 10), nil
+
+	case keyType.Kind() == reflect.Float32:
+		return strconv.FormatFloat(k.Float(), 'f', -1, 32), nil
+
+	case keyType.Kind() == reflect.Float64:
+		return strconv.FormatFloat(k.Float(), 'f', -1, 64), nil
+	}
+	return "", fmt.Errorf("toml: type %s is not supported as a map key", keyType.Kind())
+}
+
+func (enc *Encoder) encodeMap(b []byte, ctx encoderCtx, v reflect.Value) ([]byte, error) {
 	var (
 		t                 table
 		emptyValueOptions valueOptions
@@ -473,13 +676,17 @@ func (enc *Encoder) encodeMap(b []byte, ctx encoderCtx, v reflect.Value) ([]byte
 
 	iter := v.MapRange()
 	for iter.Next() {
-		k := iter.Key().String()
 		v := iter.Value()
 
 		if isNil(v) {
 			continue
 		}
 
+		k, err := enc.keyToString(iter.Key())
+		if err != nil {
+			return nil, err
+		}
+
 		if willConvertToTableOrArrayTable(ctx, v) {
 			t.pushTable(k, v, emptyValueOptions)
 		} else {
@@ -494,8 +701,8 @@ func (enc *Encoder) encodeMap(b []byte, ctx encoderCtx, v reflect.Value) ([]byte
 }
 
 func sortEntriesByKey(e []entry) {
-	sort.Slice(e, func(i, j int) bool {
-		return e[i].Key < e[j].Key
+	slices.SortFunc(e, func(a, b entry) int {
+		return strings.Compare(a.Key, b.Key)
 	})
 }
 
@@ -511,18 +718,26 @@ type table struct {
 }
 
 func (t *table) pushKV(k string, v reflect.Value, options valueOptions) {
+	for _, e := range t.kvs {
+		if e.Key == k {
+			return
+		}
+	}
+
 	t.kvs = append(t.kvs, entry{Key: k, Value: v, Options: options})
 }
 
 func (t *table) pushTable(k string, v reflect.Value, options valueOptions) {
+	for _, e := range t.tables {
+		if e.Key == k {
+			return
+		}
+	}
 	t.tables = append(t.tables, entry{Key: k, Value: v, Options: options})
 }
 
-func (enc *Encoder) encodeStruct(b []byte, ctx encoderCtx, v reflect.Value) ([]byte, error) {
-	var t table
-
-	//nolint:godox
-	// TODO: cache this?
+func walkStruct(ctx encoderCtx, t *table, v reflect.Value) {
+	// TODO: cache this
 	typ := v.Type()
 	for i := 0; i < typ.NumField(); i++ {
 		fieldType := typ.Field(i)
@@ -532,45 +747,140 @@ func (enc *Encoder) encodeStruct(b []byte, ctx encoderCtx, v reflect.Value) ([]b
 			continue
 		}
 
-		k, ok := fieldType.Tag.Lookup("toml")
-		if !ok {
-			k = fieldType.Name
-		}
+		tag := fieldType.Tag.Get("toml")
 
 		// special field name to skip field
-		if k == "-" {
+		if tag == "-" {
 			continue
 		}
 
+		k, opts := parseTag(tag)
+		if !isValidName(k) {
+			k = ""
+		}
+
 		f := v.Field(i)
 
+		if k == "" {
+			if fieldType.Anonymous {
+				if fieldType.Type.Kind() == reflect.Struct {
+					walkStruct(ctx, t, f)
+				} else if fieldType.Type.Kind() == reflect.Ptr && !f.IsNil() && f.Elem().Kind() == reflect.Struct {
+					walkStruct(ctx, t, f.Elem())
+				}
+				continue
+			} else {
+				k = fieldType.Name
+			}
+		}
+
 		if isNil(f) {
 			continue
 		}
 
 		options := valueOptions{
-			multiline: fieldBoolTag(fieldType, "multiline"),
+			multiline: opts.multiline,
+			omitempty: opts.omitempty,
+			omitzero:  opts.omitzero,
+			commented: opts.commented,
+			comment:   fieldType.Tag.Get("comment"),
 		}
 
-		inline := fieldBoolTag(fieldType, "inline")
-
-		if inline || !willConvertToTableOrArrayTable(ctx, f) {
+		if opts.inline || !willConvertToTableOrArrayTable(ctx, f) {
 			t.pushKV(k, f, options)
 		} else {
 			t.pushTable(k, f, options)
 		}
 	}
+}
+
+func (enc *Encoder) encodeStruct(b []byte, ctx encoderCtx, v reflect.Value) ([]byte, error) {
+	var t table
+
+	walkStruct(ctx, &t, v)
 
 	return enc.encodeTable(b, ctx, t)
 }
 
-func fieldBoolTag(field reflect.StructField, tag string) bool {
-	x, ok := field.Tag.Lookup(tag)
-
-	return ok && x == "true"
+func (enc *Encoder) encodeComment(indent int, comment string, b []byte) []byte {
+	for len(comment) > 0 {
+		var line string
+		idx := strings.IndexByte(comment, '\n')
+		if idx >= 0 {
+			line = comment[:idx]
+			comment = comment[idx+1:]
+		} else {
+			line = comment
+			comment = ""
+		}
+		b = enc.indent(indent, b)
+		b = append(b, "# "...)
+		b = append(b, line...)
+		b = append(b, '\n')
+	}
+	return b
+}
+
+func isValidName(s string) bool {
+	if s == "" {
+		return false
+	}
+	for _, c := range s {
+		switch {
+		case strings.ContainsRune("!#$%&()*+-./:;<=>?@[]^_{|}~ ", c):
+			// Backslash and quote chars are reserved, but
+			// otherwise any punctuation chars are allowed
+			// in a tag name.
+		case !unicode.IsLetter(c) && !unicode.IsDigit(c):
+			return false
+		}
+	}
+	return true
+}
+
+type tagOptions struct {
+	multiline bool
+	inline    bool
+	omitempty bool
+	omitzero  bool
+	commented bool
+}
+
+func parseTag(tag string) (string, tagOptions) {
+	opts := tagOptions{}
+
+	idx := strings.Index(tag, ",")
+	if idx == -1 {
+		return tag, opts
+	}
+
+	raw := tag[idx+1:]
+	tag = tag[:idx]
+	for raw != "" {
+		var o string
+		i := strings.Index(raw, ",")
+		if i >= 0 {
+			o, raw = raw[:i], raw[i+1:]
+		} else {
+			o, raw = raw, ""
+		}
+		switch o {
+		case "multiline":
+			opts.multiline = true
+		case "inline":
+			opts.inline = true
+		case "omitempty":
+			opts.omitempty = true
+		case "omitzero":
+			opts.omitzero = true
+		case "commented":
+			opts.commented = true
+		}
+	}
+
+	return tag, opts
 }
 
-//nolint:cyclop
 func (enc *Encoder) encodeTable(b []byte, ctx encoderCtx, t table) ([]byte, error) {
 	var err error
 
@@ -592,10 +902,21 @@ func (enc *Encoder) encodeTable(b []byte, ctx encoderCtx, t table) ([]byte, erro
 	}
 	ctx.skipTableHeader = false
 
+	hasNonEmptyKV := false
 	for _, kv := range t.kvs {
-		ctx.setKey(kv.Key)
+		if shouldOmitEmpty(kv.Options, kv.Value) {
+			continue
+		}
+		if shouldOmitZero(kv.Options, kv.Value) {
+			continue
+		}
+		hasNonEmptyKV = true
 
-		b, err = enc.encodeKv(b, ctx, kv.Options, kv.Value)
+		ctx.setKey(kv.Key)
+		ctx2 := ctx
+		ctx2.commented = kv.Options.commented || ctx2.commented
+
+		b, err = enc.encodeKv(b, ctx2, kv.Options, kv.Value)
 		if err != nil {
 			return nil, err
 		}
@@ -603,17 +924,33 @@ func (enc *Encoder) encodeTable(b []byte, ctx encoderCtx, t table) ([]byte, erro
 		b = append(b, '\n')
 	}
 
+	first := true
 	for _, table := range t.tables {
+		if shouldOmitEmpty(table.Options, table.Value) {
+			continue
+		}
+		if shouldOmitZero(table.Options, table.Value) {
+			continue
+		}
+		if first {
+			first = false
+			if hasNonEmptyKV {
+				b = append(b, '\n')
+			}
+		} else {
+			b = append(b, "\n"...)
+		}
+
 		ctx.setKey(table.Key)
 
 		ctx.options = table.Options
+		ctx2 := ctx
+		ctx2.commented = ctx2.commented || ctx.options.commented
 
-		b, err = enc.encode(b, ctx, table.Value)
+		b, err = enc.encode(b, ctx2, table.Value)
 		if err != nil {
 			return nil, err
 		}
-
-		b = append(b, '\n')
 	}
 
 	return b, nil
@@ -626,6 +963,13 @@ func (enc *Encoder) encodeTableInline(b []byte, ctx encoderCtx, t table) ([]byte
 
 	first := true
 	for _, kv := range t.kvs {
+		if shouldOmitEmpty(kv.Options, kv.Value) {
+			continue
+		}
+		if shouldOmitZero(kv.Options, kv.Value) {
+			continue
+		}
+
 		if first {
 			first = false
 		} else {
@@ -641,7 +985,7 @@ func (enc *Encoder) encodeTableInline(b []byte, ctx encoderCtx, t table) ([]byte
 	}
 
 	if len(t.tables) > 0 {
-		panic("inline table cannot contain nested tables, online key-values")
+		panic("inline table cannot contain nested tables, only key-values")
 	}
 
 	b = append(b, "}"...)
@@ -653,7 +997,7 @@ func willConvertToTable(ctx encoderCtx, v reflect.Value) bool {
 	if !v.IsValid() {
 		return false
 	}
-	if v.Type() == timeType || v.Type().Implements(textMarshalerType) {
+	if v.Type() == timeType || v.Type().Implements(textMarshalerType) || (v.Kind() != reflect.Ptr && v.CanAddr() && reflect.PointerTo(v.Type()).Implements(textMarshalerType)) {
 		return false
 	}
 
@@ -675,13 +1019,16 @@ func willConvertToTable(ctx encoderCtx, v reflect.Value) bool {
 }
 
 func willConvertToTableOrArrayTable(ctx encoderCtx, v reflect.Value) bool {
+	if ctx.insideKv {
+		return false
+	}
 	t := v.Type()
 
 	if t.Kind() == reflect.Interface {
 		return willConvertToTableOrArrayTable(ctx, v.Elem())
 	}
 
-	if t.Kind() == reflect.Slice {
+	if t.Kind() == reflect.Slice || t.Kind() == reflect.Array {
 		if v.Len() == 0 {
 			// An empty slice should be a kv = [].
 			return false
@@ -720,8 +1067,14 @@ func (enc *Encoder) encodeSlice(b []byte, ctx encoderCtx, v reflect.Value) ([]by
 func (enc *Encoder) encodeSliceAsArrayTable(b []byte, ctx encoderCtx, v reflect.Value) ([]byte, error) {
 	ctx.shiftKey()
 
-	var err error
 	scratch := make([]byte, 0, 64)
+
+	scratch = enc.commented(ctx.commented, scratch)
+
+	if enc.indentTables {
+		scratch = enc.indent(ctx.indent, scratch)
+	}
+
 	scratch = append(scratch, "[["...)
 
 	for i, k := range ctx.parentKey {
@@ -729,18 +1082,26 @@ func (enc *Encoder) encodeSliceAsArrayTable(b []byte, ctx encoderCtx, v reflect.
 			scratch = append(scratch, '.')
 		}
 
-		scratch, err = enc.encodeKey(scratch, k)
-		if err != nil {
-			return nil, err
-		}
+		scratch = enc.encodeKey(scratch, k)
 	}
 
 	scratch = append(scratch, "]]\n"...)
 	ctx.skipTableHeader = true
 
+	b = enc.encodeComment(ctx.indent, ctx.options.comment, b)
+
+	if enc.indentTables {
+		ctx.indent++
+	}
+
 	for i := 0; i < v.Len(); i++ {
+		if i != 0 {
+			b = append(b, "\n"...)
+		}
+
 		b = append(b, scratch...)
 
+		var err error
 		b, err = enc.encode(b, ctx, v.Index(i))
 		if err != nil {
 			return nil, err

ossfuzz/fuzz.go

@@ -0,0 +1,42 @@
+package ossfuzz
+
+import (
+	"fmt"
+	"reflect"
+	"strings"
+
+	"github.com/pelletier/go-toml/v2"
+)
+
+func FuzzToml(data []byte) int {
+	if len(data) >= 2048 {
+		return 0
+	}
+
+	if strings.Contains(string(data), "nan") {
+		return 0
+	}
+
+	var v interface{}
+	err := toml.Unmarshal(data, &v)
+	if err != nil {
+		return 0
+	}
+
+	encoded, err := toml.Marshal(v)
+	if err != nil {
+		panic(fmt.Sprintf("failed to marshal unmarshaled document: %s", err))
+	}
+
+	var v2 interface{}
+	err = toml.Unmarshal(encoded, &v2)
+	if err != nil {
+		panic(fmt.Sprintf("failed round trip: %s", err))
+	}
+
+	if !reflect.DeepEqual(v, v2) {
+		panic(fmt.Sprintf("not equal: %#+v %#+v", v, v2))
+	}
+
+	return 1
+}

parser_test.go

@@ -1,431 +0,0 @@
-package toml
-
-import (
-	"testing"
-
-	"github.com/pelletier/go-toml/v2/internal/ast"
-	"github.com/stretchr/testify/require"
-)
-
-//nolint:funlen
-func TestParser_AST_Numbers(t *testing.T) {
-	examples := []struct {
-		desc  string
-		input string
-		kind  ast.Kind
-		err   bool
-	}{
-		{
-			desc:  "integer just digits",
-			input: `1234`,
-			kind:  ast.Integer,
-		},
-		{
-			desc:  "integer zero",
-			input: `0`,
-			kind:  ast.Integer,
-		},
-		{
-			desc:  "integer sign",
-			input: `+99`,
-			kind:  ast.Integer,
-		},
-		{
-			desc:  "integer hex uppercase",
-			input: `0xDEADBEEF`,
-			kind:  ast.Integer,
-		},
-		{
-			desc:  "integer hex lowercase",
-			input: `0xdead_beef`,
-			kind:  ast.Integer,
-		},
-		{
-			desc:  "integer octal",
-			input: `0o01234567`,
-			kind:  ast.Integer,
-		},
-		{
-			desc:  "integer binary",
-			input: `0b11010110`,
-			kind:  ast.Integer,
-		},
-		{
-			desc:  "float zero",
-			input: `0.0`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "float positive zero",
-			input: `+0.0`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "float negative zero",
-			input: `-0.0`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "float pi",
-			input: `3.1415`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "float negative",
-			input: `-0.01`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "float signed exponent",
-			input: `5e+22`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "float exponent lowercase",
-			input: `1e06`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "float exponent uppercase",
-			input: `-2E-2`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "float fractional with exponent",
-			input: `6.626e-34`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "float underscores",
-			input: `224_617.445_991_228`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "inf",
-			input: `inf`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "inf negative",
-			input: `-inf`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "inf positive",
-			input: `+inf`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "nan",
-			input: `nan`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "nan negative",
-			input: `-nan`,
-			kind:  ast.Float,
-		},
-		{
-			desc:  "nan positive",
-			input: `+nan`,
-			kind:  ast.Float,
-		},
-	}
-
-	for _, e := range examples {
-		e := e
-		t.Run(e.desc, func(t *testing.T) {
-			p := parser{}
-			p.Reset([]byte(`A = ` + e.input))
-			p.NextExpression()
-			err := p.Error()
-			if e.err {
-				require.Error(t, err)
-			} else {
-				require.NoError(t, err)
-
-				expected := astNode{
-					Kind: ast.KeyValue,
-					Children: []astNode{
-						{Kind: e.kind, Data: []byte(e.input)},
-						{Kind: ast.Key, Data: []byte(`A`)},
-					},
-				}
-				compareNode(t, expected, p.Expression())
-			}
-		})
-	}
-}
-
-type (
-	astNode struct {
-		Kind     ast.Kind
-		Data     []byte
-		Children []astNode
-	}
-)
-
-func compareNode(t *testing.T, e astNode, n *ast.Node) {
-	t.Helper()
-	require.Equal(t, e.Kind, n.Kind)
-	require.Equal(t, e.Data, n.Data)
-
-	compareIterator(t, e.Children, n.Children())
-}
-
-func compareIterator(t *testing.T, expected []astNode, actual ast.Iterator) {
-	t.Helper()
-	idx := 0
-
-	for actual.Next() {
-		n := actual.Node()
-
-		if idx >= len(expected) {
-			t.Fatal("extra child in actual tree")
-		}
-		e := expected[idx]
-
-		compareNode(t, e, n)
-
-		idx++
-	}
-
-	if idx < len(expected) {
-		t.Fatal("missing children in actual", "idx =", idx, "expected =", len(expected))
-	}
-}
-
-//nolint:funlen
-func TestParser_AST(t *testing.T) {
-	examples := []struct {
-		desc  string
-		input string
-		ast   astNode
-		err   bool
-	}{
-		{
-			desc:  "simple string assignment",
-			input: `A = "hello"`,
-			ast: astNode{
-				Kind: ast.KeyValue,
-				Children: []astNode{
-					{
-						Kind: ast.String,
-						Data: []byte(`hello`),
-					},
-					{
-						Kind: ast.Key,
-						Data: []byte(`A`),
-					},
-				},
-			},
-		},
-		{
-			desc:  "simple bool assignment",
-			input: `A = true`,
-			ast: astNode{
-				Kind: ast.KeyValue,
-				Children: []astNode{
-					{
-						Kind: ast.Bool,
-						Data: []byte(`true`),
-					},
-					{
-						Kind: ast.Key,
-						Data: []byte(`A`),
-					},
-				},
-			},
-		},
-		{
-			desc:  "array of strings",
-			input: `A = ["hello", ["world", "again"]]`,
-			ast: astNode{
-				Kind: ast.KeyValue,
-				Children: []astNode{
-					{
-						Kind: ast.Array,
-						Children: []astNode{
-							{
-								Kind: ast.String,
-								Data: []byte(`hello`),
-							},
-							{
-								Kind: ast.Array,
-								Children: []astNode{
-									{
-										Kind: ast.String,
-										Data: []byte(`world`),
-									},
-									{
-										Kind: ast.String,
-										Data: []byte(`again`),
-									},
-								},
-							},
-						},
-					},
-					{
-						Kind: ast.Key,
-						Data: []byte(`A`),
-					},
-				},
-			},
-		},
-		{
-			desc:  "array of arrays of strings",
-			input: `A = ["hello", "world"]`,
-			ast: astNode{
-				Kind: ast.KeyValue,
-				Children: []astNode{
-					{
-						Kind: ast.Array,
-						Children: []astNode{
-							{
-								Kind: ast.String,
-								Data: []byte(`hello`),
-							},
-							{
-								Kind: ast.String,
-								Data: []byte(`world`),
-							},
-						},
-					},
-					{
-						Kind: ast.Key,
-						Data: []byte(`A`),
-					},
-				},
-			},
-		},
-		{
-			desc:  "inline table",
-			input: `name = { first = "Tom", last = "Preston-Werner" }`,
-			ast: astNode{
-				Kind: ast.KeyValue,
-				Children: []astNode{
-					{
-						Kind: ast.InlineTable,
-						Children: []astNode{
-							{
-								Kind: ast.KeyValue,
-								Children: []astNode{
-									{Kind: ast.String, Data: []byte(`Tom`)},
-									{Kind: ast.Key, Data: []byte(`first`)},
-								},
-							},
-							{
-								Kind: ast.KeyValue,
-								Children: []astNode{
-									{Kind: ast.String, Data: []byte(`Preston-Werner`)},
-									{Kind: ast.Key, Data: []byte(`last`)},
-								},
-							},
-						},
-					},
-					{
-						Kind: ast.Key,
-						Data: []byte(`name`),
-					},
-				},
-			},
-		},
-	}
-
-	for _, e := range examples {
-		e := e
-		t.Run(e.desc, func(t *testing.T) {
-			p := parser{}
-			p.Reset([]byte(e.input))
-			p.NextExpression()
-			err := p.Error()
-			if e.err {
-				require.Error(t, err)
-			} else {
-				require.NoError(t, err)
-				compareNode(t, e.ast, p.Expression())
-			}
-		})
-	}
-}
-
-func BenchmarkParseBasicStringWithUnicode(b *testing.B) {
-	p := &parser{}
-	b.Run("4", func(b *testing.B) {
-		input := []byte(`"\u1234\u5678\u9ABC\u1234\u5678\u9ABC"`)
-		b.ReportAllocs()
-		b.SetBytes(int64(len(input)))
-
-		for i := 0; i < b.N; i++ {
-			p.parseBasicString(input)
-		}
-	})
-	b.Run("8", func(b *testing.B) {
-		input := []byte(`"\u12345678\u9ABCDEF0\u12345678\u9ABCDEF0"`)
-		b.ReportAllocs()
-		b.SetBytes(int64(len(input)))
-
-		for i := 0; i < b.N; i++ {
-			p.parseBasicString(input)
-		}
-	})
-}
-
-func TestParser_AST_DateTimes(t *testing.T) {
-	examples := []struct {
-		desc  string
-		input string
-		kind  ast.Kind
-		err   bool
-	}{
-		{
-			desc:  "offset-date-time with delim 'T' and UTC offset",
-			input: `2021-07-21T12:08:05Z`,
-			kind:  ast.DateTime,
-		},
-		{
-			desc:  "offset-date-time with space delim and +8hours offset",
-			input: `2021-07-21 12:08:05+08:00`,
-			kind:  ast.DateTime,
-		},
-		{
-			desc:  "local-date-time with nano second",
-			input: `2021-07-21T12:08:05.666666666`,
-			kind:  ast.LocalDateTime,
-		},
-		{
-			desc:  "local-date-time",
-			input: `2021-07-21T12:08:05`,
-			kind:  ast.LocalDateTime,
-		},
-		{
-			desc:  "local-date",
-			input: `2021-07-21`,
-			kind:  ast.LocalDate,
-		},
-	}
-
-	for _, e := range examples {
-		e := e
-		t.Run(e.desc, func(t *testing.T) {
-			p := parser{}
-			p.Reset([]byte(`A = ` + e.input))
-			p.NextExpression()
-			err := p.Error()
-			if e.err {
-				require.Error(t, err)
-			} else {
-				require.NoError(t, err)
-
-				expected := astNode{
-					Kind: ast.KeyValue,
-					Children: []astNode{
-						{Kind: e.kind, Data: []byte(e.input)},
-						{Kind: ast.Key, Data: []byte(`A`)},
-					},
-				}
-				compareNode(t, expected, p.Expression())
-			}
-		})
-	}
-}

strict.go

@@ -1,9 +1,9 @@
 package toml
 
 import (
-	"github.com/pelletier/go-toml/v2/internal/ast"
 	"github.com/pelletier/go-toml/v2/internal/danger"
 	"github.com/pelletier/go-toml/v2/internal/tracker"
+	"github.com/pelletier/go-toml/v2/unstable"
 )
 
 type strict struct {
@@ -12,10 +12,10 @@ type strict struct {
 	// Tracks the current key being processed.
 	key tracker.KeyTracker
 
-	missing []decodeError
+	missing []unstable.ParserError
 }
 
-func (s *strict) EnterTable(node *ast.Node) {
+func (s *strict) EnterTable(node *unstable.Node) {
 	if !s.Enabled {
 		return
 	}
@@ -23,7 +23,7 @@ func (s *strict) EnterTable(node *ast.Node) {
 	s.key.UpdateTable(node)
 }
 
-func (s *strict) EnterArrayTable(node *ast.Node) {
+func (s *strict) EnterArrayTable(node *unstable.Node) {
 	if !s.Enabled {
 		return
 	}
@@ -31,7 +31,7 @@ func (s *strict) EnterArrayTable(node *ast.Node) {
 	s.key.UpdateArrayTable(node)
 }
 
-func (s *strict) EnterKeyValue(node *ast.Node) {
+func (s *strict) EnterKeyValue(node *unstable.Node) {
 	if !s.Enabled {
 		return
 	}
@@ -39,7 +39,7 @@ func (s *strict) EnterKeyValue(node *ast.Node) {
 	s.key.Push(node)
 }
 
-func (s *strict) ExitKeyValue(node *ast.Node) {
+func (s *strict) ExitKeyValue(node *unstable.Node) {
 	if !s.Enabled {
 		return
 	}
@@ -47,27 +47,27 @@ func (s *strict) ExitKeyValue(node *ast.Node) {
 	s.key.Pop(node)
 }
 
-func (s *strict) MissingTable(node *ast.Node) {
+func (s *strict) MissingTable(node *unstable.Node) {
 	if !s.Enabled {
 		return
 	}
 
-	s.missing = append(s.missing, decodeError{
-		highlight: keyLocation(node),
-		message:   "missing table",
-		key:       s.key.Key(),
+	s.missing = append(s.missing, unstable.ParserError{
+		Highlight: keyLocation(node),
+		Message:   "missing table",
+		Key:       s.key.Key(),
 	})
 }
 
-func (s *strict) MissingField(node *ast.Node) {
+func (s *strict) MissingField(node *unstable.Node) {
 	if !s.Enabled {
 		return
 	}
 
-	s.missing = append(s.missing, decodeError{
-		highlight: keyLocation(node),
-		message:   "missing field",
-		key:       s.key.Key(),
+	s.missing = append(s.missing, unstable.ParserError{
+		Highlight: keyLocation(node),
+		Message:   "missing field",
+		Key:       s.key.Key(),
 	})
 }
 
@@ -88,7 +88,7 @@ func (s *strict) Error(doc []byte) error {
 	return err
 }
 
-func keyLocation(node *ast.Node) []byte {
+func keyLocation(node *unstable.Node) []byte {
 	k := node.Key()
 
 	hasOne := k.Next()

test-go-versions.sh

@@ -0,0 +1,596 @@
+#!/usr/bin/env bash
+
+set -uo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Go versions to test (1.11 through 1.25)
+GO_VERSIONS=(
+    "1.11"
+    "1.12"
+    "1.13"
+    "1.14"
+    "1.15"
+    "1.16"
+    "1.17"
+    "1.18"
+    "1.19"
+    "1.20"
+    "1.21"
+    "1.22"
+    "1.23"
+    "1.24"
+    "1.25"
+)
+
+# Default values
+PARALLEL=true
+VERBOSE=false
+OUTPUT_DIR="test-results"
+DOCKER_TIMEOUT="10m"
+
+usage() {
+    cat << EOF
+Usage: $0 [OPTIONS] [GO_VERSIONS...]
+
+Test go-toml across multiple Go versions using Docker containers.
+
+The script reports the lowest continuous supported Go version (where all subsequent 
+versions pass) and only exits with non-zero status if either of the two most recent 
+Go versions fail, indicating immediate attention is needed.
+
+Note: For Go versions < 1.21, the script automatically updates go.mod to match the 
+target version, but older versions may still fail due to missing standard library 
+features (e.g., the 'slices' package introduced in Go 1.21).
+
+OPTIONS:
+    -h, --help          Show this help message
+    -s, --sequential    Run tests sequentially instead of in parallel
+    -v, --verbose       Enable verbose output
+    -o, --output DIR    Output directory for test results (default: test-results)
+    -t, --timeout TIME  Docker timeout for each test (default: 10m)
+    --list              List available Go versions and exit
+
+ARGUMENTS:
+    GO_VERSIONS         Specific Go versions to test (default: all supported versions)
+                        Examples: 1.21 1.22 1.23
+
+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
+
+EXIT CODES:
+    0                   Recent Go versions pass (good compatibility)
+    1                   Recent Go versions fail (needs attention) or script error
+
+EOF
+}
+
+log() {
+    echo -e "${BLUE}[$(date +'%H:%M:%S')]${NC} $*" >&2
+}
+
+log_success() {
+    echo -e "${GREEN}[$(date +'%H:%M:%S')] ✓${NC} $*" >&2
+}
+
+log_error() {
+    echo -e "${RED}[$(date +'%H:%M:%S')] ✗${NC} $*" >&2
+}
+
+log_warning() {
+    echo -e "${YELLOW}[$(date +'%H:%M:%S')] ⚠${NC} $*" >&2
+}
+
+# Parse command line arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        -s|--sequential)
+            PARALLEL=false
+            shift
+            ;;
+        -v|--verbose)
+            VERBOSE=true
+            shift
+            ;;
+        -o|--output)
+            OUTPUT_DIR="$2"
+            shift 2
+            ;;
+        -t|--timeout)
+            DOCKER_TIMEOUT="$2"
+            shift 2
+            ;;
+        --list)
+            echo "Available Go versions:"
+            printf '%s\n' "${GO_VERSIONS[@]}"
+            exit 0
+            ;;
+        -*)
+            echo "Unknown option: $1" >&2
+            usage
+            exit 1
+            ;;
+        *)
+            # Remaining arguments are Go versions
+            break
+            ;;
+    esac
+done
+
+# If specific versions provided, use those instead of defaults
+if [[ $# -gt 0 ]]; then
+    GO_VERSIONS=("$@")
+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"
+        exit 1
+    fi
+done
+
+# Check if Docker is available
+if ! command -v docker &> /dev/null; then
+    log_error "Docker is required but not installed or not in PATH"
+    exit 1
+fi
+
+# Check if Docker daemon is running
+if ! docker info &> /dev/null; then
+    log_error "Docker daemon is not running"
+    exit 1
+fi
+
+# Create output directory
+mkdir -p "$OUTPUT_DIR"
+
+# Function to test a single Go version
+test_go_version() {
+    local go_version="$1"
+    local container_name="go-toml-test-${go_version}"
+    local result_file="${OUTPUT_DIR}/go-${go_version}.txt"
+    local dockerfile_content
+
+    log "Testing Go $go_version..."
+
+    # Create a temporary Dockerfile for this version
+    # For Go versions < 1.21, we need to update go.mod to match the Go version
+    local needs_go_mod_update=false
+    if [[ $(echo "$go_version 1.21" | tr ' ' '\n' | sort -V | head -n1) == "$go_version" && "$go_version" != "1.21" ]]; then
+        needs_go_mod_update=true
+    fi
+    
+    dockerfile_content="FROM golang:${go_version}-alpine
+
+# Install git (required for go mod)
+RUN apk add --no-cache git
+
+# Set working directory
+WORKDIR /app
+
+# Copy source code
+COPY . ."
+
+    # Add go.mod update step for older Go versions
+    if [[ "$needs_go_mod_update" == true ]]; then
+        dockerfile_content="$dockerfile_content
+
+# Update go.mod to match Go version (required for Go < 1.21)
+RUN if [ -f go.mod ]; then sed -i 's/^go [0-9]\\+\\.[0-9]\\+\\(\\.[0-9]\\+\\)\\?/go $go_version/' go.mod; fi
+
+# Note: Go versions < 1.21 may fail due to missing standard library packages (e.g., slices)
+# This is expected for projects that use Go 1.21+ features"
+    fi
+    
+    dockerfile_content="$dockerfile_content
+
+# Run tests
+CMD [\"sh\", \"-c\", \"go version && echo '--- Running go test ./... ---' && go test ./...\"]"
+
+    # Create temporary directory for this test
+    local temp_dir
+    temp_dir=$(mktemp -d)
+
+    # Copy source to temp directory (excluding test results and git)
+    rsync -a --exclude="$OUTPUT_DIR" --exclude=".git" --exclude="*.test" . "$temp_dir/"
+
+    # Create Dockerfile in temp directory
+    echo "$dockerfile_content" > "$temp_dir/Dockerfile"
+
+    # Build and run container
+    local exit_code=0
+    local output
+
+    if $VERBOSE; then
+        log "Building Docker image for Go $go_version..."
+    fi
+
+    # Capture both stdout and stderr, and the exit code
+    if output=$(cd "$temp_dir" && timeout "$DOCKER_TIMEOUT" docker build -t "$container_name" . 2>&1 && \
+                timeout "$DOCKER_TIMEOUT" docker run --rm "$container_name" 2>&1); then
+        log_success "Go $go_version: PASSED"
+        echo "PASSED" > "${result_file}.status"
+    else
+        exit_code=$?
+        log_error "Go $go_version: FAILED (exit code: $exit_code)"
+        echo "FAILED" > "${result_file}.status"
+    fi
+
+    # Save full output
+    echo "$output" > "$result_file"
+
+    # Clean up
+    docker rmi "$container_name" &> /dev/null || true
+    rm -rf "$temp_dir"
+
+    if $VERBOSE; then
+        echo "--- Go $go_version output ---"
+        echo "$output"
+        echo "--- End Go $go_version output ---"
+    fi
+
+    return $exit_code
+}
+
+# Function to run tests in parallel
+run_parallel() {
+    local pids=()
+    local failed_versions=()
+
+    log "Starting parallel tests for ${#GO_VERSIONS[@]} Go versions..."
+
+    # Start all tests in background
+    for version in "${GO_VERSIONS[@]}"; do
+        test_go_version "$version" &
+        pids+=($!)
+    done
+
+    # Wait for all tests to complete
+    for i in "${!pids[@]}"; do
+        local pid=${pids[$i]}
+        local version=${GO_VERSIONS[$i]}
+
+        if ! wait $pid; then
+            failed_versions+=("$version")
+        fi
+    done
+
+    return ${#failed_versions[@]}
+}
+
+# Function to run tests sequentially
+run_sequential() {
+    local failed_versions=()
+
+    log "Starting sequential tests for ${#GO_VERSIONS[@]} Go versions..."
+
+    for version in "${GO_VERSIONS[@]}"; do
+        if ! test_go_version "$version"; then
+            failed_versions+=("$version")
+        fi
+    done
+
+    return ${#failed_versions[@]}
+}
+
+# Main execution
+main() {
+    local start_time
+    start_time=$(date +%s)
+
+    log "Starting Go version compatibility tests..."
+    log "Testing versions: ${GO_VERSIONS[*]}"
+    log "Output directory: $OUTPUT_DIR"
+    log "Parallel execution: $PARALLEL"
+
+    local failed_count
+    if $PARALLEL; then
+        run_parallel
+        failed_count=$?
+    else
+        run_sequential
+        failed_count=$?
+    fi
+
+    local end_time
+    end_time=$(date +%s)
+    local duration=$((end_time - start_time))
+
+    # Collect results for display
+    local passed_versions=()
+    local failed_versions=()
+    local unknown_versions=()
+    local passed_count=0
+
+    for version in "${GO_VERSIONS[@]}"; do
+        local status_file="${OUTPUT_DIR}/go-${version}.txt.status"
+        if [[ -f "$status_file" ]]; then
+            local status
+            status=$(cat "$status_file")
+            if [[ "$status" == "PASSED" ]]; then
+                passed_versions+=("$version")
+                ((passed_count++))
+            else
+                failed_versions+=("$version")
+            fi
+        else
+            unknown_versions+=("$version")
+        fi
+    done
+
+    # Generate summary report
+    local summary_file="${OUTPUT_DIR}/summary.txt"
+    {
+        echo "Go Version Compatibility Test Summary"
+        echo "====================================="
+        echo "Date: $(date)"
+        echo "Duration: ${duration}s"
+        echo "Parallel: $PARALLEL"
+        echo ""
+        echo "Results:"
+
+        for version in "${GO_VERSIONS[@]}"; do
+            local status_file="${OUTPUT_DIR}/go-${version}.txt.status"
+            if [[ -f "$status_file" ]]; then
+                local status
+                status=$(cat "$status_file")
+                if [[ "$status" == "PASSED" ]]; then
+                    echo "  Go $version: ✓ PASSED"
+                else
+                    echo "  Go $version: ✗ FAILED"
+                fi
+            else
+                echo "  Go $version: ? UNKNOWN (no status file)"
+            fi
+        done
+
+        echo ""
+        echo "Summary: $passed_count/${#GO_VERSIONS[@]} versions passed"
+
+        if [[ $failed_count -gt 0 ]]; then
+            echo ""
+            echo "Failed versions details:"
+            for version in "${failed_versions[@]}"; do
+                echo ""
+                echo "--- Go $version (FAILED) ---"
+                local result_file="${OUTPUT_DIR}/go-${version}.txt"
+                if [[ -f "$result_file" ]]; then
+                    tail -n 30 "$result_file"
+                fi
+            done
+        fi
+    } > "$summary_file"
+
+        # Find lowest continuous supported version and check recent versions
+    local lowest_continuous_version=""
+    local recent_versions_failed=false
+    
+    # Sort versions to ensure proper order
+    local sorted_versions=()
+    for version in "${GO_VERSIONS[@]}"; do
+        sorted_versions+=("$version")
+    done
+    # Sort versions numerically (1.11, 1.12, ..., 1.25)
+    IFS=$'\n' sorted_versions=($(sort -V <<< "${sorted_versions[*]}"))
+    
+    # Find lowest continuous supported version (all versions from this point onwards pass)
+    for version in "${sorted_versions[@]}"; do
+        local status_file="${OUTPUT_DIR}/go-${version}.txt.status"
+        local all_subsequent_pass=true
+        
+        # Check if this version and all subsequent versions pass
+        local found_current=false
+        for check_version in "${sorted_versions[@]}"; do
+            if [[ "$check_version" == "$version" ]]; then
+                found_current=true
+            fi
+            
+            if [[ "$found_current" == true ]]; then
+                local check_status_file="${OUTPUT_DIR}/go-${check_version}.txt.status"
+                if [[ -f "$check_status_file" ]]; then
+                    local status
+                    status=$(cat "$check_status_file")
+                    if [[ "$status" != "PASSED" ]]; then
+                        all_subsequent_pass=false
+                        break
+                    fi
+                else
+                    all_subsequent_pass=false
+                    break
+                fi
+            fi
+        done
+        
+        if [[ "$all_subsequent_pass" == true ]]; then
+            lowest_continuous_version="$version"
+            break
+        fi
+    done
+    
+    # Check if the two most recent versions failed
+    local num_versions=${#sorted_versions[@]}
+    if [[ $num_versions -ge 2 ]]; then
+        local second_recent="${sorted_versions[$((num_versions-2))]}"
+        local most_recent="${sorted_versions[$((num_versions-1))]}"
+        
+        local second_recent_status_file="${OUTPUT_DIR}/go-${second_recent}.txt.status"
+        local most_recent_status_file="${OUTPUT_DIR}/go-${most_recent}.txt.status"
+        
+        local second_recent_failed=false
+        local most_recent_failed=false
+        
+        if [[ -f "$second_recent_status_file" ]]; then
+            local status
+            status=$(cat "$second_recent_status_file")
+            if [[ "$status" != "PASSED" ]]; then
+                second_recent_failed=true
+            fi
+        else
+            second_recent_failed=true
+        fi
+        
+        if [[ -f "$most_recent_status_file" ]]; then
+            local status
+            status=$(cat "$most_recent_status_file")
+            if [[ "$status" != "PASSED" ]]; then
+                most_recent_failed=true
+            fi
+        else
+            most_recent_failed=true
+        fi
+        
+        if [[ "$second_recent_failed" == true || "$most_recent_failed" == true ]]; then
+            recent_versions_failed=true
+        fi
+    elif [[ $num_versions -eq 1 ]]; then
+        # Only one version tested, check if it's the most recent and failed
+        local only_version="${sorted_versions[0]}"
+        local only_status_file="${OUTPUT_DIR}/go-${only_version}.txt.status"
+        
+        if [[ -f "$only_status_file" ]]; then
+            local status
+            status=$(cat "$only_status_file")
+            if [[ "$status" != "PASSED" ]]; then
+                recent_versions_failed=true
+            fi
+        else
+            recent_versions_failed=true
+        fi
+    fi
+    
+    # Display summary
+    echo ""
+    log "Test completed in ${duration}s"
+    log "Summary report: $summary_file"
+    
+    echo ""
+    echo "========================================"
+    echo "           FINAL RESULTS"
+    echo "========================================"
+    echo ""
+    
+    # Display passed versions
+    if [[ ${#passed_versions[@]} -gt 0 ]]; then
+        log_success "PASSED (${#passed_versions[@]}/${#GO_VERSIONS[@]}):"
+        # Sort passed versions for display
+        local sorted_passed=()
+        for version in "${sorted_versions[@]}"; do
+            for passed_version in "${passed_versions[@]}"; do
+                if [[ "$version" == "$passed_version" ]]; then
+                    sorted_passed+=("$version")
+                    break
+                fi
+            done
+        done
+        for version in "${sorted_passed[@]}"; do
+            echo -e "  ${GREEN}✓${NC} Go $version"
+        done
+        echo ""
+    fi
+    
+    # Display failed versions
+    if [[ ${#failed_versions[@]} -gt 0 ]]; then
+        log_error "FAILED (${#failed_versions[@]}/${#GO_VERSIONS[@]}):"
+        # Sort failed versions for display
+        local sorted_failed=()
+        for version in "${sorted_versions[@]}"; do
+            for failed_version in "${failed_versions[@]}"; do
+                if [[ "$version" == "$failed_version" ]]; then
+                    sorted_failed+=("$version")
+                    break
+                fi
+            done
+        done
+        for version in "${sorted_failed[@]}"; do
+            echo -e "  ${RED}✗${NC} Go $version"
+        done
+        echo ""
+        
+        # Show failure details
+        echo "========================================"
+        echo "         FAILURE DETAILS"
+        echo "========================================"
+        echo ""
+        
+        for version in "${sorted_failed[@]}"; do
+            echo -e "${RED}--- Go $version FAILURE LOGS (last 30 lines) ---${NC}"
+            local result_file="${OUTPUT_DIR}/go-${version}.txt"
+            if [[ -f "$result_file" ]]; then
+                tail -n 30 "$result_file" | sed 's/^/  /'
+            else
+                echo "  No log file found: $result_file"
+            fi
+            echo ""
+        done
+    fi
+    
+    # Display unknown versions
+    if [[ ${#unknown_versions[@]} -gt 0 ]]; then
+        log_warning "UNKNOWN (${#unknown_versions[@]}/${#GO_VERSIONS[@]}):"
+        for version in "${unknown_versions[@]}"; do
+            echo -e "  ${YELLOW}?${NC} Go $version (no status file)"
+        done
+        echo ""
+    fi
+    
+    echo "========================================"
+    echo "         COMPATIBILITY SUMMARY"
+    echo "========================================"
+    echo ""
+    
+    if [[ -n "$lowest_continuous_version" ]]; then
+        log_success "Lowest continuous supported version: Go $lowest_continuous_version"
+        echo "  (All versions from Go $lowest_continuous_version onwards pass)"
+    else
+        log_error "No continuous version support found"
+        echo "  (No version has all subsequent versions passing)"
+    fi
+    
+    echo ""
+    echo "========================================"
+    echo "Full detailed logs available in: $OUTPUT_DIR"
+    echo "========================================"
+    
+    # Determine exit code based on recent versions
+    if [[ "$recent_versions_failed" == true ]]; then
+        log_error "OVERALL RESULT: Recent Go versions failed - this needs attention!"
+        if [[ -n "$lowest_continuous_version" ]]; then
+            echo "Note: Continuous support starts from Go $lowest_continuous_version"
+        fi
+        exit 1
+    else
+        log_success "OVERALL RESULT: Recent Go versions pass - compatibility looks good!"
+        if [[ -n "$lowest_continuous_version" ]]; then
+            echo "Continuous support starts from Go $lowest_continuous_version"
+        fi
+        exit 0
+    fi
+}
+
+# Trap to clean up on exit
+cleanup() {
+    # Kill any remaining background processes
+    jobs -p | xargs -r kill 2>/dev/null || true
+
+    # Clean up any remaining Docker containers
+    docker ps -q --filter "name=go-toml-test-" | xargs -r docker stop 2>/dev/null || true
+    docker images -q --filter "reference=go-toml-test-*" | xargs -r docker rmi 2>/dev/null || true
+}
+
+trap cleanup EXIT
+
+# Run main function
+main

testdata/fuzz/FuzzUnmarshal/0c08b924aa26af23d16b77029b4f5567a96af93402e0472fef7b837b37580d7c

@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("0=0000-01-01 00:00:00")

testdata/fuzz/FuzzUnmarshal/249a017d8ffa0d88d41c594ada5399f764833f64050180cb39f106d12666853f

@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("\"\\n\"=\"\"")

testdata/fuzz/FuzzUnmarshal/391ce67b866d58464d067c5981e99951fd499896453a2fe2779a6bfe7df11bf5

@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("''=0")

testdata/fuzz/FuzzUnmarshal/49ae83283c5cfbed874bcacbfb342de107b69c2a3d3c35c2d99f67345fe89946

@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("0=0000-01-01")

testdata/fuzz/FuzzUnmarshal/69ea82e85bb4ad966ae86bb05eea3af69ed1a826c846f1bf2282f329b4d8fb36

@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("0=\"\"\"\\U00000000\"\"\"")

testdata/fuzz/FuzzUnmarshal/746910fac6deb42e7e62dce60b333c81c39d844a122c9075894c023400e8fdbf

@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("0=[[{}]]")

testdata/fuzz/FuzzUnmarshal/844d1171a3adc95e51627f0e9378bbaa193fe2d0284f4ba8ed19a5226a8cbc74

@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("\"\\b\"=\"\"")

testdata/fuzz/FuzzUnmarshal/900c54b5071113ae2a5365b3156377ddd775b9d38add61629544903cb9c94b00

@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("0=inf")

testdata/fuzz/FuzzUnmarshal/c87e8eb4e8fa40fd3c89d8ed16a049ce81592ded710965ee29a4e506eb5427b3

@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("0=0000-01-01 00:00:00+00:00")

testdata/fuzz/FuzzUnmarshal/d0e5d6fc3b865cfae5480c01f301b87c932722ae0c1d692deea413349ea028be

@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("0=[{}]")

testdata/fuzz/FuzzUnmarshal/d2cecea5b8ee5f148419671cef0644178cdba1ee91d3f295be38da576e89ef40

@@ -0,0 +1,2 @@
+go test fuzz v1
+[]byte("0=nan")

toml_testgen_support_test.go

@@ -1,4 +1,5 @@
-//go:generate go run ./cmd/tomltestgen/main.go -o toml_testgen_test.go
+//go:generate go run github.com/toml-lang/toml-test/cmd/toml-test@v1.6.0 -copy ./tests
+//go:generate go run ./cmd/tomltestgen/main.go -r v1.6.0 -o toml_testgen_test.go
 
 // This is a support file for toml_testgen_test.go
 package toml_test
@@ -8,8 +9,8 @@ import (
 	"testing"
 
 	"github.com/pelletier/go-toml/v2"
-	"github.com/pelletier/go-toml/v2/testsuite"
-	"github.com/stretchr/testify/require"
+	"github.com/pelletier/go-toml/v2/internal/assert"
+	"github.com/pelletier/go-toml/v2/internal/testsuite"
 )
 
 func testgenInvalid(t *testing.T, input string) {
@@ -44,15 +45,15 @@ func testgenValid(t *testing.T, input string, jsonRef string) {
 		t.Fatalf("failed parsing toml: %s", err)
 	}
 	j, err := testsuite.ValueToTaggedJSON(doc)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 
 	var ref interface{}
 	err = json.Unmarshal([]byte(jsonRef), &ref)
-	require.NoError(t, err)
+	assert.NoError(t, err)
 
 	var actual interface{}
-	err = json.Unmarshal([]byte(j), &actual)
-	require.NoError(t, err)
+	err = json.Unmarshal(j, &actual)
+	assert.NoError(t, err)
 
 	testsuite.CmpJSON(t, "", ref, actual)
 }

types.go

@@ -6,8 +6,9 @@ import (
 	"time"
 )
 
-var timeType = reflect.TypeOf(time.Time{})
-var textMarshalerType = reflect.TypeOf(new(encoding.TextMarshaler)).Elem()
-var textUnmarshalerType = reflect.TypeOf(new(encoding.TextUnmarshaler)).Elem()
-var mapStringInterfaceType = reflect.TypeOf(map[string]interface{}{})
-var sliceInterfaceType = reflect.TypeOf([]interface{}{})
+var timeType = reflect.TypeOf((*time.Time)(nil)).Elem()
+var textMarshalerType = reflect.TypeOf((*encoding.TextMarshaler)(nil)).Elem()
+var textUnmarshalerType = reflect.TypeOf((*encoding.TextUnmarshaler)(nil)).Elem()
+var mapStringInterfaceType = reflect.TypeOf(map[string]interface{}(nil))
+var sliceInterfaceType = reflect.TypeOf([]interface{}(nil))
+var stringType = reflect.TypeOf("")

unstable/ast.go

@@ -0,0 +1,136 @@
+package unstable
+
+import (
+	"fmt"
+	"unsafe"
+
+	"github.com/pelletier/go-toml/v2/internal/danger"
+)
+
+// Iterator over a sequence of nodes.
+//
+// Starts uninitialized, you need to call Next() first.
+//
+// For example:
+//
+//	it := n.Children()
+//	for it.Next() {
+//		n := it.Node()
+//		// do something with n
+//	}
+type Iterator struct {
+	started bool
+	node    *Node
+}
+
+// Next moves the iterator forward and returns true if points to a
+// node, false otherwise.
+func (c *Iterator) Next() bool {
+	if !c.started {
+		c.started = true
+	} else if c.node.Valid() {
+		c.node = c.node.Next()
+	}
+	return c.node.Valid()
+}
+
+// IsLast returns true if the current node of the iterator is the last
+// one.  Subsequent calls to Next() will return false.
+func (c *Iterator) IsLast() bool {
+	return c.node.next == 0
+}
+
+// Node returns a pointer to the node pointed at by the iterator.
+func (c *Iterator) Node() *Node {
+	return c.node
+}
+
+// Node in a TOML expression AST.
+//
+// Depending on Kind, its sequence of children should be interpreted
+// differently.
+//
+//   - Array have one child per element in the array.
+//   - InlineTable have one child per key-value in the table (each of kind
+//     InlineTable).
+//   - KeyValue have at least two children. The first one is the value. The rest
+//     make a potentially dotted key.
+//   - Table and ArrayTable's children represent a dotted key (same as
+//     KeyValue, but without the first node being the value).
+//
+// When relevant, Raw describes the range of bytes this node is referring to in
+// the input document. Use Parser.Raw() to retrieve the actual bytes.
+type Node struct {
+	Kind Kind
+	Raw  Range  // Raw bytes from the input.
+	Data []byte // Node value (either allocated or referencing the input).
+
+	// References to other nodes, as offsets in the backing array
+	// from this node. References can go backward, so those can be
+	// negative.
+	next  int // 0 if last element
+	child int // 0 if no child
+}
+
+// Range of bytes in the document.
+type Range struct {
+	Offset uint32
+	Length uint32
+}
+
+// Next returns a pointer to the next node, or nil if there is no next node.
+func (n *Node) Next() *Node {
+	if n.next == 0 {
+		return nil
+	}
+	ptr := unsafe.Pointer(n)
+	size := unsafe.Sizeof(Node{})
+	return (*Node)(danger.Stride(ptr, size, n.next))
+}
+
+// Child returns a pointer to the first child node of this node. Other children
+// can be accessed calling Next on the first child.  Returns nil if this Node
+// has no child.
+func (n *Node) Child() *Node {
+	if n.child == 0 {
+		return nil
+	}
+	ptr := unsafe.Pointer(n)
+	size := unsafe.Sizeof(Node{})
+	return (*Node)(danger.Stride(ptr, size, n.child))
+}
+
+// Valid returns true if the node's kind is set (not to Invalid).
+func (n *Node) Valid() bool {
+	return n != nil
+}
+
+// Key returns the children nodes making the Key on a supported node. Panics
+// otherwise.  They are guaranteed to be all be of the Kind Key. A simple key
+// would return just one element.
+func (n *Node) Key() Iterator {
+	switch n.Kind {
+	case KeyValue:
+		value := n.Child()
+		if !value.Valid() {
+			panic(fmt.Errorf("KeyValue should have at least two children"))
+		}
+		return Iterator{node: value.Next()}
+	case Table, ArrayTable:
+		return Iterator{node: n.Child()}
+	default:
+		panic(fmt.Errorf("Key() is not supported on a %s", n.Kind))
+	}
+}
+
+// Value returns a pointer to the value node of a KeyValue.
+// Guaranteed to be non-nil.  Panics if not called on a KeyValue node,
+// or if the Children are malformed.
+func (n *Node) Value() *Node {
+	return n.Child()
+}
+
+// Children returns an iterator over a node's children.
+func (n *Node) Children() Iterator {
+	return Iterator{node: n.Child()}
+}

unstable/benchmark_test.go

@@ -1,4 +1,4 @@
-package toml
+package unstable
 
 import (
 	"bytes"
@@ -55,7 +55,7 @@ func BenchmarkParseLiteralStringValid(b *testing.B) {
 
 	for name, input := range inputs {
 		b.Run(name, func(b *testing.B) {
-			p := parser{}
+			p := Parser{}
 			b.SetBytes(int64(len(input)))
 			b.ReportAllocs()
 			b.ResetTimer()

unstable/builder.go

@@ -0,0 +1,71 @@
+package unstable
+
+// root contains a full AST.
+//
+// It is immutable once constructed with Builder.
+type root struct {
+	nodes []Node
+}
+
+// Iterator over the top level nodes.
+func (r *root) Iterator() Iterator {
+	it := Iterator{}
+	if len(r.nodes) > 0 {
+		it.node = &r.nodes[0]
+	}
+	return it
+}
+
+func (r *root) at(idx reference) *Node {
+	return &r.nodes[idx]
+}
+
+type reference int
+
+const invalidReference reference = -1
+
+func (r reference) Valid() bool {
+	return r != invalidReference
+}
+
+type builder struct {
+	tree    root
+	lastIdx int
+}
+
+func (b *builder) Tree() *root {
+	return &b.tree
+}
+
+func (b *builder) NodeAt(ref reference) *Node {
+	return b.tree.at(ref)
+}
+
+func (b *builder) Reset() {
+	b.tree.nodes = b.tree.nodes[:0]
+	b.lastIdx = 0
+}
+
+func (b *builder) Push(n Node) reference {
+	b.lastIdx = len(b.tree.nodes)
+	b.tree.nodes = append(b.tree.nodes, n)
+	return reference(b.lastIdx)
+}
+
+func (b *builder) PushAndChain(n Node) reference {
+	newIdx := len(b.tree.nodes)
+	b.tree.nodes = append(b.tree.nodes, n)
+	if b.lastIdx >= 0 {
+		b.tree.nodes[b.lastIdx].next = newIdx - b.lastIdx
+	}
+	b.lastIdx = newIdx
+	return reference(b.lastIdx)
+}
+
+func (b *builder) AttachChild(parent reference, child reference) {
+	b.tree.nodes[parent].child = int(child) - int(parent)
+}
+
+func (b *builder) Chain(from reference, to reference) {
+	b.tree.nodes[from].next = int(to) - int(from)
+}

unstable/doc.go

@@ -0,0 +1,3 @@
+// Package unstable provides APIs that do not meet the backward compatibility
+// guarantees yet.
+package unstable

unstable/kind.go

@@ -1,25 +1,26 @@
-package ast
+package unstable
 
 import "fmt"
 
+// Kind represents the type of TOML structure contained in a given Node.
 type Kind int
 
 const (
-	// meta
+	// Meta
 	Invalid Kind = iota
 	Comment
 	Key
 
-	// top level structures
+	// Top level structures
 	Table
 	ArrayTable
 	KeyValue
 
-	// containers values
+	// Containers values
 	Array
 	InlineTable
 
-	// values
+	// Values
 	String
 	Bool
 	Float
@@ -30,6 +31,7 @@ const (
 	DateTime
 )
 
+// String implementation of fmt.Stringer.
 func (k Kind) String() string {
 	switch k {
 	case Invalid:

unstable/parser.go

@@ -1,50 +1,108 @@
-package toml
+package unstable
 
 import (
 	"bytes"
+	"fmt"
 	"unicode"
 
-	"github.com/pelletier/go-toml/v2/internal/ast"
+	"github.com/pelletier/go-toml/v2/internal/characters"
 	"github.com/pelletier/go-toml/v2/internal/danger"
 )
 
-type parser struct {
-	builder ast.Builder
-	ref     ast.Reference
+// ParserError describes an error relative to the content of the document.
+//
+// It cannot outlive the instance of Parser it refers to, and may cause panics
+// if the parser is reset.
+type ParserError struct {
+	Highlight []byte
+	Message   string
+	Key       []string // optional
+}
+
+// Error is the implementation of the error interface.
+func (e *ParserError) Error() string {
+	return e.Message
+}
+
+// NewParserError is a convenience function to create a ParserError
+//
+// 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 {
+	return &ParserError{
+		Highlight: highlight,
+		Message:   fmt.Errorf(format, args...).Error(),
+	}
+}
+
+// Parser scans over a TOML-encoded document and generates an iterative AST.
+//
+// To prime the Parser, first reset it with the contents of a TOML document.
+// Then, process all top-level expressions sequentially. See Example.
+//
+// Don't forget to check Error() after you're done parsing.
+//
+// Each top-level expression needs to be fully processed before calling
+// NextExpression() again. Otherwise, calls to various Node methods may panic if
+// the parser has moved on the next expression.
+//
+// For performance reasons, go-toml doesn't make a copy of the input bytes to
+// the parser. Make sure to copy all the bytes you need to outlive the slice
+// given to the parser.
+type Parser struct {
 	data    []byte
+	builder builder
+	ref     reference
 	left    []byte
 	err     error
 	first   bool
+
+	KeepComments bool
 }
 
-func (p *parser) Range(b []byte) ast.Range {
-	return ast.Range{
+// Data returns the slice provided to the last call to Reset.
+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(danger.SubsliceOffset(p.data, b)),
 		Length: uint32(len(b)),
 	}
 }
 
-func (p *parser) Raw(raw ast.Range) []byte {
+// 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]
 }
 
-func (p *parser) Reset(b []byte) {
+// Reset brings the parser to its initial state for a given input. It wipes an
+// reuses internal storage to reduce allocation.
+func (p *Parser) Reset(b []byte) {
 	p.builder.Reset()
-	p.ref = ast.InvalidReference
+	p.ref = invalidReference
 	p.data = b
 	p.left = b
 	p.err = nil
 	p.first = true
 }
 
-//nolint:cyclop
-func (p *parser) NextExpression() bool {
+// NextExpression parses the next top-level expression. If an expression was
+// successfully parsed, it returns true. If the parser is at the end of the
+// document or an error occurred, it returns false.
+//
+// Retrieve the parsed expression with Expression().
+func (p *Parser) NextExpression() bool {
 	if len(p.left) == 0 || p.err != nil {
 		return false
 	}
 
 	p.builder.Reset()
-	p.ref = ast.InvalidReference
+	p.ref = invalidReference
 
 	for {
 		if len(p.left) == 0 || p.err != nil {
@@ -73,15 +131,56 @@ func (p *parser) NextExpression() bool {
 	}
 }
 
-func (p *parser) Expression() *ast.Node {
+// Expression returns a pointer to the node representing the last successfully
+// parsed expression.
+func (p *Parser) Expression() *Node {
 	return p.builder.NodeAt(p.ref)
 }
 
-func (p *parser) Error() error {
+// Error returns any error that has occurred during parsing.
+func (p *Parser) Error() error {
 	return p.err
 }
 
-func (p *parser) parseNewline(b []byte) ([]byte, error) {
+// Position describes a position in the input.
+type Position struct {
+	// Number of bytes from the beginning of the input.
+	Offset int
+	// Line number, starting at 1.
+	Line int
+	// Column number, starting at 1.
+	Column int
+}
+
+// Shape describes the position of a range in the input.
+type Shape struct {
+	Start Position
+	End   Position
+}
+
+func (p *Parser) position(b []byte) Position {
+	offset := danger.SubsliceOffset(p.data, b)
+
+	lead := p.data[:offset]
+
+	return Position{
+		Offset: offset,
+		Line:   bytes.Count(lead, []byte{'\n'}) + 1,
+		Column: len(lead) - bytes.LastIndex(lead, []byte{'\n'}),
+	}
+}
+
+// Shape returns the shape of the given range in the input.  Will
+// panic if the range is not a subslice of the input.
+func (p *Parser) Shape(r Range) Shape {
+	raw := p.Raw(r)
+	return Shape{
+		Start: p.position(raw),
+		End:   p.position(raw[r.Length:]),
+	}
+}
+
+func (p *Parser) parseNewline(b []byte) ([]byte, error) {
 	if b[0] == '\n' {
 		return b[1:], nil
 	}
@@ -91,14 +190,27 @@ func (p *parser) parseNewline(b []byte) ([]byte, error) {
 		return rest, err
 	}
 
-	return nil, newDecodeError(b[0:1], "expected newline but got %#U", b[0])
+	return nil, NewParserError(b[0:1], "expected newline but got %#U", b[0])
 }
 
-func (p *parser) parseExpression(b []byte) (ast.Reference, []byte, error) {
+func (p *Parser) parseComment(b []byte) (reference, []byte, error) {
+	ref := invalidReference
+	data, rest, err := scanComment(b)
+	if p.KeepComments && err == nil {
+		ref = p.builder.Push(Node{
+			Kind: Comment,
+			Raw:  p.Range(data),
+			Data: data,
+		})
+	}
+	return ref, rest, err
+}
+
+func (p *Parser) parseExpression(b []byte) (reference, []byte, error) {
 	// expression =  ws [ comment ]
 	// expression =/ ws keyval ws [ comment ]
 	// expression =/ ws table ws [ comment ]
-	ref := ast.InvalidReference
+	ref := invalidReference
 
 	b = p.parseWhitespace(b)
 
@@ -107,7 +219,7 @@ func (p *parser) parseExpression(b []byte) (ast.Reference, []byte, error) {
 	}
 
 	if b[0] == '#' {
-		_, rest, err := scanComment(b)
+		ref, rest, err := p.parseComment(b)
 		return ref, rest, err
 	}
 
@@ -129,14 +241,17 @@ func (p *parser) parseExpression(b []byte) (ast.Reference, []byte, error) {
 	b = p.parseWhitespace(b)
 
 	if len(b) > 0 && b[0] == '#' {
-		_, rest, err := scanComment(b)
+		cref, rest, err := p.parseComment(b)
+		if cref != invalidReference {
+			p.builder.Chain(ref, cref)
+		}
 		return ref, rest, err
 	}
 
 	return ref, b, nil
 }
 
-func (p *parser) parseTable(b []byte) (ast.Reference, []byte, error) {
+func (p *Parser) parseTable(b []byte) (reference, []byte, error) {
 	// table = std-table / array-table
 	if len(b) > 1 && b[1] == '[' {
 		return p.parseArrayTable(b)
@@ -145,12 +260,12 @@ func (p *parser) parseTable(b []byte) (ast.Reference, []byte, error) {
 	return p.parseStdTable(b)
 }
 
-func (p *parser) parseArrayTable(b []byte) (ast.Reference, []byte, error) {
+func (p *Parser) parseArrayTable(b []byte) (reference, []byte, error) {
 	// array-table = array-table-open key array-table-close
 	// array-table-open  = %x5B.5B ws  ; [[ Double left square bracket
 	// array-table-close = ws %x5D.5D  ; ]] Double right square bracket
-	ref := p.builder.Push(ast.Node{
-		Kind: ast.ArrayTable,
+	ref := p.builder.Push(Node{
+		Kind: ArrayTable,
 	})
 
 	b = b[2:]
@@ -174,12 +289,12 @@ func (p *parser) parseArrayTable(b []byte) (ast.Reference, []byte, error) {
 	return ref, b, err
 }
 
-func (p *parser) parseStdTable(b []byte) (ast.Reference, []byte, error) {
+func (p *Parser) parseStdTable(b []byte) (reference, []byte, error) {
 	// std-table = std-table-open key std-table-close
 	// std-table-open  = %x5B ws     ; [ Left square bracket
 	// std-table-close = ws %x5D     ; ] Right square bracket
-	ref := p.builder.Push(ast.Node{
-		Kind: ast.Table,
+	ref := p.builder.Push(Node{
+		Kind: Table,
 	})
 
 	b = b[1:]
@@ -199,15 +314,15 @@ func (p *parser) parseStdTable(b []byte) (ast.Reference, []byte, error) {
 	return ref, b, err
 }
 
-func (p *parser) parseKeyval(b []byte) (ast.Reference, []byte, error) {
+func (p *Parser) parseKeyval(b []byte) (reference, []byte, error) {
 	// keyval = key keyval-sep val
-	ref := p.builder.Push(ast.Node{
-		Kind: ast.KeyValue,
+	ref := p.builder.Push(Node{
+		Kind: KeyValue,
 	})
 
 	key, b, err := p.parseKey(b)
 	if err != nil {
-		return ast.InvalidReference, nil, err
+		return invalidReference, nil, err
 	}
 
 	// keyval-sep = ws %x3D ws ; =
@@ -215,12 +330,12 @@ func (p *parser) parseKeyval(b []byte) (ast.Reference, []byte, error) {
 	b = p.parseWhitespace(b)
 
 	if len(b) == 0 {
-		return ast.InvalidReference, nil, newDecodeError(b, "expected = after a key, but the document ends there")
+		return invalidReference, nil, NewParserError(b, "expected = after a key, but the document ends there")
 	}
 
 	b, err = expect('=', b)
 	if err != nil {
-		return ast.InvalidReference, nil, err
+		return invalidReference, nil, err
 	}
 
 	b = p.parseWhitespace(b)
@@ -237,12 +352,12 @@ func (p *parser) parseKeyval(b []byte) (ast.Reference, []byte, error) {
 }
 
 //nolint:cyclop,funlen
-func (p *parser) parseVal(b []byte) (ast.Reference, []byte, error) {
+func (p *Parser) parseVal(b []byte) (reference, []byte, error) {
 	// val = string / boolean / array / inline-table / date-time / float / integer
-	ref := ast.InvalidReference
+	ref := invalidReference
 
 	if len(b) == 0 {
-		return ref, nil, newDecodeError(b, "expected value, not eof")
+		return ref, nil, NewParserError(b, "expected value, not eof")
 	}
 
 	var err error
@@ -259,8 +374,8 @@ func (p *parser) parseVal(b []byte) (ast.Reference, []byte, error) {
 		}
 
 		if err == nil {
-			ref = p.builder.Push(ast.Node{
-				Kind: ast.String,
+			ref = p.builder.Push(Node{
+				Kind: String,
 				Raw:  p.Range(raw),
 				Data: v,
 			})
@@ -277,8 +392,8 @@ func (p *parser) parseVal(b []byte) (ast.Reference, []byte, error) {
 		}
 
 		if err == nil {
-			ref = p.builder.Push(ast.Node{
-				Kind: ast.String,
+			ref = p.builder.Push(Node{
+				Kind: String,
 				Raw:  p.Range(raw),
 				Data: v,
 			})
@@ -287,22 +402,22 @@ func (p *parser) parseVal(b []byte) (ast.Reference, []byte, error) {
 		return ref, b, err
 	case 't':
 		if !scanFollowsTrue(b) {
-			return ref, nil, newDecodeError(atmost(b, 4), "expected 'true'")
+			return ref, nil, NewParserError(atmost(b, 4), "expected 'true'")
 		}
 
-		ref = p.builder.Push(ast.Node{
-			Kind: ast.Bool,
+		ref = p.builder.Push(Node{
+			Kind: Bool,
 			Data: b[:4],
 		})
 
 		return ref, b[4:], nil
 	case 'f':
 		if !scanFollowsFalse(b) {
-			return ref, nil, newDecodeError(atmost(b, 5), "expected 'false'")
+			return ref, nil, NewParserError(atmost(b, 5), "expected 'false'")
 		}
 
-		ref = p.builder.Push(ast.Node{
-			Kind: ast.Bool,
+		ref = p.builder.Push(Node{
+			Kind: Bool,
 			Data: b[:5],
 		})
 
@@ -324,7 +439,7 @@ func atmost(b []byte, n int) []byte {
 	return b[:n]
 }
 
-func (p *parser) parseLiteralString(b []byte) ([]byte, []byte, []byte, error) {
+func (p *Parser) parseLiteralString(b []byte) ([]byte, []byte, []byte, error) {
 	v, rest, err := scanLiteralString(b)
 	if err != nil {
 		return nil, nil, nil, err
@@ -333,19 +448,20 @@ func (p *parser) parseLiteralString(b []byte) ([]byte, []byte, []byte, error) {
 	return v, v[1 : len(v)-1], rest, nil
 }
 
-func (p *parser) parseInlineTable(b []byte) (ast.Reference, []byte, error) {
+func (p *Parser) parseInlineTable(b []byte) (reference, []byte, error) {
 	// inline-table = inline-table-open [ inline-table-keyvals ] inline-table-close
 	// inline-table-open  = %x7B ws     ; {
 	// inline-table-close = ws %x7D     ; }
 	// inline-table-sep   = ws %x2C ws  ; , Comma
 	// inline-table-keyvals = keyval [ inline-table-sep inline-table-keyvals ]
-	parent := p.builder.Push(ast.Node{
-		Kind: ast.InlineTable,
+	parent := p.builder.Push(Node{
+		Kind: InlineTable,
+		Raw:  p.Range(b[:1]),
 	})
 
 	first := true
 
-	var child ast.Reference
+	var child reference
 
 	b = b[1:]
 
@@ -356,7 +472,7 @@ func (p *parser) parseInlineTable(b []byte) (ast.Reference, []byte, error) {
 		b = p.parseWhitespace(b)
 
 		if len(b) == 0 {
-			return parent, nil, newDecodeError(previousB[:1], "inline table is incomplete")
+			return parent, nil, NewParserError(previousB[:1], "inline table is incomplete")
 		}
 
 		if b[0] == '}' {
@@ -371,7 +487,7 @@ func (p *parser) parseInlineTable(b []byte) (ast.Reference, []byte, error) {
 			b = p.parseWhitespace(b)
 		}
 
-		var kv ast.Reference
+		var kv reference
 
 		kv, b, err = p.parseKeyval(b)
 		if err != nil {
@@ -394,7 +510,7 @@ func (p *parser) parseInlineTable(b []byte) (ast.Reference, []byte, error) {
 }
 
 //nolint:funlen,cyclop
-func (p *parser) parseValArray(b []byte) (ast.Reference, []byte, error) {
+func (p *Parser) parseValArray(b []byte) (reference, []byte, error) {
 	// array = array-open [ array-values ] ws-comment-newline array-close
 	// array-open =  %x5B ; [
 	// array-close = %x5D ; ]
@@ -405,23 +521,39 @@ func (p *parser) parseValArray(b []byte) (ast.Reference, []byte, error) {
 	arrayStart := b
 	b = b[1:]
 
-	parent := p.builder.Push(ast.Node{
-		Kind: ast.Array,
+	parent := p.builder.Push(Node{
+		Kind: Array,
 	})
 
+	// First indicates whether the parser is looking for the first element
+	// (non-comment) of the array.
 	first := true
 
-	var lastChild ast.Reference
+	lastChild := invalidReference
+
+	addChild := func(valueRef reference) {
+		if lastChild == invalidReference {
+			p.builder.AttachChild(parent, valueRef)
+		} else {
+			p.builder.Chain(lastChild, valueRef)
+		}
+		lastChild = valueRef
+	}
 
 	var err error
 	for len(b) > 0 {
-		b, err = p.parseOptionalWhitespaceCommentNewline(b)
+		cref := invalidReference
+		cref, b, err = p.parseOptionalWhitespaceCommentNewline(b)
 		if err != nil {
 			return parent, nil, err
 		}
 
+		if cref != invalidReference {
+			addChild(cref)
+		}
+
 		if len(b) == 0 {
-			return parent, nil, newDecodeError(arrayStart[:1], "array is incomplete")
+			return parent, nil, NewParserError(arrayStart[:1], "array is incomplete")
 		}
 
 		if b[0] == ']' {
@@ -430,16 +562,19 @@ func (p *parser) parseValArray(b []byte) (ast.Reference, []byte, error) {
 
 		if b[0] == ',' {
 			if first {
-				return parent, nil, newDecodeError(b[0:1], "array cannot start with comma")
+				return parent, nil, NewParserError(b[0:1], "array cannot start with comma")
 			}
 			b = b[1:]
 
-			b, err = p.parseOptionalWhitespaceCommentNewline(b)
+			cref, b, err = p.parseOptionalWhitespaceCommentNewline(b)
 			if err != nil {
 				return parent, nil, err
 			}
+			if cref != invalidReference {
+				addChild(cref)
+			}
 		} else if !first {
-			return parent, nil, newDecodeError(b[0:1], "array elements must be separated by commas")
+			return parent, nil, NewParserError(b[0:1], "array elements must be separated by commas")
 		}
 
 		// TOML allows trailing commas in arrays.
@@ -447,23 +582,22 @@ func (p *parser) parseValArray(b []byte) (ast.Reference, []byte, error) {
 			break
 		}
 
-		var valueRef ast.Reference
+		var valueRef reference
 		valueRef, b, err = p.parseVal(b)
 		if err != nil {
 			return parent, nil, err
 		}
 
-		if first {
-			p.builder.AttachChild(parent, valueRef)
-		} else {
-			p.builder.Chain(lastChild, valueRef)
-		}
-		lastChild = valueRef
+		addChild(valueRef)
 
-		b, err = p.parseOptionalWhitespaceCommentNewline(b)
+		cref, b, err = p.parseOptionalWhitespaceCommentNewline(b)
 		if err != nil {
 			return parent, nil, err
 		}
+		if cref != invalidReference {
+			addChild(cref)
+		}
+
 		first = false
 	}
 
@@ -472,15 +606,34 @@ func (p *parser) parseValArray(b []byte) (ast.Reference, []byte, error) {
 	return parent, rest, err
 }
 
-func (p *parser) parseOptionalWhitespaceCommentNewline(b []byte) ([]byte, error) {
+func (p *Parser) parseOptionalWhitespaceCommentNewline(b []byte) (reference, []byte, error) {
+	rootCommentRef := invalidReference
+	latestCommentRef := invalidReference
+
+	addComment := func(ref reference) {
+		if rootCommentRef == invalidReference {
+			rootCommentRef = ref
+		} else if latestCommentRef == invalidReference {
+			p.builder.AttachChild(rootCommentRef, ref)
+			latestCommentRef = ref
+		} else {
+			p.builder.Chain(latestCommentRef, ref)
+			latestCommentRef = ref
+		}
+	}
+
 	for len(b) > 0 {
 		var err error
 		b = p.parseWhitespace(b)
 
 		if len(b) > 0 && b[0] == '#' {
-			_, b, err = scanComment(b)
+			var ref reference
+			ref, b, err = p.parseComment(b)
 			if err != nil {
-				return nil, err
+				return invalidReference, nil, err
+			}
+			if ref != invalidReference {
+				addComment(ref)
 			}
 		}
 
@@ -491,17 +644,17 @@ func (p *parser) parseOptionalWhitespaceCommentNewline(b []byte) ([]byte, error)
 		if b[0] == '\n' || b[0] == '\r' {
 			b, err = p.parseNewline(b)
 			if err != nil {
-				return nil, err
+				return invalidReference, nil, err
 			}
 		} else {
 			break
 		}
 	}
 
-	return b, nil
+	return rootCommentRef, b, nil
 }
 
-func (p *parser) parseMultilineLiteralString(b []byte) ([]byte, []byte, []byte, error) {
+func (p *Parser) parseMultilineLiteralString(b []byte) ([]byte, []byte, []byte, error) {
 	token, rest, err := scanMultilineLiteralString(b)
 	if err != nil {
 		return nil, nil, nil, err
@@ -520,7 +673,7 @@ func (p *parser) parseMultilineLiteralString(b []byte) ([]byte, []byte, []byte,
 }
 
 //nolint:funlen,gocognit,cyclop
-func (p *parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, error) {
+func (p *Parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, error) {
 	// ml-basic-string = ml-basic-string-delim [ newline ] ml-basic-body
 	// ml-basic-string-delim
 	// ml-basic-string-delim = 3quotation-mark
@@ -549,13 +702,13 @@ func (p *parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, er
 	startIdx := i
 	endIdx := len(token) - len(`"""`)
 
-	if escaped < 0 {
+	if !escaped {
 		str := token[startIdx:endIdx]
-		verr := utf8TomlValidAlreadyEscaped(str)
+		verr := characters.Utf8TomlValidAlreadyEscaped(str)
 		if verr.Zero() {
 			return token, str, rest, nil
 		}
-		return nil, nil, nil, newDecodeError(str[verr.Index:verr.Index+verr.Size], "invalid UTF-8")
+		return nil, nil, nil, NewParserError(str[verr.Index:verr.Index+verr.Size], "invalid UTF-8")
 	}
 
 	var builder bytes.Buffer
@@ -578,6 +731,10 @@ func (p *parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, er
 				switch token[i+j] {
 				case ' ', '\t':
 					continue
+				case '\r':
+					if token[i+j+1] == '\n' {
+						continue
+					}
 				case '\n':
 					isLastNonWhitespaceOnLine = true
 				}
@@ -613,6 +770,8 @@ func (p *parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, er
 				builder.WriteByte('\r')
 			case 't':
 				builder.WriteByte('\t')
+			case 'e':
+				builder.WriteByte(0x1B)
 			case 'u':
 				x, err := hexToRune(atmost(token[i+1:], 4), 4)
 				if err != nil {
@@ -629,13 +788,13 @@ func (p *parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, er
 				builder.WriteRune(x)
 				i += 8
 			default:
-				return nil, nil, nil, newDecodeError(token[i:i+1], "invalid escaped character %#U", c)
+				return nil, nil, nil, NewParserError(token[i:i+1], "invalid escaped character %#U", c)
 			}
 			i++
 		} else {
-			size := utf8ValidNext(token[i:])
+			size := characters.Utf8ValidNext(token[i:])
 			if size == 0 {
-				return nil, nil, nil, newDecodeError(token[i:i+1], "invalid character %#U", c)
+				return nil, nil, nil, NewParserError(token[i:i+1], "invalid character %#U", c)
 			}
 			builder.Write(token[i : i+size])
 			i += size
@@ -645,7 +804,7 @@ func (p *parser) parseMultilineBasicString(b []byte) ([]byte, []byte, []byte, er
 	return token, builder.Bytes(), rest, nil
 }
 
-func (p *parser) parseKey(b []byte) (ast.Reference, []byte, error) {
+func (p *Parser) parseKey(b []byte) (reference, []byte, error) {
 	// key = simple-key / dotted-key
 	// simple-key = quoted-key / unquoted-key
 	//
@@ -656,11 +815,11 @@ func (p *parser) parseKey(b []byte) (ast.Reference, []byte, error) {
 	// dot-sep   = ws %x2E ws  ; . Period
 	raw, key, b, err := p.parseSimpleKey(b)
 	if err != nil {
-		return ast.InvalidReference, nil, err
+		return invalidReference, nil, err
 	}
 
-	ref := p.builder.Push(ast.Node{
-		Kind: ast.Key,
+	ref := p.builder.Push(Node{
+		Kind: Key,
 		Raw:  p.Range(raw),
 		Data: key,
 	})
@@ -675,8 +834,8 @@ func (p *parser) parseKey(b []byte) (ast.Reference, []byte, error) {
 				return ref, nil, err
 			}
 
-			p.builder.PushAndChain(ast.Node{
-				Kind: ast.Key,
+			p.builder.PushAndChain(Node{
+				Kind: Key,
 				Raw:  p.Range(raw),
 				Data: key,
 			})
@@ -688,14 +847,14 @@ func (p *parser) parseKey(b []byte) (ast.Reference, []byte, error) {
 	return ref, b, nil
 }
 
-func (p *parser) parseSimpleKey(b []byte) (raw, key, rest []byte, err 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")
+	}
+
 	// 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
-	if len(b) == 0 {
-		return nil, nil, nil, newDecodeError(b, "key is incomplete")
-	}
-
 	switch {
 	case b[0] == '\'':
 		return p.parseLiteralString(b)
@@ -705,12 +864,12 @@ 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, newDecodeError(b[0:1], "invalid character at start of key: %c", b[0])
+		return nil, nil, nil, NewParserError(b[0:1], "invalid character at start of key: %c", b[0])
 	}
 }
 
 //nolint:funlen,cyclop
-func (p *parser) parseBasicString(b []byte) ([]byte, []byte, []byte, error) {
+func (p *Parser) parseBasicString(b []byte) ([]byte, []byte, []byte, error) {
 	// basic-string = quotation-mark *basic-char quotation-mark
 	// quotation-mark = %x22            ; "
 	// basic-char = basic-unescaped / escaped
@@ -736,13 +895,13 @@ 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.
-	if escaped < 0 {
+	if !escaped {
 		str := token[startIdx:endIdx]
-		verr := utf8TomlValidAlreadyEscaped(str)
+		verr := characters.Utf8TomlValidAlreadyEscaped(str)
 		if verr.Zero() {
 			return token, str, rest, nil
 		}
-		return nil, nil, nil, newDecodeError(str[verr.Index:verr.Index+verr.Size], "invalid UTF-8")
+		return nil, nil, nil, NewParserError(str[verr.Index:verr.Index+verr.Size], "invalid UTF-8")
 	}
 
 	i := startIdx
@@ -770,6 +929,8 @@ func (p *parser) parseBasicString(b []byte) ([]byte, []byte, []byte, error) {
 				builder.WriteByte('\r')
 			case 't':
 				builder.WriteByte('\t')
+			case 'e':
+				builder.WriteByte(0x1B)
 			case 'u':
 				x, err := hexToRune(token[i+1:len(token)-1], 4)
 				if err != nil {
@@ -787,13 +948,13 @@ func (p *parser) parseBasicString(b []byte) ([]byte, []byte, []byte, error) {
 				builder.WriteRune(x)
 				i += 8
 			default:
-				return nil, nil, nil, newDecodeError(token[i:i+1], "invalid escaped character %#U", c)
+				return nil, nil, nil, NewParserError(token[i:i+1], "invalid escaped character %#U", c)
 			}
 			i++
 		} else {
-			size := utf8ValidNext(token[i:])
+			size := characters.Utf8ValidNext(token[i:])
 			if size == 0 {
-				return nil, nil, nil, newDecodeError(token[i:i+1], "invalid character %#U", c)
+				return nil, nil, nil, NewParserError(token[i:i+1], "invalid character %#U", c)
 			}
 			builder.Write(token[i : i+size])
 			i += size
@@ -805,7 +966,7 @@ func (p *parser) parseBasicString(b []byte) ([]byte, []byte, []byte, error) {
 
 func hexToRune(b []byte, length int) (rune, error) {
 	if len(b) < length {
-		return -1, newDecodeError(b, "unicode point needs %d character, not %d", length, len(b))
+		return -1, NewParserError(b, "unicode point needs %d character, not %d", length, len(b))
 	}
 	b = b[:length]
 
@@ -820,19 +981,19 @@ func hexToRune(b []byte, length int) (rune, error) {
 		case 'A' <= c && c <= 'F':
 			d = uint32(c - 'A' + 10)
 		default:
-			return -1, newDecodeError(b[i:i+1], "non-hex character")
+			return -1, NewParserError(b[i:i+1], "non-hex character")
 		}
 		r = r*16 + d
 	}
 
 	if r > unicode.MaxRune || 0xD800 <= r && r < 0xE000 {
-		return -1, newDecodeError(b, "escape sequence is invalid Unicode code point")
+		return -1, NewParserError(b, "escape sequence is invalid Unicode code point")
 	}
 
 	return rune(r), nil
 }
 
-func (p *parser) parseWhitespace(b []byte) []byte {
+func (p *Parser) parseWhitespace(b []byte) []byte {
 	// ws = *wschar
 	// wschar =  %x20  ; Space
 	// wschar =/ %x09  ; Horizontal tab
@@ -842,31 +1003,32 @@ func (p *parser) parseWhitespace(b []byte) []byte {
 }
 
 //nolint:cyclop
-func (p *parser) parseIntOrFloatOrDateTime(b []byte) (ast.Reference, []byte, error) {
+func (p *Parser) parseIntOrFloatOrDateTime(b []byte) (reference, []byte, error) {
 	switch b[0] {
 	case 'i':
 		if !scanFollowsInf(b) {
-			return ast.InvalidReference, nil, newDecodeError(atmost(b, 3), "expected 'inf'")
+			return invalidReference, nil, NewParserError(atmost(b, 3), "expected 'inf'")
 		}
 
-		return p.builder.Push(ast.Node{
-			Kind: ast.Float,
+		return p.builder.Push(Node{
+			Kind: Float,
 			Data: b[:3],
+			Raw:  p.Range(b[:3]),
 		}), b[3:], nil
 	case 'n':
 		if !scanFollowsNan(b) {
-			return ast.InvalidReference, nil, newDecodeError(atmost(b, 3), "expected 'nan'")
+			return invalidReference, nil, NewParserError(atmost(b, 3), "expected 'nan'")
 		}
 
-		return p.builder.Push(ast.Node{
-			Kind: ast.Float,
+		return p.builder.Push(Node{
+			Kind: Float,
 			Data: b[:3],
+			Raw:  p.Range(b[:3]),
 		}), b[3:], nil
 	case '+', '-':
 		return p.scanIntOrFloat(b)
 	}
 
-	//nolint:gomnd
 	if len(b) < 3 {
 		return p.scanIntOrFloat(b)
 	}
@@ -884,24 +1046,14 @@ func (p *parser) parseIntOrFloatOrDateTime(b []byte) (ast.Reference, []byte, err
 		if idx == 2 && c == ':' || (idx == 4 && c == '-') {
 			return p.scanDateTime(b)
 		}
+
+		break
 	}
 
 	return p.scanIntOrFloat(b)
 }
 
-func digitsToInt(b []byte) int {
-	x := 0
-
-	for _, d := range b {
-		x *= 10
-		x += int(d - '0')
-	}
-
-	return x
-}
-
-//nolint:gocognit,cyclop
-func (p *parser) scanDateTime(b []byte) (ast.Reference, []byte, error) {
+func (p *Parser) scanDateTime(b []byte) (reference, []byte, error) {
 	// scans for contiguous characters in [0-9T:Z.+-], and up to one space if
 	// followed by a digit.
 	hasDate := false
@@ -924,7 +1076,7 @@ byteLoop:
 			}
 		case c == 'T' || c == 't' || c == ':' || c == '.':
 			hasTime = true
-		case c == '+' || c == '-' || c == 'Z' || c == 'z':
+		case c == '+' || c == 'Z' || c == 'z':
 			hasTz = true
 		case c == ' ':
 			if !seenSpace && i+1 < len(b) && isDigit(b[i+1]) {
@@ -944,33 +1096,33 @@ byteLoop:
 		}
 	}
 
-	var kind ast.Kind
+	var kind Kind
 
 	if hasTime {
 		if hasDate {
 			if hasTz {
-				kind = ast.DateTime
+				kind = DateTime
 			} else {
-				kind = ast.LocalDateTime
+				kind = LocalDateTime
 			}
 		} else {
-			kind = ast.LocalTime
+			kind = LocalTime
 		}
 	} else {
-		kind = ast.LocalDate
+		kind = LocalDate
 	}
 
-	return p.builder.Push(ast.Node{
+	return p.builder.Push(Node{
 		Kind: kind,
 		Data: b[:i],
 	}), b[i:], nil
 }
 
 //nolint:funlen,gocognit,cyclop
-func (p *parser) scanIntOrFloat(b []byte) (ast.Reference, []byte, error) {
+func (p *Parser) scanIntOrFloat(b []byte) (reference, []byte, error) {
 	i := 0
 
-	if len(b) > 2 && b[0] == '0' && b[1] != '.' && b[1] != 'e' {
+	if len(b) > 2 && b[0] == '0' && b[1] != '.' && b[1] != 'e' && b[1] != 'E' {
 		var isValidRune validRuneFn
 
 		switch b[1] {
@@ -993,9 +1145,10 @@ func (p *parser) scanIntOrFloat(b []byte) (ast.Reference, []byte, error) {
 			}
 		}
 
-		return p.builder.Push(ast.Node{
-			Kind: ast.Integer,
+		return p.builder.Push(Node{
+			Kind: Integer,
 			Data: b[:i],
+			Raw:  p.Range(b[:i]),
 		}), b[i:], nil
 	}
 
@@ -1016,42 +1169,45 @@ func (p *parser) scanIntOrFloat(b []byte) (ast.Reference, []byte, error) {
 
 		if c == 'i' {
 			if scanFollowsInf(b[i:]) {
-				return p.builder.Push(ast.Node{
-					Kind: ast.Float,
+				return p.builder.Push(Node{
+					Kind: Float,
 					Data: b[:i+3],
+					Raw:  p.Range(b[:i+3]),
 				}), b[i+3:], nil
 			}
 
-			return ast.InvalidReference, nil, newDecodeError(b[i:i+1], "unexpected character 'i' while scanning for a number")
+			return invalidReference, nil, NewParserError(b[i:i+1], "unexpected character 'i' while scanning for a number")
 		}
 
 		if c == 'n' {
 			if scanFollowsNan(b[i:]) {
-				return p.builder.Push(ast.Node{
-					Kind: ast.Float,
+				return p.builder.Push(Node{
+					Kind: Float,
 					Data: b[:i+3],
+					Raw:  p.Range(b[:i+3]),
 				}), b[i+3:], nil
 			}
 
-			return ast.InvalidReference, nil, newDecodeError(b[i:i+1], "unexpected character 'n' while scanning for a number")
+			return invalidReference, nil, NewParserError(b[i:i+1], "unexpected character 'n' while scanning for a number")
 		}
 
 		break
 	}
 
 	if i == 0 {
-		return ast.InvalidReference, b, newDecodeError(b, "incomplete number")
+		return invalidReference, b, NewParserError(b, "incomplete number")
 	}
 
-	kind := ast.Integer
+	kind := Integer
 
 	if isFloat {
-		kind = ast.Float
+		kind = Float
 	}
 
-	return p.builder.Push(ast.Node{
+	return p.builder.Push(Node{
 		Kind: kind,
 		Data: b[:i],
+		Raw:  p.Range(b[:i]),
 	}), b[i:], nil
 }
 
@@ -1078,11 +1234,11 @@ func isValidBinaryRune(r byte) bool {
 
 func expect(x byte, b []byte) ([]byte, error) {
 	if len(b) == 0 {
-		return nil, newDecodeError(b, "expected character %c but the document ended here", x)
+		return nil, NewParserError(b, "expected character %c but the document ended here", x)
 	}
 
 	if b[0] != x {
-		return nil, newDecodeError(b[0:1], "expected character %c", x)
+		return nil, NewParserError(b[0:1], "expected character %c", x)
 	}
 
 	return b[1:], nil

unstable/parser_test.go

@@ -0,0 +1,629 @@
+package unstable
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/pelletier/go-toml/v2/internal/assert"
+)
+
+func TestParser_AST_Numbers(t *testing.T) {
+	examples := []struct {
+		desc  string
+		input string
+		kind  Kind
+		err   bool
+	}{
+		{
+			desc:  "integer just digits",
+			input: `1234`,
+			kind:  Integer,
+		},
+		{
+			desc:  "integer zero",
+			input: `0`,
+			kind:  Integer,
+		},
+		{
+			desc:  "integer sign",
+			input: `+99`,
+			kind:  Integer,
+		},
+		{
+			desc:  "integer hex uppercase",
+			input: `0xDEADBEEF`,
+			kind:  Integer,
+		},
+		{
+			desc:  "integer hex lowercase",
+			input: `0xdead_beef`,
+			kind:  Integer,
+		},
+		{
+			desc:  "integer octal",
+			input: `0o01234567`,
+			kind:  Integer,
+		},
+		{
+			desc:  "integer binary",
+			input: `0b11010110`,
+			kind:  Integer,
+		},
+		{
+			desc:  "float zero",
+			input: `0.0`,
+			kind:  Float,
+		},
+		{
+			desc:  "float positive zero",
+			input: `+0.0`,
+			kind:  Float,
+		},
+		{
+			desc:  "float negative zero",
+			input: `-0.0`,
+			kind:  Float,
+		},
+		{
+			desc:  "float pi",
+			input: `3.1415`,
+			kind:  Float,
+		},
+		{
+			desc:  "float negative",
+			input: `-0.01`,
+			kind:  Float,
+		},
+		{
+			desc:  "float signed exponent",
+			input: `5e+22`,
+			kind:  Float,
+		},
+		{
+			desc:  "float exponent lowercase",
+			input: `1e06`,
+			kind:  Float,
+		},
+		{
+			desc:  "float exponent uppercase",
+			input: `-2E-2`,
+			kind:  Float,
+		},
+		{
+			desc:  "float fractional with exponent",
+			input: `6.626e-34`,
+			kind:  Float,
+		},
+		{
+			desc:  "float underscores",
+			input: `224_617.445_991_228`,
+			kind:  Float,
+		},
+		{
+			desc:  "inf",
+			input: `inf`,
+			kind:  Float,
+		},
+		{
+			desc:  "inf negative",
+			input: `-inf`,
+			kind:  Float,
+		},
+		{
+			desc:  "inf positive",
+			input: `+inf`,
+			kind:  Float,
+		},
+		{
+			desc:  "nan",
+			input: `nan`,
+			kind:  Float,
+		},
+		{
+			desc:  "nan negative",
+			input: `-nan`,
+			kind:  Float,
+		},
+		{
+			desc:  "nan positive",
+			input: `+nan`,
+			kind:  Float,
+		},
+	}
+
+	for _, e := range examples {
+		e := e
+		t.Run(e.desc, func(t *testing.T) {
+			p := Parser{}
+			p.Reset([]byte(`A = ` + e.input))
+			p.NextExpression()
+			err := p.Error()
+			if e.err {
+				assert.Error(t, err)
+			} else {
+				assert.NoError(t, err)
+
+				expected := astNode{
+					Kind: KeyValue,
+					Children: []astNode{
+						{Kind: e.kind, Data: []byte(e.input)},
+						{Kind: Key, Data: []byte(`A`)},
+					},
+				}
+				compareNode(t, expected, p.Expression())
+			}
+		})
+	}
+}
+
+type (
+	astNode struct {
+		Kind     Kind
+		Data     []byte
+		Children []astNode
+	}
+)
+
+func compareNode(t *testing.T, e astNode, n *Node) {
+	t.Helper()
+	assert.Equal(t, e.Kind, n.Kind)
+	assert.Equal(t, e.Data, n.Data)
+
+	compareIterator(t, e.Children, n.Children())
+}
+
+func compareIterator(t *testing.T, expected []astNode, actual Iterator) {
+	t.Helper()
+	idx := 0
+
+	for actual.Next() {
+		n := actual.Node()
+
+		if idx >= len(expected) {
+			t.Fatal("extra child in actual tree")
+		}
+		e := expected[idx]
+
+		compareNode(t, e, n)
+
+		idx++
+	}
+
+	if idx < len(expected) {
+		t.Fatal("missing children in actual", "idx =", idx, "expected =", len(expected))
+	}
+}
+
+//nolint:funlen
+func TestParser_AST(t *testing.T) {
+	examples := []struct {
+		desc  string
+		input string
+		ast   astNode
+		err   bool
+	}{
+		{
+			desc:  "simple string assignment",
+			input: `A = "hello"`,
+			ast: astNode{
+				Kind: KeyValue,
+				Children: []astNode{
+					{
+						Kind: String,
+						Data: []byte(`hello`),
+					},
+					{
+						Kind: Key,
+						Data: []byte(`A`),
+					},
+				},
+			},
+		},
+		{
+			desc:  "simple bool assignment",
+			input: `A = true`,
+			ast: astNode{
+				Kind: KeyValue,
+				Children: []astNode{
+					{
+						Kind: Bool,
+						Data: []byte(`true`),
+					},
+					{
+						Kind: Key,
+						Data: []byte(`A`),
+					},
+				},
+			},
+		},
+		{
+			desc:  "array of strings",
+			input: `A = ["hello", ["world", "again"]]`,
+			ast: astNode{
+				Kind: KeyValue,
+				Children: []astNode{
+					{
+						Kind: Array,
+						Children: []astNode{
+							{
+								Kind: String,
+								Data: []byte(`hello`),
+							},
+							{
+								Kind: Array,
+								Children: []astNode{
+									{
+										Kind: String,
+										Data: []byte(`world`),
+									},
+									{
+										Kind: String,
+										Data: []byte(`again`),
+									},
+								},
+							},
+						},
+					},
+					{
+						Kind: Key,
+						Data: []byte(`A`),
+					},
+				},
+			},
+		},
+		{
+			desc:  "array of arrays of strings",
+			input: `A = ["hello", "world"]`,
+			ast: astNode{
+				Kind: KeyValue,
+				Children: []astNode{
+					{
+						Kind: Array,
+						Children: []astNode{
+							{
+								Kind: String,
+								Data: []byte(`hello`),
+							},
+							{
+								Kind: String,
+								Data: []byte(`world`),
+							},
+						},
+					},
+					{
+						Kind: Key,
+						Data: []byte(`A`),
+					},
+				},
+			},
+		},
+		{
+			desc:  "inline table",
+			input: `name = { first = "Tom", last = "Preston-Werner" }`,
+			ast: astNode{
+				Kind: KeyValue,
+				Children: []astNode{
+					{
+						Kind: InlineTable,
+						Children: []astNode{
+							{
+								Kind: KeyValue,
+								Children: []astNode{
+									{Kind: String, Data: []byte(`Tom`)},
+									{Kind: Key, Data: []byte(`first`)},
+								},
+							},
+							{
+								Kind: KeyValue,
+								Children: []astNode{
+									{Kind: String, Data: []byte(`Preston-Werner`)},
+									{Kind: Key, Data: []byte(`last`)},
+								},
+							},
+						},
+					},
+					{
+						Kind: Key,
+						Data: []byte(`name`),
+					},
+				},
+			},
+		},
+	}
+
+	for _, e := range examples {
+		e := e
+		t.Run(e.desc, func(t *testing.T) {
+			p := Parser{}
+			p.Reset([]byte(e.input))
+			p.NextExpression()
+			err := p.Error()
+			if e.err {
+				assert.Error(t, err)
+			} else {
+				assert.NoError(t, err)
+				compareNode(t, e.ast, p.Expression())
+			}
+		})
+	}
+}
+
+func BenchmarkParseBasicStringWithUnicode(b *testing.B) {
+	p := &Parser{}
+	b.Run("4", func(b *testing.B) {
+		input := []byte(`"\u1234\u5678\u9ABC\u1234\u5678\u9ABC"`)
+		b.ReportAllocs()
+		b.SetBytes(int64(len(input)))
+
+		for i := 0; i < b.N; i++ {
+			p.parseBasicString(input)
+		}
+	})
+	b.Run("8", func(b *testing.B) {
+		input := []byte(`"\u12345678\u9ABCDEF0\u12345678\u9ABCDEF0"`)
+		b.ReportAllocs()
+		b.SetBytes(int64(len(input)))
+
+		for i := 0; i < b.N; i++ {
+			p.parseBasicString(input)
+		}
+	})
+}
+
+func BenchmarkParseBasicStringsEasy(b *testing.B) {
+	p := &Parser{}
+
+	for _, size := range []int{1, 4, 8, 16, 21} {
+		b.Run(strconv.Itoa(size), func(b *testing.B) {
+			input := []byte(`"` + strings.Repeat("A", size) + `"`)
+
+			b.ReportAllocs()
+			b.SetBytes(int64(len(input)))
+
+			for i := 0; i < b.N; i++ {
+				p.parseBasicString(input)
+			}
+		})
+	}
+}
+
+func TestParser_AST_DateTimes(t *testing.T) {
+	examples := []struct {
+		desc  string
+		input string
+		kind  Kind
+		err   bool
+	}{
+		{
+			desc:  "offset-date-time with delim 'T' and UTC offset",
+			input: `2021-07-21T12:08:05Z`,
+			kind:  DateTime,
+		},
+		{
+			desc:  "offset-date-time with space delim and +8hours offset",
+			input: `2021-07-21 12:08:05+08:00`,
+			kind:  DateTime,
+		},
+		{
+			desc:  "local-date-time with nano second",
+			input: `2021-07-21T12:08:05.666666666`,
+			kind:  LocalDateTime,
+		},
+		{
+			desc:  "local-date-time",
+			input: `2021-07-21T12:08:05`,
+			kind:  LocalDateTime,
+		},
+		{
+			desc:  "local-date",
+			input: `2021-07-21`,
+			kind:  LocalDate,
+		},
+	}
+
+	for _, e := range examples {
+		e := e
+		t.Run(e.desc, func(t *testing.T) {
+			p := Parser{}
+			p.Reset([]byte(`A = ` + e.input))
+			p.NextExpression()
+			err := p.Error()
+			if e.err {
+				assert.Error(t, err)
+			} else {
+				assert.NoError(t, err)
+
+				expected := astNode{
+					Kind: KeyValue,
+					Children: []astNode{
+						{Kind: e.kind, Data: []byte(e.input)},
+						{Kind: Key, Data: []byte(`A`)},
+					},
+				}
+				compareNode(t, expected, p.Expression())
+			}
+		})
+	}
+}
+
+// This example demonstrates how to parse a TOML document and preserving
+// comments.  Comments are stored in the AST as Comment nodes. This example
+// displays the structure of the full AST generated by the parser using the
+// following structure:
+//
+//  1. Each root-level expression is separated by three dashes.
+//  2. Bytes associated to a node are displayed in square brackets.
+//  3. Siblings have the same indentation.
+//  4. Children of a node are indented one level.
+func ExampleParser_comments() {
+	doc := `# Top of the document comment.
+# Optional, any amount of lines.
+
+# Above table.
+[table] # Next to table.
+# Above simple value.
+key = "value" # Next to simple value.
+# Below simple value.
+
+# Some comment alone.
+
+# Multiple comments, on multiple lines.
+
+# Above inline table.
+name = { first = "Tom", last = "Preston-Werner" } # Next to inline table.
+# Below inline table.
+
+# Above array.
+array = [ 1, 2, 3 ] # Next to one-line array.
+# Below array.
+
+# Above multi-line array.
+key5 = [ # Next to start of inline array.
+  # Second line before array content.
+  1, # Next to first element.
+  # After first element.
+  # Before second element.
+  2,
+  3, # Next to last element
+  # After last element.
+] # Next to end of array.
+# Below multi-line array.
+
+# Before array table.
+[[products]] # Next to array table.
+# After array table.
+`
+
+	var printGeneric func(*Parser, int, *Node)
+	printGeneric = func(p *Parser, indent int, e *Node) {
+		if e == nil {
+			return
+		}
+		s := p.Shape(e.Raw)
+		x := fmt.Sprintf("%d:%d->%d:%d (%d->%d)", s.Start.Line, s.Start.Column, s.End.Line, s.End.Column, s.Start.Offset, s.End.Offset)
+		fmt.Printf("%-25s | %s%s [%s]\n", x, strings.Repeat("  ", indent), e.Kind, e.Data)
+		printGeneric(p, indent+1, e.Child())
+		printGeneric(p, indent, e.Next())
+	}
+
+	printTree := func(p *Parser) {
+		for p.NextExpression() {
+			e := p.Expression()
+			fmt.Println("---")
+			printGeneric(p, 0, e)
+		}
+		if err := p.Error(); err != nil {
+			panic(err)
+		}
+	}
+
+	p := &Parser{
+		KeepComments: true,
+	}
+	p.Reset([]byte(doc))
+	printTree(p)
+
+	// Output:
+	// ---
+	// 1:1->1:31 (0->30)         | Comment [# Top of the document comment.]
+	// ---
+	// 2:1->2:33 (31->63)        | Comment [# Optional, any amount of lines.]
+	// ---
+	// 4:1->4:15 (65->79)        | Comment [# Above table.]
+	// ---
+	// 1:1->1:1 (0->0)           | Table []
+	// 5:2->5:7 (81->86)         |   Key [table]
+	// 5:9->5:25 (88->104)       | Comment [# Next to table.]
+	// ---
+	// 6:1->6:22 (105->126)      | Comment [# Above simple value.]
+	// ---
+	// 1:1->1:1 (0->0)           | 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.]
+	// ---
+	// 8:1->8:22 (165->186)      | Comment [# Below simple value.]
+	// ---
+	// 10:1->10:22 (188->209)    | Comment [# Some comment alone.]
+	// ---
+	// 12:1->12:40 (211->250)    | Comment [# Multiple comments, on multiple lines.]
+	// ---
+	// 14:1->14:22 (252->273)    | Comment [# Above inline table.]
+	// ---
+	// 1:1->1:1 (0->0)           | KeyValue []
+	// 15:8->15:9 (281->282)     |   InlineTable []
+	// 1:1->1:1 (0->0)           |     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:32->15:48 (305->321)   |       String [Preston-Werner]
+	// 15:25->15:29 (298->302)   |       Key [last]
+	// 15:1->15:5 (274->278)     |   Key [name]
+	// 15:51->15:74 (324->347)   | Comment [# Next to inline table.]
+	// ---
+	// 16:1->16:22 (348->369)    | Comment [# Below inline table.]
+	// ---
+	// 18:1->18:15 (371->385)    | Comment [# Above array.]
+	// ---
+	// 1:1->1:1 (0->0)           | KeyValue []
+	// 1:1->1:1 (0->0)           |   Array []
+	// 19:11->19:12 (396->397)   |     Integer [1]
+	// 19:14->19:15 (399->400)   |     Integer [2]
+	// 19:17->19:18 (402->403)   |     Integer [3]
+	// 19:1->19:6 (386->391)     |   Key [array]
+	// 19:21->19:46 (406->431)   | Comment [# Next to one-line array.]
+	// ---
+	// 20:1->20:15 (432->446)    | Comment [# Below array.]
+	// ---
+	// 22:1->22:26 (448->473)    | Comment [# Above multi-line array.]
+	// ---
+	// 1:1->1:1 (0->0)           | 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.]
+	// 25:3->25:4 (556->557)     |     Integer [1]
+	// 25:6->25:30 (559->583)    |     Comment [# Next to first element.]
+	// 26:3->26:25 (586->608)    |       Comment [# After first element.]
+	// 27:3->27:27 (611->635)    |       Comment [# Before second element.]
+	// 28:3->28:4 (638->639)     |     Integer [2]
+	// 29:3->29:4 (643->644)     |     Integer [3]
+	// 29:6->29:28 (646->668)    |     Comment [# Next to last element]
+	// 30:3->30:24 (671->692)    |       Comment [# After last element.]
+	// 23:1->23:5 (474->478)     |   Key [key5]
+	// 31:3->31:26 (695->718)    | Comment [# Next to end of array.]
+	// ---
+	// 32:1->32:26 (719->744)    | Comment [# Below multi-line array.]
+	// ---
+	// 34:1->34:22 (746->767)    | Comment [# Before array table.]
+	// ---
+	// 1:1->1:1 (0->0)           | ArrayTable []
+	// 35:3->35:11 (770->778)    |   Key [products]
+	// 35:14->35:36 (781->803)   | Comment [# Next to array table.]
+	// ---
+	// 36:1->36:21 (804->824)    | Comment [# After array table.]
+}
+
+func ExampleParser() {
+	doc := `
+	hello = "world"
+	value = 42
+	`
+	p := Parser{}
+	p.Reset([]byte(doc))
+	for p.NextExpression() {
+		e := p.Expression()
+		fmt.Printf("Expression: %s\n", e.Kind)
+		value := e.Value()
+		it := e.Key()
+		k := it.Node() // shortcut: we know there is no dotted key in the example
+		fmt.Printf("%s -> (%s) %s\n", k.Data, value.Kind, value.Data)
+	}
+
+	// Output:
+	// Expression: KeyValue
+	// hello -> (String) world
+	// Expression: KeyValue
+	// value -> (Integer) 42
+}

unstable/scanner.go

@@ -1,4 +1,6 @@
-package toml
+package unstable
+
+import "github.com/pelletier/go-toml/v2/internal/characters"
 
 func scanFollows(b []byte, pattern string) bool {
 	n := len(pattern)
@@ -53,17 +55,17 @@ func scanLiteralString(b []byte) ([]byte, []byte, error) {
 		switch b[i] {
 		case '\'':
 			return b[:i+1], b[i+1:], nil
-		case '\n':
-			return nil, nil, newDecodeError(b[i:i+1], "literal strings cannot have new lines")
+		case '\n', '\r':
+			return nil, nil, NewParserError(b[i:i+1], "literal strings cannot have new lines")
 		}
-		size := utf8ValidNext(b[i:])
+		size := characters.Utf8ValidNext(b[i:])
 		if size == 0 {
-			return nil, nil, newDecodeError(b[i:i+1], "invalid character")
+			return nil, nil, NewParserError(b[i:i+1], "invalid character")
 		}
 		i += size
 	}
 
-	return nil, nil, newDecodeError(b[len(b):], "unterminated literal string")
+	return nil, nil, NewParserError(b[len(b):], "unterminated literal string")
 }
 
 func scanMultilineLiteralString(b []byte) ([]byte, []byte, error) {
@@ -76,49 +78,61 @@ func scanMultilineLiteralString(b []byte) ([]byte, []byte, error) {
 	// mll-char = %x09 / %x20-26 / %x28-7E / non-ascii
 	// mll-quotes = 1*2apostrophe
 	for i := 3; i < len(b); {
-		if scanFollowsMultilineLiteralStringDelimiter(b[i:]) {
-			i += 3
+		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.
+				// 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
+				}
+				i++
+
+				if i >= len(b) || b[i] != '\'' {
+					return b[:i], b[i:], nil
+				}
+				i++
+
+				if i < len(b) && b[i] == '\'' {
+					return nil, nil, NewParserError(b[i-3:i+1], "''' not allowed in multiline literal string")
+				}
 
-			if i >= len(b) || b[i] != '\'' {
 				return b[:i], b[i:], nil
 			}
-			i++
-
-			if i >= len(b) || b[i] != '\'' {
-				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`)
 			}
-			i++
-
-			if i < len(b) && b[i] == '\'' {
-				return nil, nil, newDecodeError(b[i-3:i+1], "''' not allowed in multiline literal string")
+			if b[i+1] != '\n' {
+				return nil, nil, NewParserError(b[i:i+2], `need a \n after \r`)
 			}
-
-			return b[:i], b[i:], nil
+			i += 2 // skip the \n
+			continue
 		}
-		size := utf8ValidNext(b[i:])
+		size := characters.Utf8ValidNext(b[i:])
 		if size == 0 {
-			return nil, nil, newDecodeError(b[i:i+1], "invalid character")
+			return nil, nil, NewParserError(b[i:i+1], "invalid character")
 		}
 		i += size
 	}
 
-	return nil, nil, newDecodeError(b[len(b):], `multiline literal string not terminated by '''`)
+	return nil, nil, NewParserError(b[len(b):], `multiline literal string not terminated by '''`)
 }
 
 func scanWindowsNewline(b []byte) ([]byte, []byte, error) {
 	const lenCRLF = 2
 	if len(b) < lenCRLF {
-		return nil, nil, newDecodeError(b, "windows new line expected")
+		return nil, nil, NewParserError(b, "windows new line expected")
 	}
 
 	if b[1] != '\n' {
-		return nil, nil, newDecodeError(b, `windows new line should be \r\n`)
+		return nil, nil, NewParserError(b, `windows new line should be \r\n`)
 	}
 
 	return b[:lenCRLF], b[lenCRLF:], nil
@@ -137,7 +151,6 @@ func scanWhitespace(b []byte) ([]byte, []byte) {
 	return b, b[len(b):]
 }
 
-//nolint:unparam
 func scanComment(b []byte) ([]byte, []byte, error) {
 	// comment-start-symbol = %x23 ; #
 	// non-ascii = %x80-D7FF / %xE000-10FFFF
@@ -149,9 +162,15 @@ func scanComment(b []byte) ([]byte, []byte, error) {
 		if b[i] == '\n' {
 			return b[:i], b[i:], nil
 		}
-		size := utf8ValidNext(b[i:])
+		if b[i] == '\r' {
+			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")
+		}
+		size := characters.Utf8ValidNext(b[i:])
 		if size == 0 {
-			return nil, nil, newDecodeError(b[i:i+1], "invalid character in comment")
+			return nil, nil, NewParserError(b[i:i+1], "invalid character in comment")
 		}
 
 		i += size
@@ -160,50 +179,34 @@ func scanComment(b []byte) ([]byte, []byte, error) {
 	return b, b[len(b):], nil
 }
 
-func scanBasicString(b []byte) ([]byte, int, []byte, error) {
+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
-	escaped := -1 // index of the first \. -1 means no escape character in there.
+	escaped := false
 	i := 1
 
-loop:
 	for ; i < len(b); i++ {
 		switch b[i] {
 		case '"':
 			return b[:i+1], escaped, b[i+1:], nil
-		case '\n':
-			return nil, escaped, nil, newDecodeError(b[i:i+1], "basic strings cannot have new lines")
+		case '\n', '\r':
+			return nil, escaped, nil, NewParserError(b[i:i+1], "basic strings cannot have new lines")
 		case '\\':
 			if len(b) < i+2 {
-				return nil, escaped, nil, newDecodeError(b[i:i+1], "need a character after \\")
-			}
-			escaped = i
-			i += 2 // skip the next character
-			break loop
-		}
-	}
-
-	for ; i < len(b); i++ {
-		switch b[i] {
-		case '"':
-			return b[:i+1], escaped, b[i+1:], nil
-		case '\n':
-			return nil, escaped, nil, newDecodeError(b[i:i+1], "basic strings cannot have new lines")
-		case '\\':
-			if len(b) < i+2 {
-				return nil, escaped, nil, newDecodeError(b[i:i+1], "need a character after \\")
+				return nil, escaped, nil, NewParserError(b[i:i+1], "need a character after \\")
 			}
+			escaped = true
 			i++ // skip the next character
 		}
 	}
 
-	return nil, escaped, nil, newDecodeError(b[len(b):], `basic string not terminated by "`)
+	return nil, escaped, nil, NewParserError(b[len(b):], `basic string not terminated by "`)
 }
 
-func scanMultilineBasicString(b []byte) ([]byte, int, []byte, error) {
+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
@@ -215,10 +218,9 @@ func scanMultilineBasicString(b []byte) ([]byte, int, []byte, error) {
 	// mlb-unescaped = wschar / %x21 / %x23-5B / %x5D-7E / non-ascii
 	// mlb-escaped-nl = escape ws newline *( wschar / newline )
 
-	escaped := -1
+	escaped := false
 	i := 3
 
-loop:
 	for ; i < len(b); i++ {
 		switch b[i] {
 		case '"':
@@ -242,34 +244,27 @@ loop:
 				i++
 
 				if i < len(b) && b[i] == '"' {
-					return nil, escaped, nil, newDecodeError(b[i-3:i+1], `""" not allowed in multiline basic string`)
+					return nil, escaped, nil, NewParserError(b[i-3:i+1], `""" not allowed in multiline basic string`)
 				}
 
 				return b[:i], escaped, b[i:], nil
 			}
 		case '\\':
 			if len(b) < i+2 {
-				return nil, escaped, nil, newDecodeError(b[len(b):], "need a character after \\")
-			}
-			escaped = i
-			i += 2 // skip the next character
-			break loop
-		}
-	}
-
-	for ; i < len(b); i++ {
-		switch b[i] {
-		case '"':
-			if scanFollowsMultilineBasicStringDelimiter(b[i:]) {
-				return b[:i+3], escaped, b[i+3:], nil
-			}
-		case '\\':
-			if len(b) < i+2 {
-				return nil, escaped, nil, newDecodeError(b[len(b):], "need a character after \\")
+				return nil, escaped, nil, NewParserError(b[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`)
+			}
+			if b[i+1] != '\n' {
+				return nil, escaped, nil, NewParserError(b[i:i+2], `need a \n after \r`)
+			}
+			i++ // skip the \n
 		}
 	}
 
-	return nil, escaped, nil, newDecodeError(b[len(b):], `multiline basic string not terminated by """`)
+	return nil, escaped, nil, NewParserError(b[len(b):], `multiline basic string not terminated by """`)
 }

unstable/unmarshaler.go

@@ -0,0 +1,7 @@
+package unstable
+
+// The Unmarshaler interface may be implemented by types to customize their
+// behavior when being unmarshaled from a TOML document.
+type Unmarshaler interface {
+	UnmarshalTOML(value *Node) error
+}