interpres/README.md

# interpres

A dependency-free **TOML 1.0 parser for Go** — standard library only, no
third-party modules. Passes the entire
[toml-test](https://github.com/toml-lang/toml-test) suite (185 valid and 371
invalid cases).

`interpres` (Latin for *interpreter*) reads TOML documents into Go values with a
small, `encoding/json`-style API. It is built for embedding in zero-dependency
Go programs that still want their configuration in TOML.

## Install

```sh
go get codeberg.org/petrbalvin/interpres
```

Requires Go 1.26 or newer. The module imports only the standard library.

## Usage

### Decode into a struct

```go
package main

import (
	"fmt"

	"codeberg.org/petrbalvin/interpres"
)

type Config struct {
	Title  string `toml:"title"`
	Server struct {
		Host string `toml:"host"`
		Port int    `toml:"port"`
	} `toml:"server"`
}

func main() {
	data := []byte(`
title = "example"

[server]
host = "127.0.0.1"
port = 9090
`)

	var cfg Config
	if err := interpres.Unmarshal(data, &cfg); err != nil {
		panic(err)
	}
	fmt.Printf("%+v\n", cfg)
}
```

### Untyped tree

```go
tree, err := interpres.Parse(data) // map[string]any
```

### Strict decoding

Reject keys that have no matching struct field — useful for catching typos in
configuration files:

```go
err := interpres.NewDecoder().
	DisallowUnknownFields().
	Decode(data, &cfg)
```

## Struct mapping

Fields are matched to TOML keys by the `toml:"name"` tag, or by a
case-insensitive match on the field name when no tag is present. A tag of `"-"`
skips the field.

| TOML value | Go type (untyped tree) |
|------------|------------------------|
| string | `string` |
| integer | `int64` |
| float | `float64` |
| boolean | `bool` |
| offset date-time | `time.Time` |
| local date-time | `LocalDateTime` |
| local date | `LocalDate` |
| local time | `LocalTime` |
| array | `[]any` |
| table / inline table | `map[string]any` |
| array of tables | `[]map[string]any` |

When decoding into a struct, these map onto the destination's concrete types
(any integer/unsigned/float width, slices, nested structs, and `map[string]T`).

## TOML 1.0 support

`interpres` implements the full [TOML 1.0](https://toml.io/en/v1.0.0) grammar:

- Comments, and bare / quoted / dotted keys.
- Tables `[a.b]` and arrays of tables `[[a]]`.
- Basic and literal strings, including multiline (`"""` / `'''`) with escape
  sequences (`\n`, `\t`, `\uXXXX`, `\UXXXXXXXX`, line-ending backslash).
- 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 (multiline, mixed types) and inline tables.

Invalid documents are rejected per the specification (malformed numbers and
floats, control characters, non-UTF-8 input, out-of-range escapes, table and
inline-table redefinitions, and more).

## Compliance

The parser is verified against the official
[toml-test](https://github.com/toml-lang/toml-test) suite via
`cmd/interpres-decode`:

```sh
go build -o interpres-decode ./cmd/interpres-decode
toml-test ./interpres-decode
```

## License

MIT — see [LICENSE](LICENSE).
Copyright © 2026 [Petr Balvín](https://petrbalvin.org)