130 lines
3.1 KiB
Markdown
130 lines
3.1 KiB
Markdown
# 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)
|