feat: add Statements, the top-level statement iterator

Assisted-by: GLM 5.3 Flash

examples/statements/main.go

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: MIT
+
+// Command statements walks the top-level statements of a TOML document with
+// interpres.Statements, the shape a configuration tool uses to read the
+// sections it cares about and skip the rest.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"sourcedock.dev/petrbalvin/interpres/v2"
+)
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func run(stdin io.Reader, stdout io.Writer) error {
+	for stmt, err := range interpres.Statements(stdin) {
+		if err != nil {
+			return err
+		}
+		switch {
+		case stmt.Index >= 0:
+			fmt.Fprintf(stdout, "[[%s]] #%d\n", stmt.Key, stmt.Index)
+		case stmt.Table != nil:
+			fmt.Fprintf(stdout, "[%s] keys: %v\n", stmt.Key, stmt.Table.Keys())
+		default:
+			fmt.Fprintf(stdout, "%s = %v\n", stmt.Key, stmt.Value)
+		}
+	}
+	return nil
+}