configtoml

README

config-toml

Read TOML configuration through config

Part of the phpboyscout Go toolkit — small, framework-free Go modules extracted from go-tool-base. Documented with the parent module at config.go.phpboyscout.uk

---

config reads and writes only YAML. Every other file format is a sibling module like this one, so a consumer who needs TOML takes it and one who does not pays nothing for it.

import (
	"gitlab.com/phpboyscout/go/config"
	configtoml "gitlab.com/phpboyscout/go/config-toml"
)

store, err := config.NewStore(ctx,
	config.WithFiles(fsys, "/etc/app.yaml"),                    // YAML, the default
	config.WithBackend(configtoml.New(fsys, "/etc/app.toml")),  // outranks it
)

A TOML layer takes part in precedence, per-key merge and provenance exactly as a YAML file does. Tables become nested keys, arrays of tables become slices, and scalar types survive.

Read-only, for now

This module reads TOML and does not yet write it. No existing Go library round-trips TOML without destroying the file — comments gone, sections alphabetised, indentation injected — which is the merged-view write the whole toolkit exists to prevent. Structure-preserving TOML writing needs a document editor of its own, and it is a committed fast follow rather than a prerequisite: reading is most of the value, and blocking it behind that work would serve no one.

Because the codec is read-only, a write to a key a TOML layer defines is not applied to it — routing skips it and the write lands in the next writable layer down, reported as shadowed rather than failing. When write support lands it will be a minor version, and configtoml.New will not change.

What it costs

The config graph plus one TOML parser (pelletier/go-toml/v2, no dependencies of its own) — asserted by an allowlist test, so an unforeseen transitive addition fails the build rather than arriving quietly. No filesystem library: you supply the config.FS.

License

See LICENSE.

Documentation

Overview

Package configtoml reads TOML configuration through the config codec seam.

It is a sibling of the config core, not part of it: a consumer who needs TOML takes this module, and one who does not pays nothing for it. The core reads and writes only YAML; every other file format is a module like this one.

config.NewStore(ctx,
	config.WithFiles(fsys, "/etc/app.yaml"),        // YAML, the default
	config.WithBackend(configtoml.New(fsys, "/etc/app.toml")),
)

A TOML layer takes part in precedence, per-key merge, provenance and write routing exactly as a YAML file does.

Writing preserves the file

Re-serialising a decoded document destroys it — comments gone, sections alphabetised, indentation injected — the merged-view write the whole toolkit exists to prevent. So writes edit the document in place: reading is go-toml/v2's, and editing is a targeted byte replacement located by go-toml/v2's own source ranges, so an edit changes one value or adds one key and leaves comments, table headers and key order exactly as they were.

Setting or removing a key, and adding a key to an existing section or the top level, are supported. Writing into a sub-path of an inline-table value, or adding a key to an empty section, is refused with config.ErrInvalidTarget rather than guessed.

Index

• func New(filesystem config.FS, path string) config.Backend
• type Codec
  • func (Codec) Apply(path string, src []byte, edits []config.Edit) ([]byte, error)
  • func (Codec) Check(path string, src []byte) error
  • func (Codec) Decode(path string, src []byte) ([]map[string]any, error)
  • func (Codec) Empty() []byte
  • func (Codec) PreservesComments() bool

Functions

func New

func New(filesystem config.FS, path string) config.Backend

New reads and writes a TOML document.

Types

type Codec

type Codec struct{}

Codec reads a TOML document and edits it in place. New uses it, and it is exported so a backend adapter can reuse it as a value decoder — a Consul or etcd key whose value is a TOML document, decoded into a subtree via that adapter's WithValueCodec option. It is a config.Codec (and config.EditingCodec).

Reading (Decode) is go-toml/v2's; editing (Check, Apply, Empty, in write.go) is a targeted byte replacement located by go-toml/v2's source ranges. The two never cross: decoded values feed the read side, and edits are applied to bytes, and the seam re-decodes what was written.

A TOML document's top level is always a table, so — unlike JSON — there is no non-object shape to refuse.

func (Codec) Apply

func (Codec) Apply(path string, src []byte, edits []config.Edit) ([]byte, error)

Apply folds the edits into the document one at a time, replacing a value's bytes in place or inserting a key, and leaving comments, table headers and key order untouched.

func (Codec) Check

func (Codec) Check(path string, src []byte) error

Check reports whether a TOML source can be edited safely. Every edit is a targeted byte replacement over the parsed document, so anything that parses can be edited — Check surfaces the same parse error Decode would, nothing more.

func (Codec) Decode

func (Codec) Decode(path string, src []byte) ([]map[string]any, error)

func (Codec) Empty

func (Codec) Empty() []byte

Empty returns the content of a new, empty TOML document.

func (Codec) PreservesComments

func (Codec) PreservesComments() bool

PreservesComments reports that a TOML edit retains comments and formatting. Editing is a targeted byte replacement over the parsed document — comments, table headers and key order are left exactly as they were — so this is true, and it backs the file backend's PreservesComments capability. It satisfies config.CommentPreservingCodec.