# Changelog

All notable changes to **interpres** are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [development]

### Added

- `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](https://github.com/toml-lang/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.