github.com/BurntSushi/toml v0.3.1: Decode, NewEncoder, MetaData

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:golang/github.com/BurntSushi/toml@v0.3.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/BurntSushi/toml@v0.3.1

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:d8b925ee2564573c51d90af49a35b7d544d290d4affb894400420d1d5213a88a","contract":["toml.Decode deserializes TOML formatted documents into Go struct and map fields","toml.NewEncoder serializes Go structs into valid TOML documents preserved across round-trip decoding","toml.MetaData reports defined keys and detects undecoded fields when decoding into partial structs","toml.Decode returns an error on malformed TOML syntax"],"goal":"verify pkg:golang/github.com/BurntSushi/toml@v0.3.1","kind":"HOW","packages":["pkg:golang/github.com/BurntSushi/toml@v0.3.1"],"schemaVersion":1,"symbols":["github.com/BurntSushi/toml.Decode","github.com/BurntSushi/toml.NewEncoder","github.com/BurntSushi/toml.MetaData"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/BurntSushi/toml@v0.3.1"],"schemaVersion":1,"subject":"pkg:golang/github.com/BurntSushi/toml@v0.3.1","symbols":["github.com/BurntSushi/toml.Decode","github.com/BurntSushi/toml.NewEncoder","github.com/BurntSushi/toml.MetaData"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require github.com/BurntSushi/toml v0.3.1

github.com/BurntSushi/toml v0.3.1 h1:WXkYYl6Yr3qBf1K79EBnL4mak0OimBfB0XUf9Vl28OQ=
github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/github.com/BurntSushi/toml@v0.3.1",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/BurntSushi/toml@v0.3.1"
  ]
}

package main

import (
	"fmt"
	"os"

	"github.com/BurntSushi/toml"
	"sample"
)

func main() {
	// Assertion 1: toml.Decode correctly deserializes TOML document into structured types
	rawTOML := `
title = "Sample App"

[owner]
name = "Test Author"
org = "Test Org"

[server]
host = "127.0.0.1"
port = 8080
enabled = true

[clients]
alpha = "10.0.0.1"
beta = "10.0.0.2"
`
	cfg, _, err := sample.DecodeTOML(rawTOML)
	if err != nil {
		fmt.Fprintf(os.Stderr, "DecodeTOML failed: %v\n", err)
		os.Exit(1)
	}
	if cfg.Title != "Sample App" {
		fmt.Fprintf(os.Stderr, "expected title 'Sample App', got %q\n", cfg.Title)
		os.Exit(1)
	}
	if cfg.Owner.Name != "Test Author" || cfg.Owner.Org != "Test Org" {
		fmt.Fprintf(os.Stderr, "unexpected owner info: %+v\n", cfg.Owner)
		os.Exit(1)
	}
	if cfg.Server.Host != "127.0.0.1" || cfg.Server.Port != 8080 || !cfg.Server.Enabled {
		fmt.Fprintf(os.Stderr, "unexpected server info: %+v\n", cfg.Server)
		os.Exit(1)
	}
	if len(cfg.Clients) != 2 || cfg.Clients["alpha"] != "10.0.0.1" {
		fmt.Fprintf(os.Stderr, "unexpected clients map: %+v\n", cfg.Clients)
		os.Exit(1)
	}

	// Assertion 2: toml.NewEncoder encodes struct into TOML format that preserves data on round-trip decode
	encoded, err := sample.EncodeTOML(cfg)
	if err != nil {
		fmt.Fprintf(os.Stderr, "EncodeTOML failed: %v\n", err)
		os.Exit(1)
	}
	roundTripCfg, _, err := sample.DecodeTOML(encoded)
	if err != nil {
		fmt.Fprintf(os.Stderr, "round-trip decode failed: %v\n", err)
		os.Exit(1)
	}
	if roundTripCfg.Title != cfg.Title || roundTripCfg.Server.Port != cfg.Server.Port {
		fmt.Fprintf(os.Stderr, "round-trip mismatch: got %+v, want %+v\n", roundTripCfg, cfg)
		os.Exit(1)
	}

	// Assertion 3: toml.MetaData tracks defined keys and detects undecoded fields
	type PartialConfig struct {
		Title string `toml:"title"`
	}
	var partial PartialConfig
	partialMeta, err := sample.DecodeWithMetadata(rawTOML, &partial)
	if err != nil {
		fmt.Fprintf(os.Stderr, "DecodeWithMetadata failed: %v\n", err)
		os.Exit(1)
	}
	if !partialMeta.IsDefined("title") {
		fmt.Fprintf(os.Stderr, "expected 'title' to be defined in meta\n")
		os.Exit(1)
	}
	undecoded := partialMeta.Undecoded()
	if len(undecoded) == 0 {
		fmt.Fprintf(os.Stderr, "expected undecoded keys for partial struct, got 0\n")
		os.Exit(1)
	}

	// Assertion 4: toml.Decode returns an error on malformed TOML syntax
	invalidTOML := `title = [unclosed array`
	var badCfg sample.Config
	_, badErr := toml.Decode(invalidTOML, &badCfg)
	if badErr == nil {
		fmt.Fprintf(os.Stderr, "expected error for malformed TOML, got nil\n")
		os.Exit(1)
	}

	fmt.Println("All BurntSushi/toml contract assertions passed.")
}

package sample

import (
	"bytes"

	"github.com/BurntSushi/toml"
)

// Config represents a sample configuration structure for TOML serialization.
type Config struct {
	Title   string            `toml:"title"`
	Owner   OwnerInfo         `toml:"owner"`
	Server  ServerInfo        `toml:"server"`
	Clients map[string]string `toml:"clients"`
}

// OwnerInfo represents user details within Config.
type OwnerInfo struct {
	Name string `toml:"name"`
	Org  string `toml:"org"`
}

// ServerInfo represents host and port configuration.
type ServerInfo struct {
	Host    string `toml:"host"`
	Port    int    `toml:"port"`
	Enabled bool   `toml:"enabled"`
}

// DecodeTOML parses a TOML string into a Config and returns the decoded configuration along with MetaData.
func DecodeTOML(data string) (Config, toml.MetaData, error) {
	var cfg Config
	meta, err := toml.Decode(data, &cfg)
	if err != nil {
		return Config{}, meta, err
	}
	return cfg, meta, nil
}

// EncodeTOML serializes a Config struct into a formatted TOML string.
func EncodeTOML(cfg Config) (string, error) {
	var buf bytes.Buffer
	enc := toml.NewEncoder(&buf)
	if err := enc.Encode(cfg); err != nil {
		return "", err
	}
	return buf.String(), nil
}

// DecodeWithMetadata parses raw TOML data into the destination and exposes metadata.
func DecodeWithMetadata(data string, target interface{}) (toml.MetaData, error) {
	return toml.Decode(data, target)
}