interpres/CHANGELOG.md

Changelog

All notable changes to interpres are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[development]

Added

• interpres-decode -validate [file ...]: a validate mode beside the toml-test adapter. It parses each named file, or stdin when none are named, prints one line per invalid document to stderr, and exits 0 when all are valid, 1 when one is not, and 2 on a usage or read failure. Install it with go install .../cmd/interpres-decode@latest; releases still ship no binaries.
• DecodeError and EncodeError: decode and encode failures are wrapped in typed errors carrying the key path, read with errors.AsType instead of parsing the message text. The rendered messages keep their shape; the only visible change is that an encode failure on a top-level field no longer gains a meaningless leading dot in its path.
• omitzero and omitempty tag options on encode: toml:"name,omitzero" skips a field whose value is the zero value of its type (a type with an IsZero() bool method decides through the method), and toml:"name,omitempty" skips a nil or empty slice, array, or map. The decoder ignores both options.

Fixed

• Untagged embedded fields now decode symmetrically with encode: an embedded struct receives its keys inline (a nil embedded pointer struct is allocated), an embedded map catches the keys no field claims, and a name clash resolves in favour of the shallower field. A struct with an untagged embedded field previously decoded with all inline keys dropped and did not round-trip.
• Marshal re-emits arrays that mix tables with scalars: the table elements render as inline tables inside the value array. A tree that Parse accepts from such a document previously failed with cannot encode map[string]interface {}.

[1.0.0] - 2026-08-20

First stable release: a dependency-free TOML 1.0 parser and encoder for Go that uses only the standard library and passes the entire toml-test suite (185 valid and 371 invalid cases, 0 failures).

Added

Parsing

• Parse(data []byte) (map[string]any, error): decode a TOML document into an untyped tree.
• Full TOML 1.0 syntax: comments; bare, quoted, and dotted keys; tables ([a.b]) and arrays of tables ([[a]]); basic and literal strings, including multiline (""" / ''') with escape sequences and line-ending backslash trimming; integers in decimal, hex (0x), octal (0o), and binary (0b) with _ separators; floats with exponents and inf / nan; booleans; offset/local date-times, dates, and times; arrays; and inline tables.
• Distinct date-time types: offset date-times decode to time.Time, while LocalDateTime, LocalDate, and LocalTime represent the local variants, each with a String() method returning the TOML-canonical rendering.
• Strict, spec-conformant validation that rejects invalid documents: leading zeros, misplaced underscores, malformed floats and radix literals, control characters in strings and comments, bare carriage returns, non-UTF-8 input, out-of-range Unicode escapes, multiline strings used as keys, single-digit date-time components, duplicate/overwriting inline-table keys, and the full family of table redefinitions (header vs. header, header vs. dotted key, array of tables vs. table, and dotted-key appends to defined tables).
• SyntaxError carrying the 1-based line of a malformed document.

Decoding

• Unmarshal(data []byte, v any): parse and map onto a struct or map[string]any via reflection, with overflow-checked numeric conversion, nested structs, slices, and map[string]T.
• toml:"name" field tags, case-insensitive name fallback, and toml:"-" to skip a field.
• Decoder with DisallowUnknownFields for strict decoding that rejects keys without a destination field, at every struct depth.
• Unmarshaler interface (UnmarshalTOML(data any) error) for types that take full control of their decode.

Encoding

• Marshal(v any) ([]byte, error): encode a struct or map[string]V value to a TOML 1.0 document that re-parses to an equivalent value tree.
• Encoder with chainable policy options: GroupByKind (group-by-kind layout versus declaration order), OmitEmptyArrays, and UseLiteralMultiline.
• Marshaler interface (MarshalTOML() (any, error)) for types that need a custom TOML shape; the returned value is encoded normally.

Cancellation

• ParseContext, UnmarshalContext, MarshalContext, (*Decoder).DecodeContext and (*Encoder).MarshalContext honour a context.Context, checked up front and every 64 statements or fields.

Project

• Standard library only: zero third-party modules.
• cmd/interpres-decode, a toml-test harness adapter (TOML on stdin, tagged JSON on stdout).
• A runnable example, a table-driven Go test suite, and a canonical just recipe set whose gates recipe is the definition of done.
• Hand-written CI pipelines for the test, race and release gates.
• SECURITY.md for private vulnerability reports.