TOML

https://github.com/burntsushi/toml
Admin
TOML is a Go package that provides a reflection interface for encoding and decoding TOML...
Tokens:34,768
Snippets:378
Trust Score:9.8
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install the package

Source: https://github.com/burntsushi/toml/blob/master/README.md

Add the library to your project using the go get command.

```bash
go get github.com/BurntSushi/toml@latest
```

--------------------------------

### MetaData.Type string output example

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/types.md

Example showing the string representation returned by MetaData.Type.

```go
// Example: the string form returned by MetaData.Type
fmt.Printf("%s\n", md.Type("Pi")) // "Float" (tomlFloat.typeString())
```

--------------------------------

### Install and run tomlv

Source: https://github.com/burntsushi/toml/blob/master/cmd/tomlv/README.md

Install the tool via Go and validate a specific TOML file.

```bash
$ go install github.com/BurntSushi/toml/cmd/tomlv@master
$ tomlv some-toml-file.toml
```

--------------------------------

### DecodeFile usage example

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

Example of decoding a TOML file into a configuration struct with error handling.

```go
var config example
meta, err := toml.DecodeFile("example.toml", &config)
if err != nil {
	fmt.Fprintln(os.Stderr, err)
	os.Exit(1)
}
```

--------------------------------

### tomlv -types example

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/cli-tools.md

Example command and output for validating a TOML file and displaying key types.

```bash
% tomlv -types example.toml
Age                                      Integer
Cats                                     Array
    [0]                                  String
```

--------------------------------

### Install and use the validator CLI

Source: https://github.com/burntsushi/toml/blob/master/README.md

Install the tomlv tool to validate TOML files from the command line.

```bash
go install github.com/BurntSushi/toml/cmd/tomlv@latest
tomlv some-toml-file.toml
```

--------------------------------

### Unmarshaler implementation example

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

Example of a custom type implementing UnmarshalTOML to manually populate fields from a raw map.

```go
type Contact struct {
	Name  string
	Email string
}

func (c *Contact) UnmarshalTOML(data any) error {
	if t, ok := data.(map[string]any); ok {
		c.Name, _ = t["name"].(string)
		c.Email, _ = t["email"].(string)
		return nil
	}
	return fmt.Errorf("expected a table for Contact")
}
```

--------------------------------

### Decode usage example

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

Example of using Decode to populate a struct and inspect metadata using IsDefined and Type.

```go
blob := `Age = 25
Cats = ["Cauchy", "Plato"]`
var conf Config
md, err := toml.Decode(blob, &conf)
if err == nil && md.IsDefined("Age") {
	fmt.Printf("%s\n", md.Type("Age")) // "Integer"
}
```

--------------------------------

### TOML output for struct configuration

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/encode.md

The resulting TOML output from the struct configuration example.

```toml
[Servers.alpha]
IP = "10.0.0.1"
Hostname = "alpha"
Enabled = true

[Servers.beta]
IP = "10.0.0.2"
Hostname = "beta"
Enabled = false
```

--------------------------------

### tomlv -json output example

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/cli-tools.md

Example command and output for converting a TOML file to JSON format.

```bash
% tomlv -json config.toml
{
  "title": "example",
  "enabled": true
}
```

--------------------------------

### Invalid Float Examples

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Examples of syntactically incorrect float definitions in TOML.

```toml
# INVALID FLOATS
invalid_float_1 = .7
invalid_float_2 = 7.
invalid_float_3 = 3.e+20
```

--------------------------------

### Encoding a struct configuration

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/encode.md

Example of encoding a nested struct configuration into TOML format.

```go
type Server struct{
	IP       string
	Hostname string
	Enabled  bool
}
type Config struct{
	Map[string]Server
}
conf := Config{Servers: map[string]Server{
	"alpha": Server{IP: "10.0.0.1", Hostname: "alpha", Enabled: true},
	"beta":  Server{IP: "10.0.0.2", Hostname: "beta",  Enabled: false},
}}

enc := toml.NewEncoder(os.Stdout)
if err := enc.Encode(conf); err != nil {
	log.Fatalf("encoding failed: %s", err)
}
```

--------------------------------

### Invalid table redefinition examples

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Tables cannot be defined more than once.

```toml
# DO NOT DO THIS

[fruit]
apple = "red"

[fruit]
orange = "orange"
```

```toml
# DO NOT DO THIS EITHER

[fruit]
apple = "red"

[fruit.apple]
texture = "smooth"
```

--------------------------------

### Invalid TOML Key/Value Pair Examples

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Examples of invalid syntax including missing values and multiple pairs on a single line.

```toml
key = # INVALID
```

```toml
first = "Tom" last = "Preston-Werner" # INVALID
```

--------------------------------

### Implementing Marshaler for custom types

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/encode.md

Example implementation of the Marshaler interface for a custom struct.

```go
type MyId struct{ V string }

func (m *MyId) MarshalTOML() ([]byte, error) {
	if m.V == "" {
		return nil, fmt.Errorf("empty id")
	}
	return []byte(`"` + m.V + `"`), nil
}
```

--------------------------------

### tomlv -types output format

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/cli-tools.md

Example of the output format when using the -types flag to display key types.

```text
Server    Hash
    IP   String
```

--------------------------------

### Equivalent Standard Table Definitions

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Shows the standard table structure equivalent to the provided inline table examples.

```toml
[name]
first = "Tom"
last = "Preston-Werner"

[point]
x = 1
y = 2

[animal]
type.name = "pug"

[contact.personal]
name = "Donald Duck"
email = "donald@duckburg.com"

[contact.work]
name = "Coin cleaner"
email = "donald@ScroogeCorp.com"
```

--------------------------------

### Marshal usage example

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/encode.md

Basic usage of toml.Marshal to encode a struct into TOML format.

```go
type Distro struct{ Name string; Version string }
out, err := toml.Marshal(Distro{Name: "nixos", Version: "24.11"})
// out == `Name = "nixos"\nVersion = "24.11"\n`
```

--------------------------------

### Apply toml struct tags

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/configuration.md

Examples of using various `toml` tag configurations to control field mapping, exclusion, and conditional omission.

```go
type Config struct {
	ObscureKey string `toml:"some_key_NAME"`          // explicit key name
	SkipMe     string `toml:"-"`                      // excluded entirely
	Note       string `toml:"note,omitempty"`         // dropped when empty string
	Ratio      float  `toml:"ratio,omitzero"`         // dropped when 0.0
	Opt        string `toml:"opt,omitempty,omitzero"` // both options
}
```

--------------------------------

### Invalid Key Definitions

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Examples of invalid key redefinitions or conflicting structures.

```toml
# DO NOT DO THIS
name = "Tom"
name = "Pradyun"
```

```toml
# THIS WILL NOT WORK
spelling = "favorite"
"spelling" = "favourite"
```

```toml
# This makes the key "fruit" into a table.
fruit.apple.smooth = true

# So then you can add to the table "fruit" like so:
fruit.orange = 2
```

```toml
# THE FOLLOWING IS INVALID

# This defines the value of fruit.apple to be an integer.
fruit.apple = 1

# But then this treats fruit.apple like it's a table.
# You can't turn an integer into a table.
fruit.apple.smooth = true
```

--------------------------------

### Equivalent standard table definitions

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Standard table syntax equivalent to the provided inline table examples.

```toml
[name]
first = "Tom"
last = "Preston-Werner"

[point]
x = 1
y = 2

[animal]
type.name = "pug"
```

--------------------------------

### Basic usage with time types

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

Example of decoding TOML data into a struct containing int, time.Time, and time.Duration fields.

```go
type Config struct {
	Age  int
	DOB  time.Time
	Wait time.Duration
}
var conf Config
md, err := toml.NewDecoder(strings.NewReader(`
Age = 25
DOB = 1987-07-05T05:45:00Z
Wait = "5m10s"
`)).Decode(&conf)
```

--------------------------------

### Unmarshal usage example

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

Basic usage of Unmarshal to decode a TOML byte slice into a configuration struct.

```go
var conf Config
err := toml.Unmarshal([]byte(`Age = 25
Cats = ["Cauchy", "Plato"]`), &conf)
if err != nil {
	log.Fatal(err)
}
```

--------------------------------

### Primitive decoding usage

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

Example of using toml.Primitive to delay decoding of a specific field.

```go
type Config struct {
	Data toml.Primitive // decode lazily
}
var conf Config
_, err := toml.Decode(blob, &conf)
```

--------------------------------

### Decoding a Primitive Value Example

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

Demonstrates capturing a TOML value into a Primitive field and decoding it later into a concrete type.

```go
type Config struct{ Data toml.Primitive }
var conf Config
md, err := toml.Decode(`a = [1, 2, 3]`, &conf)

// Later, once we know the concrete type:
var nums []int
err := md.PrimitiveDecode(conf.Data, &nums)
```

--------------------------------

### Encoding a value with custom indentation

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/encode.md

Example of creating an encoder, configuring the indentation to a tab character, and encoding a value to standard output.

```go
enc := toml.NewEncoder(os.Stdout)
enc.Indent = "\t" // tab indentation
err := enc.Encode(value)
```

--------------------------------

### JSON mapping of dotted integer keys

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

The JSON representation of the dotted integer key example.

```json
{ "3": { "14159": "pi" } }
```

--------------------------------

### Marshal error handling

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/encode.md

Example of handling errors when passing invalid top-level types to Marshal.

```go
out, err := toml.Marshal(map[string]int{"k": 1})
if err != nil { // err: "toml: top-level values must be Go maps or structs"
	log.Fatal(err)
}
```

--------------------------------

### Define TOML integers

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Examples of basic integer definitions including positive, negative, and zero values.

```toml
int1 = +99
int2 = 42
int3 = 0
int4 = -17
```

--------------------------------

### Valid Float Representations

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Examples of valid TOML floats using fractional parts, exponents, or both.

```toml
# fractional
flt1 = +1.0
flt2 = 3.1415
flt3 = -0.01

# exponent
flt4 = 5e+22
flt5 = 1e06
flt6 = -2E-2

# both
flt7 = 6.626e-34
```

--------------------------------

### Unmarshal error handling with ParseError

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

Example of inspecting a returned ParseError to provide detailed, annotated error information.

```go
var conf Config
err := toml.Unmarshal(data, &conf)
if err != nil {
	var perr toml.ParseError
	if errors.As(err, &perr) {
		log.Fatal(perr.ErrorWithPosition()) // detailed, annotated snippet
	}
	log.Fatal(err)
}
```

--------------------------------

### Define Offset Date-Time values

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Examples of RFC 3339 formatted date-times with offsets, including fractional seconds.

```toml
odt1 = 1979-05-27T07:32:00Z
odt2 = 1979-05-27T00:32:00-07:00
odt3 = 1979-05-27T00:32:00.5-07:00
odt4 = 1979-05-27T00:32:00.999999-07:00
```

--------------------------------

### Position.withCol method

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/parse-error.md

Computes the column number from the byte offset Start given the raw TOML input.

```go
func (p Position) withCol(tomlFile string) Position {
	var (
		pos   int
		lines = strings.Split(tomlFile, "\n")
	)
	for i := range lines {
		ll := len(lines[i]) + 1 // +1 for the removed newline
		if pos+ll >= p.Start {
			p.Col = max(p.Start-pos+1, 1) // Should never happen, but just in case.
			break
		}
		pos += ll
	}
	return p
}
```

--------------------------------

### Define Local Date-Time values

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Examples of date-times without offsets, representing a time without a specific timezone.

```toml
ldt1 = 1979-05-27T07:32:00
ldt2 = 1979-05-27T07:32:00.5
ldt3 = 1979-05-27T00:32:00.999999
```

--------------------------------

### JSON representation of dotted keys

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

The resulting JSON structure for the provided dotted key example.

```json
{
  "name": "Orange",
  "physical": {
    "color": "orange",
    "shape": "round"
  },
  "site": {
    "google.com": true
  }
}
```

--------------------------------

### Define the root table

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

The root table starts at the beginning of the document and ends before the first header.

```toml
# Top-level table begins.
name = "Fido"
breed = "pug"

# Top-level table ends.
[owner]
name = "Regina Dogman"
member_since = 1999-08-04
```

--------------------------------

### Represent nested TOML arrays as JSON

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Shows the JSON mapping for the nested TOML array of tables example.

```json
{
  "fruits": [
    {
      "name": "apple",
      "physical": {
        "color": "red",
        "shape": "round"
      },
      "varieties": [{ "name": "red delicious" }, { "name": "granny smith" }]
    },
    {
      "name": "banana",
      "varieties": [{ "name": "plantain" }]
    }
  ]
}
```

--------------------------------

### Invalid TOML: Out of order definition

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Example of an invalid TOML document where a subtable is defined before its parent array.

```toml
# INVALID TOML DOC
[fruit.physical]  # subtable, but to which parent element should it belong?
color = "red"
shape = "round"

[[fruit]]  # parser must throw an error upon discovering that "fruit" is
           # an array rather than a table
name = "apple"
```

--------------------------------

### Define TOML Comments

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Comments start with a hash symbol and continue to the end of the line, unless inside a string.

```toml
# This is a full-line comment
key = "value"  # This is a comment at the end of a line
another = "# This is not a comment"
```

--------------------------------

### Catching ParseError with errors.As

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/errors.md

Demonstrates how to use errors.As to identify a ParseError and access its detailed error reporting methods and wrapped cause.

```go
md, err := toml.Decode(data, &conf)
if err != nil {
	var perr toml.ParseError
	if errors.As(err, &perr) {
		fmt.Fprintln(os.Stderr, perr.ErrorWithUsage())
		fmt.Fprintln(os.Stderr, "cause: ", perr.Unwrap().Error())
	} else {
		fmt.Fprintln(os.Stderr, err)
	}
}
```

--------------------------------

### Recommended dotted key ordering

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Grouping related dotted keys together is the recommended practice.

```toml
# RECOMMENDED

apple.type = "fruit"
apple.skin = "thin"
apple.color = "red"

orange.type = "fruit"
orange.skin = "thick"
orange.color = "orange"
```

--------------------------------

### Configure Decoder.MaxDepth usage

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/configuration.md

Demonstrates how to set a custom nesting limit and how to disable the limit by setting it to 0.

```go
dec := toml.NewDecoder(fp)
dec.MaxDepth(64)   // cap nesting at 64 levels
md, err := dec.Decode(&conf)
dec.MaxDepth(0)    // disable the limit
```

--------------------------------

### Configure Encoder.Indent

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/configuration.md

Demonstrates how to change the indentation string for the encoder, such as using tabs or disabling indentation entirely.

```go
enc := toml.NewEncoder(os.Stdout)
enc.Indent = "\t"  // tab-indented output
err := enc.Encode(conf)

enc.Indent = ""    // no indentation
```

--------------------------------

### Define tables using dotted keys

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Demonstrates how to define nested tables using dot-separated keys.

```toml
fruit.apple.color = "red"
# Defines a table named fruit
# Defines a table named fruit.apple

fruit.apple.taste.sweet = true
# Defines a table named fruit.apple.taste
# fruit and fruit.apple were already created
```

--------------------------------

### Top-level entry points for toml package

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/index.md

Lists the primary functions for decoding and encoding TOML data, along with the interfaces for custom type handling.

```go
import "github.com/BurntSushi/toml"

// Decoding — all take a pointer to a destination value:
toml.Unmarshal(data []byte, v any) error                     // []byte input, returns only error
toml.Decode(data string, v any) (MetaData, error)            // string input
toml.DecodeFile(path string, v any) (MetaData, error)        // file path input
toml.DecodeFS(fsys fs.FS, path string, v any) (MetaData, error) // fs.FS input

// Encoding:
toml.Marshal(v any) ([]byte, error)                          // value → TOML bytes

// Interfaces for custom types:
type Unmarshaler interface { UnmarshalTOML(any) error }
type Marshaler   interface { MarshalTOML() ([]byte, error) }
```

--------------------------------

### Define multiple tables with key-value pairs

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Key/value pairs follow the header until the next header or EOF.

```toml
[table-1]
key1 = "some string"
key2 = 123

[table-2]
key1 = "another string"
key2 = 456
```

--------------------------------

### JSON representation of nested arrays

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

The JSON structure corresponding to the nested array of tables example.

```json
{
  "fruits": [
    {
      "name": "apple",
      "physical": {
        "color": "red",
        "shape": "round"
      },
      "varieties": [
        { "name": "red delicious" },
        { "name": "granny smith" }
      ]
    },
    {
      "name": "banana",
      "varieties": [
        { "name": "plantain" }
      ]
    }
  ]
}
```

--------------------------------

### Convert Key to string

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/metadata.md

Renders the key as a dotted string, automatically quoting components that are not bare-key safe.

```go
func (k Key) String() string {
	var b strings.Builder
	b.Grow(len(k) * 25)
outer:
	for i, kk := range k {
		if i > 0 {
			b.WriteByte('.')
		}
		if kk == "" {
			b.WriteString(`""`)
		} else {
			for _, r := range kk {
				// "Inline" isBareKeyChar
				if !((r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '_' || r == '-') {
					b.WriteByte('"')
					b.WriteString(dblQuotedReplacer.Replace(kk))
					b.WriteByte('"')
					continue outer
				}
			}
			b.WriteString(kk)
		}
	}
	return b.String()
}
```

```go
k := toml.Key{"a", "some key"}
fmt.Printf("%s\n", k.String()) // a."some key"
```

--------------------------------

### Navigate Key components

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/metadata.md

Methods to retrieve the parent key or the last component of a key.

```go
func (k Key) parent() Key  { return k[:len(k)-1] } // all except the last piece.
func (k Key) last() string { return k[len(k)-1] }  // last piece of this key.
```

```go
k := Key{"a", "b", "c"}
k.parent() // ["a", "b"]
k.last()   // "c"
```

--------------------------------

### Table ordering recommendations

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Defining tables out-of-order is discouraged.

```toml
# VALID BUT DISCOURAGED
[fruit.apple]
[animal]
[fruit.orange]
```

```toml
# RECOMMENDED
[fruit.apple]
[fruit.orange]
[animal]
```

--------------------------------

### Dotted Keys as Floats

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Demonstrates how dotted keys can be misinterpreted as floats, which is generally discouraged.

```toml
3.14159 = "pi"
```

```json
{ "3": { "14159": "pi" } }
```

--------------------------------

### Keys method usage

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/metadata.md

Returns a slice of all keys present in the TOML document in order of appearance.

```go
func (md *MetaData) Keys() []Key {
	return md.keys
}
```

```go
for _, k := range md.Keys() {
	fmt.Printf("%-20s %s\n", k, md.Type(k...))
}
```

--------------------------------

### Define tables with headers and sub-tables

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Shows the use of table headers and adding sub-tables to existing structures.

```toml
[fruit]
apple.color = "red"
apple.taste.sweet = true

# [fruit.apple]  # INVALID
# [fruit.apple.taste]  # INVALID

[fruit.apple.texture]  # you can add sub-tables
smooth = true
```

--------------------------------

### Inline Table Usage

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Shows how to define arrays of inline tables for concise data representation.

```toml
points = [ { x = 1, y = 2, z = 3 },
           { x = 7, y = 8, z = 9 },
           { x = 2, y = 4, z = 8 } ]
```

--------------------------------

### Error handling for nil pointer

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

Demonstrates the error returned when attempting to decode into a nil pointer.

```go
var conf *Config
_, err := dec.Decode(conf) // err: "toml: cannot decode to nil value of *Config"
```

--------------------------------

### Run toml-test-encoder

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/cli-tools.md

Executes the encoder harness to convert a tagged JSON file into TOML format via stdin.

```bash
% toml-test-encoder < some-json-file.json
```

--------------------------------

### Invalid TOML: Appending to static array

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Example of an invalid TOML document where an attempt is made to append to a statically defined array.

```toml
# INVALID TOML DOC
fruits = []

[[fruits]] # Not allowed
```

--------------------------------

### Define Inline Tables

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Demonstrates compact table definitions using curly braces and nested key/value pairs.

```toml
name = { first = "Tom", last = "Preston-Werner" }
point = {x=1, y=2}
animal = { type.name = "pug" }
contact = {
    personal = {
        name = "Donald Duck",
        email = "donald@duckburg.com",
    },
    work = {
        name = "Coin cleaner",
        email = "donald@ScroogeCorp.com",
    },
}
```

--------------------------------

### Append to Key

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/metadata.md

Creates a new Key by appending a piece to the existing key.

```go
func (k Key) add(piece string) Key {
	newKey := make(Key, len(k)+1)
	copy(newKey, k)
	newKey[len(k)] = piece
	return newKey
}
```

```go
k := Key{"a"}.add("b") // ["a", "b"]
```

--------------------------------

### tomlv usage syntax

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/cli-tools.md

Basic command-line usage for the tomlv validator, supporting file arguments or reading from stdin.

```bash
% tomlv toml-file [ toml-file ... ]
% tomlv -            # read from stdin (also used when no arguments are given)
```

--------------------------------

### Float with Underscores

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Demonstrates the use of underscores for readability in float values.

```toml
flt8 = 224_617.445_991_228
```

--------------------------------

### Run toml-test-decoder

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/cli-tools.md

Executes the decoder harness to convert a TOML file into tagged JSON format via stdin.

```bash
% toml-test-decoder < some-toml-file.toml
```

--------------------------------

### Access structured ParseError fields

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/parse-error.md

Shows how to access specific fields like Position and LastKey, as well as the underlying cause via Unwrap.

```go
var perr toml.ParseError
if errors.As(err, &perr) {
	fmt.Printf("line=%d col=%d offset=%d len=%d lastKey=%q\n",
		perr.Position.Line, perr.Position.Col, perr.Position.Start, perr.Position.Len, perr.LastKey)
	fmt.Printf("cause: %s\n", perr.Unwrap())
}
```

--------------------------------

### toml-test-decoder

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/cli-tools.md

A CLI tool that satisfies the toml-test interface for testing TOML decoders by accepting TOML on stdin and outputting tagged JSON on stdout.

```APIDOC
## toml-test-decoder

### Description
Accepts a TOML document via stdin and outputs the decoded content as JSON with toml-test type tags to stdout.

### Usage
`toml-test-decoder < some-toml-file.toml`

### Input/Output Contract
- **Input (stdin)**: TOML document
- **Output (stdout)**: JSON with toml-test type tags
- **Errors**: Logs 'Error decoding TOML: %s' and exits with status 1
```

--------------------------------

### Inspect TOML key types

Source: https://github.com/burntsushi/toml/blob/master/cmd/tomlv/README.md

Display the inferred types for every key within a TOML file.

```bash
$ tomlv -types some-toml-file.toml
```

--------------------------------

### Define a basic table

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Tables are defined by headers on their own line.

```toml
[table]
```

--------------------------------

### ParseError.ErrorWithUsage method

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/parse-error.md

Returns the error with location context and optional usage guidance.

```go
func (pe ParseError) ErrorWithUsage() string {
	m := pe.ErrorWithPosition()
	if u, ok := pe.err.(interface{ Usage() string }); ok && u.Usage() != "" {
		lines := strings.Split(strings.TrimSpace(u.Usage()), "\n")
		for i := range lines {
			if lines[i] != "" {
				lines[i] = "    " + lines[i]
			}
		}
		return m + "Error help:\n\n" + strings.Join(lines, "\n") + "\n"
	}
	return m
}
```

```text
toml: error: newlines not allowed within inline tables

At line 1, column 18:

      1 | x = [{ key = 42 #
                           ^

Error help:

  Inline tables must always be on a single line:

      table = {key = 42, second = 43}
  ...
```

--------------------------------

### Print annotated error with remediation help

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/parse-error.md

Uses ErrorWithUsage to print the full annotated error along with helpful remediation information.

```go
var perr toml.ParseError
if errors.As(err, &perr) {
	fmt.Fprintln(os.Stderr, perr.ErrorWithUsage())
}
```

--------------------------------

### Use struct tags for custom mapping

Source: https://github.com/burntsushi/toml/blob/master/README.md

Use the `toml` struct tag to map Go fields to specific TOML keys.

```toml
some_key_NAME = "wat"
```

```go
type TOML struct {
    ObscureKey string `toml:"some_key_NAME"`
}
```

--------------------------------

### Define Tables

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Tables are collections of key/value pairs defined by headers in square brackets.

```toml
[table]
```

```toml
[table-1]
key1 = "some string"
key2 = 123

[table-2]
key1 = "another string"
key2 = 456
```

```toml
[dog."tater.man"]
type.name = "pug"
```

```json
{ "dog": { "tater.man": { "type": { "name": "pug" } } } }
```

```toml
[a.b.c]            # this is best practice
[ d.e.f ]          # same as [d.e.f]
[ g .  h  . i ]    # same as [g.h.i]
[ j . "ʞ" . 'l' ]  # same as [j."ʞ".'l']
```

```toml
# [x] you
# [x.y] don't
# [x.y.z] need these
[x.y.z.w] # for this to work

[x] # defining a super-table afterward is ok
```

```toml
# VALID BUT DISCOURAGED
[fruit.apple]
[animal]
[fruit.orange]
```

```toml
# RECOMMENDED
[fruit.apple]
[fruit.orange]
[animal]
```

```toml
# Top-level table begins.
name = "Fido"
breed = "pug"

# Top-level table ends.
[owner]
name = "Regina Dogman"
member_since = 1999-08-04
```

--------------------------------

### Catch and inspect ParseError

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/parse-error.md

Demonstrates the errors.As pattern to catch a ParseError and print the error with its position.

```go
md, err := toml.Decode(data, &conf)
if err != nil {
	var perr toml.ParseError
	if errors.As(err, &perr) {
		log.Fatalf("Error: %s", perr.ErrorWithPosition())
	}
	log.Fatalf("Error: %s", err)
}
```

--------------------------------

### Define tagOptions struct

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/configuration.md

Internal structure used to represent parsed tag options.

```go
type tagOptions struct {
	skip      bool // "-"
	name      string
	omitempty bool
	omitzero  bool
}
```

--------------------------------

### toml-test-encoder

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/cli-tools.md

A CLI tool that satisfies the toml-test interface for testing TOML encoders by accepting tagged JSON on stdin and outputting TOML on stdout.

```APIDOC
## toml-test-encoder

### Description
Accepts tagged JSON via stdin, strips the toml-test tags, and outputs the resulting TOML document to stdout.

### Usage
`toml-test-encoder < some-json-file.json`

### Input/Output Contract
- **Input (stdin)**: JSON with toml-test type tags
- **Output (stdout)**: TOML document
- **Errors**: Logs 'Error decoding JSON: %s' or 'Error encoding TOML: %s' and exits with status 1
```

--------------------------------

### func Marshal(v any) ([]byte, error)

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/encode.md

Returns a TOML representation of the provided Go value.

```APIDOC
## func Marshal(v any) ([]byte, error)

### Description
Returns a TOML representation of the Go value `v` using the default encoder settings.

### Parameters
- **v** (any) - Required - The value to encode. Must be a map or struct at the top level.

### Returns
- **([]byte, error)** - The encoded TOML document as bytes, or an error if encoding fails.
```

--------------------------------

### func DecodeFS(fsys fs.FS, path string, v any) (MetaData, error)

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

Same as DecodeFile, but reads from an arbitrary fs.FS filesystem rather than the OS filesystem.

```APIDOC
## func DecodeFS(fsys fs.FS, path string, v any) (MetaData, error)

### Description
Same as DecodeFile, but reads from an arbitrary fs.FS filesystem rather than the OS filesystem.

### Parameters
- **fsys** (fs.FS) - Required - Filesystem abstraction to open path from.
- **path** (string) - Required - Virtual path inside fsys.
- **v** (any) - Required - Destination pointer.

### Returns
- **(MetaData, error)** - Open errors are returned as-is with a default MetaData{}.
```

--------------------------------

### Format large TOML integers

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Demonstrates using underscores to improve readability in large integer values.

```toml
int5 = 1_000
int6 = 5_349_221
int7 = 53_49_221  # Indian number system grouping
int8 = 1_2_3_4_5  # VALID but discouraged
```

--------------------------------

### DecodeFile function implementation

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

The implementation of the DecodeFile function which reads and decodes a file from the OS filesystem.

```go
func DecodeFile(path string, v any) (MetaData, error) {
	fp, err := os.Open(path)
	if err != nil {
		return MetaData{}, err
	}
	defer fp.Close()
	return NewDecoder(fp).Decode(v)
}
```

--------------------------------

### func (md *MetaData) Type(key ...string) string

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/metadata.md

Returns a string representation of the TOML type of the key specified.

```APIDOC
## func (md *MetaData) Type(key ...string) string

### Description
Returns a string representation of the TOML type of the key specified.

### Parameters
- **key** (...string) - Required - Hierarchical key parts. Keys are case sensitive.

### Returns
- **string** - One of "Integer", "Float", "Datetime", "String", "Bool", "Array", "Hash", "ArrayHash"; the empty string if given an empty key or a key that does not exist.
```

--------------------------------

### Define inline tables

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Compact syntax for defining tables on a single line using curly braces.

```toml
name = { first = "Tom", last = "Preston-Werner" }
point = { x = 1, y = 2 }
animal = { type.name = "pug" }
```

--------------------------------

### Error handling for non-string map keys

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/encode.md

Demonstrates the error returned when attempting to encode a map with non-string keys.

```go
var bad map[time.Time]int
bad[time.Now()] = 1
err := toml.NewEncoder(buff).Encode(bad)
// err: "toml: cannot encode a map with non-string key type"
```

--------------------------------

### Quote key component

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/metadata.md

Renders a specific component of the key, applying quotes only if the component is not bare-key safe.

```go
func (k Key) maybeQuoted(i int) string {
	if k[i] == "" {
		return `""`
	}
	for _, r := range k[i] {
		if (r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '_' || r == '-' {
			continue
		}
		return `"` + dblQuotedReplacer.Replace(k[i]) + `"`
	}
	return k[i]
}
```

--------------------------------

### IsDefined method usage

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/metadata.md

Checks if a specific key exists in the decoded TOML data. Returns false for empty keys.

```go
func (md *MetaData) IsDefined(key ...string) bool {
	if len(key) == 0 {
		return false
	}
	...
```

```go
md, err := toml.Decode(`[fruit]
apple = 1`, &conf)
if md.IsDefined("fruit", "apple") {
	// ...
}
if !md.IsDefined("") {
	// empty key: always false
}
```

--------------------------------

### Type method usage

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/metadata.md

Retrieves the TOML type of a key as a string. Returns an empty string if the key does not exist.

```go
func (md *MetaData) Type(key ...string) string {
	if ki, ok := md.keyInfo[Key(key).String()]; ok {
		return ki.tomlType.typeString()
	}
	return ""
}
```

```go
md, _ := toml.Decode(`Pi = 3.14`, &conf)
fmt.Printf("%s\n", md.Type("Pi")) // "Float"
```

--------------------------------

### Implement encoding.TextUnmarshaler

Source: https://github.com/burntsushi/toml/blob/master/README.md

Use custom unmarshaling logic by implementing the UnmarshalText interface.

```toml
contacts = [
    "Donald Duck <donald@duckburg.com>",
    "Scrooge McDuck <scrooge@duckburg.com>",
]
```

```go
// Create address type which satisfies the encoding.TextUnmarshaler interface.
type address struct {
	*mail.Address
}

func (a *address) UnmarshalText(text []byte) error {
	var err error
	a.Address, err = mail.ParseAddress(string(text))
	return err
}

// Decode it.
func decode() {
	blob := `
		contacts = [
			"Donald Duck <donald@duckburg.com>",
			"Scrooge McDuck <scrooge@duckburg.com>",
		]
	`

	var contacts struct {
		Contacts []address
	}

	_, err := toml.Decode(blob, &contacts)
	if err != nil {
		log.Fatal(err)
	}

	for _, c := range contacts.Contacts {
		fmt.Printf("%#v\n", c.Address)
	}

	// Output:
	// &mail.Address{Name:"Donald Duck", Address:"donald@duckburg.com"}
	// &mail.Address{Name:"Scrooge McDuck", Address:"scrooge@duckburg.com"}
}
```

--------------------------------

### DecodeFS function implementation

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

The implementation of the DecodeFS function which decodes a file from an arbitrary fs.FS filesystem.

```go
func DecodeFS(fsys fs.FS, path string, v any) (MetaData, error) {
	fp, err := fsys.Open(path)
	if err != nil {
		return MetaData{}, err
	}
	defer fp.Close()
	return NewDecoder(fp).Decode(v)
}
```

--------------------------------

### Decoder Struct

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/types.md

Configures the TOML input reader and parsing depth.

```go
type Decoder struct {
	r        io.Reader
	maxDepth int
}
```

--------------------------------

### Equivalence of bare and quoted keys

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Bare and quoted keys are treated as equivalent, so they cannot be redefined.

```toml
# THIS WILL NOT WORK
spelling = "favorite"
"spelling" = "favourite"
```

--------------------------------

### ParseError.Error method

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/parse-error.md

Returns a standard one-line error message string.

```go
func (pe ParseError) Error() string {
	if pe.LastKey == "" {
		return fmt.Sprintf("toml: line %d: %s", pe.Position.Line, pe.Message)
	}
	return fmt.Sprintf("toml: line %d (last key %q): %s", pe.Position.Line, pe.LastKey, pe.Message)
}
```

--------------------------------

### Define arrays of tables

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Using double brackets to define an array of tables and populate elements.

```toml
[[products]]
name = "Hammer"
sku = 738594937

[[products]]  # empty table within the array

[[products]]
name = "Nail"
sku = 284758393

color = "gray"
```

--------------------------------

### NewDecoder function

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

Creates a new Decoder instance with a default maximum nesting depth of 128.

```go
func NewDecoder(r io.Reader) *Decoder {
	return &Decoder{r: r, maxDepth: 128}
}
```

```go
dec := toml.NewDecoder(strings.NewReader(`x = 1`))
md, err := dec.Decode(&conf)
```

--------------------------------

### Define Key type

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/metadata.md

The Key type represents a TOML key as a slice of strings, where each element is a component of the key.

```go
type Key []string
```

--------------------------------

### Define TOML literal strings

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Demonstrates the use of triple-quoted literal strings where whitespace and special characters are preserved.

```toml
regex2 = '''I [dw]on't need \d{2} apples'''
lines  = '''
The first newline is
trimmed in literal strings.
   All other whitespace
   is preserved.
'''
```

--------------------------------

### Define nested tables with quoted keys

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Table names follow the same rules as keys, allowing for nested structures.

```toml
[dog."tater.man"]
type.name = "pug"
```

```json
{ "dog": { "tater.man": { "type": { "name": "pug" } } } }
```

--------------------------------

### tomlv

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/cli-tools.md

The tomlv command validates TOML files and provides options to inspect key types, parse duration, or output the document as JSON.

```APIDOC
## tomlv

### Description
Validates TOML documents provided as files or via stdin. Supports flags to output key types, parse duration, or JSON representation.

### Usage
`tomlv [flags] [toml-file ...]`
`tomlv -` (read from stdin)

### Flags
- **-types** (bool) - Optional - Show the types for every key.
- **-time** (bool) - Optional - Show how long the parsing took in seconds.
- **-json** (bool) - Optional - Output the parsed document as JSON (indented 2 spaces).

### Example
`tomlv -types example.toml`
`tomlv -json config.toml`
```

--------------------------------

### Define a basic string

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Basic strings use double quotes and support standard escape sequences.

```toml
str = "I'm a string. \"You can quote me\". Name\tJos\xE9\nLocation\tSF."
```

--------------------------------

### Define integers

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Integers support optional plus or minus signs and underscores for readability.

```toml
int1 = +99
int2 = 42
int3 = 0
int4 = -17
```

```toml
int5 = 1_000
int6 = 5_349_221
int7 = 53_49_221  # Indian number system grouping
int8 = 1_2_3_4_5  # VALID but discouraged
```

--------------------------------

### Use space delimiter in Offset Date-Time

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Demonstrates replacing the T delimiter with a space for readability.

```toml
odt4 = 1979-05-27 07:32:00Z
```

--------------------------------

### Define Local Date-Time

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Local date-times omit the offset and are implementation-specific regarding instant conversion.

```toml
ldt1 = 1979-05-27T07:32:00
ldt2 = 1979-05-27T00:32:00.999999
```

--------------------------------

### Handle whitespace in table headers

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Whitespace around keys in headers is ignored, though avoiding it is best practice.

```toml
[a.b.c]            # this is best practice
[ d.e.f ]          # same as [d.e.f]
[ g .  h  . i ]    # same as [g.h.i]
[ j . "ʞ" . 'l' ]  # same as [j."ʞ".'l']
```

--------------------------------

### ParseError.ErrorWithPosition method

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/parse-error.md

Returns a detailed multi-line error message with location context.

```go
func (pe ParseError) ErrorWithPosition() string {
	if pe.input == "" { // Should never happen, but just in case.
		return pe.Error()
	}
	...
```

```text
toml: error: Key 'fruit' was already created and cannot be used as an array.

At line 4, column 2-7:

      2 | fruit = []
      3 |
      4 | [[fruit]] # Not allowed
            ^^^^^
```

--------------------------------

### Decode basic TOML data

Source: https://github.com/burntsushi/toml/blob/master/README.md

Map TOML keys to a Go struct using the toml.Decode function.

```toml
Age = 25
Cats = [ "Cauchy", "Plato" ]
Pi = 3.14
Perfection = [ 6, 28, 496, 8128 ]
DOB = 1987-07-05T05:45:00Z
```

```go
type Config struct {
	Age        int
	Cats       []string
	Pi         float64
	Perfection []int
	DOB        time.Time
}

var conf Config
_, err := toml.Decode(tomlData, &conf)
```

--------------------------------

### Represent TOML array of tables as JSON

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Shows the equivalent JSON structure for the provided TOML array of tables.

```json
{
  "product": [
    { "name": "Hammer", "sku": 738594937 },
    {},
    { "name": "Nail", "sku": 284758393, "color": "gray" }
  ]
}
```

--------------------------------

### Group Key-Value Pairs

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Organize related keys together for better readability compared to interleaved definitions.

```toml
# VALID BUT DISCOURAGED

apple.type = "fruit"
orange.type = "fruit"

apple.skin = "thin"
orange.skin = "thick"

apple.color = "red"
orange.color = "orange"
```

```toml
# RECOMMENDED

apple.type = "fruit"
apple.skin = "thin"
apple.color = "red"

orange.type = "fruit"
orange.skin = "thick"
orange.color = "orange"
```

--------------------------------

### Define TOML Key/Value Pair

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Basic key/value pair structure where whitespace around the equals sign is ignored.

```toml
key = "value"
```

--------------------------------

### Define Key/Value Pairs

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Key/value pairs are the primary building blocks of TOML. They must be on the same line and followed by a newline or EOF.

```toml
key = "value"
```

```toml
key = # INVALID
```

--------------------------------

### Unmarshal function implementation

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

The implementation of the Unmarshal function which decodes TOML bytes into a pointer.

```go
func Unmarshal(data []byte, v any) error {
	_, err := NewDecoder(bytes.NewReader(data)).Decode(v)
	return err
}
```

--------------------------------

### ParseError.Unwrap method

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/parse-error.md

Returns the underlying wrapped error value.

```go
func (pe ParseError) Unwrap() error {
	return pe.err
}
```

--------------------------------

### NewEncoder function definition

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/encode.md

Initializes a new Encoder instance that writes to the provided io.Writer with a default indentation of two spaces.

```go
func NewEncoder(w io.Writer) *Encoder {
	return &Encoder{w: bufio.NewWriter(w), Indent: "  "}
}
```

--------------------------------

### Define an array of tables in TOML

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.1.0.md

Uses double brackets to define an array and its elements in the order they are encountered.

```toml
[[product]]
name = "Hammer"
sku = 738594937

[[product]]  # empty table within the array

[[product]]
name = "Nail"
sku = 284758393

color = "gray"
```

--------------------------------

### Define Bare Keys

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Bare keys contain only ASCII letters, digits, underscores, and dashes.

```toml
key = "value"
bare_key = "value"
bare-key = "value"
1234 = "value"
```

--------------------------------

### func DecodeFile(path string, v any) (MetaData, error)

Source: https://github.com/burntsushi/toml/blob/master/_autodocs/api-reference/decode.md

Reads the contents of the file at path and decodes them with Decode.

```APIDOC
## func DecodeFile(path string, v any) (MetaData, error)

### Description
Reads the contents of the file at path and decodes them with Decode.

### Parameters
- **path** (string) - Required - Filesystem path of the TOML file.
- **v** (any) - Required - Destination pointer.

### Returns
- **(MetaData, error)** - If the file cannot be opened, returns MetaData{} and the os.Open error.
```

--------------------------------

### Basic Strings

Source: https://github.com/burntsushi/toml/blob/master/internal/toml-test/specs/v1.0.0.md

Basic strings use double quotes and support standard escape sequences.

```toml
str = "I'm a string. \"You can quote me\". Name\tJos\u00E9\nLocation\tSF."
```
Tokens:
Raw