README
¶
toml
Fork of https://github.com/pelletier/go-toml/v2 that I wish I didn't need.
License
The MIT License (MIT). Read LICENSE.
Documentation
¶
Overview ¶
Package toml is a library to read and write TOML documents.
Index ¶
- func Marshal(v interface{}) ([]byte, error)
- func Unmarshal(data []byte, v interface{}) error
- type DecodeError
- type Decoder
- type Encoder
- func (enc *Encoder) Encode(v interface{}) error
- func (enc *Encoder) SetArraysMultiline(multiline bool) *Encoder
- func (enc *Encoder) SetIndentSymbol(s string) *Encoder
- func (enc *Encoder) SetIndentTables(indent bool) *Encoder
- func (enc *Encoder) SetMarshalJsonNumbers(indent bool) *Encoder
- func (enc *Encoder) SetTablesInline(inline bool) *Encoder
- type Key
- type LocalDate
- type LocalDateTime
- type LocalTime
- type StrictMissingError
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Marshal ¶
Marshal serializes a Go value as a TOML document.
It is a shortcut for Encoder.Encode() with the default options.
Example ¶
package main
import (
"fmt"
"git.sr.ht/~ixoh/toml"
)
func main() {
type MyConfig struct {
Version int
Name string
Tags []string
}
cfg := MyConfig{
Version: 2,
Name: "go-toml",
Tags: []string{"go", "toml"},
}
b, err := toml.Marshal(cfg)
if err != nil {
panic(err)
}
fmt.Println(string(b))
}
Output: Version = 2 Name = 'go-toml' Tags = ['go', 'toml']
Example (Commented) ¶
Example that uses the 'commented' field tag option to generate an example configuration file that has commented out sections (example from go-graphite/graphite-clickhouse).
package main
import (
"fmt"
"time"
"git.sr.ht/~ixoh/toml"
)
func main() {
type Common struct {
Listen string `toml:"listen" comment:"general listener"`
PprofListen string `toml:"pprof-listen" comment:"listener to serve /debug/pprof requests. '-pprof' argument overrides it"`
MaxMetricsPerTarget int `toml:"max-metrics-per-target" comment:"limit numbers of queried metrics per target in /render requests, 0 or negative = unlimited"`
MemoryReturnInterval time.Duration `toml:"memory-return-interval" comment:"daemon will return the freed memory to the OS when it>0"`
}
type Costs struct {
Cost *int `toml:"cost" comment:"default cost (for wildcarded equalence or matched with regex, or if no value cost set)"`
ValuesCost map[string]int `toml:"values-cost" comment:"cost with some value (for equalence without wildcards) (additional tuning, usually not needed)"`
}
type ClickHouse struct {
URL string `toml:"url" comment:"default url, see https://clickhouse.tech/docs/en/interfaces/http. Can be overwritten with query-params"`
RenderMaxQueries int `toml:"render-max-queries" comment:"Max queries to render queiries"`
RenderConcurrentQueries int `toml:"render-concurrent-queries" comment:"Concurrent queries to render queiries"`
TaggedCosts map[string]*Costs `toml:"tagged-costs,commented"`
TreeTable string `toml:"tree-table,commented"`
ReverseTreeTable string `toml:"reverse-tree-table,commented"`
DateTreeTable string `toml:"date-tree-table,commented"`
DateTreeTableVersion int `toml:"date-tree-table-version,commented"`
TreeTimeout time.Duration `toml:"tree-timeout,commented"`
TagTable string `toml:"tag-table,commented"`
ExtraPrefix string `toml:"extra-prefix" comment:"add extra prefix (directory in graphite) for all metrics, w/o trailing dot"`
ConnectTimeout time.Duration `toml:"connect-timeout" comment:"TCP connection timeout"`
DataTableLegacy string `toml:"data-table,commented"`
RollupConfLegacy string `toml:"rollup-conf,commented"`
MaxDataPoints int `toml:"max-data-points" comment:"max points per metric when internal-aggregation=true"`
InternalAggregation bool `toml:"internal-aggregation" comment:"ClickHouse-side aggregation, see doc/aggregation.md"`
}
type Tags struct {
Rules string `toml:"rules"`
Date string `toml:"date"`
ExtraWhere string `toml:"extra-where"`
InputFile string `toml:"input-file"`
OutputFile string `toml:"output-file"`
}
type Config struct {
Common Common `toml:"common"`
ClickHouse ClickHouse `toml:"clickhouse"`
Tags Tags `toml:"tags,commented"`
}
cfg := &Config{
Common: Common{
Listen: ":9090",
PprofListen: "",
MaxMetricsPerTarget: 15000, // This is arbitrary value to protect CH from overload
MemoryReturnInterval: 0,
},
ClickHouse: ClickHouse{
URL: "http://localhost:8123?cancel_http_readonly_queries_on_client_close=1",
ExtraPrefix: "",
ConnectTimeout: time.Second,
DataTableLegacy: "",
RollupConfLegacy: "auto",
MaxDataPoints: 1048576,
InternalAggregation: true,
},
Tags: Tags{},
}
out, err := toml.Marshal(cfg)
if err != nil {
panic(err)
}
err = toml.Unmarshal(out, &cfg)
if err != nil {
panic(err)
}
fmt.Println(string(out))
}
Output: [common] # general listener listen = ':9090' # listener to serve /debug/pprof requests. '-pprof' argument overrides it pprof-listen = '' # limit numbers of queried metrics per target in /render requests, 0 or negative = unlimited max-metrics-per-target = 15000 # daemon will return the freed memory to the OS when it>0 memory-return-interval = 0 [clickhouse] # default url, see https://clickhouse.tech/docs/en/interfaces/http. Can be overwritten with query-params url = 'http://localhost:8123?cancel_http_readonly_queries_on_client_close=1' # Max queries to render queiries render-max-queries = 0 # Concurrent queries to render queiries render-concurrent-queries = 0 # tree-table = '' # reverse-tree-table = '' # date-tree-table = '' # date-tree-table-version = 0 # tree-timeout = 0 # tag-table = '' # add extra prefix (directory in graphite) for all metrics, w/o trailing dot extra-prefix = '' # TCP connection timeout connect-timeout = 1000000000 # data-table = '' # rollup-conf = 'auto' # max points per metric when internal-aggregation=true max-data-points = 1048576 # ClickHouse-side aggregation, see doc/aggregation.md internal-aggregation = true # [tags] # rules = '' # date = '' # extra-where = '' # input-file = '' # output-file = ''
func Unmarshal ¶
Unmarshal deserializes a TOML document into a Go value.
It is a shortcut for Decoder.Decode() with the default options.
Example ¶
package main
import (
"fmt"
"git.sr.ht/~ixoh/toml"
)
func main() {
type MyConfig struct {
Version int
Name string
Tags []string
}
doc := `
version = 2
name = "go-toml"
tags = ["go", "toml"]
`
var cfg MyConfig
err := toml.Unmarshal([]byte(doc), &cfg)
if err != nil {
panic(err)
}
fmt.Println("version:", cfg.Version)
fmt.Println("name:", cfg.Name)
fmt.Println("tags:", cfg.Tags)
}
Output: version: 2 name: go-toml tags: [go toml]
Example (TextUnmarshal) ¶
package main
import (
"fmt"
"log"
"strconv"
"git.sr.ht/~ixoh/toml"
)
type customInt int
func (i *customInt) UnmarshalText(b []byte) error {
x, err := strconv.ParseInt(string(b), 10, 32)
if err != nil {
return err
}
*i = customInt(x * 100)
return nil
}
type doc struct {
Value customInt
}
func main() {
var x doc
data := []byte(`value = "42"`)
err := toml.Unmarshal(data, &x)
if err != nil {
log.Fatal(err)
}
fmt.Println(x)
}
Output: {4200}
Types ¶
type DecodeError ¶
type DecodeError struct {
// contains filtered or unexported fields
}
DecodeError represents an error encountered during the parsing or decoding of a TOML document.
In addition to the error message, it contains the position in the document where it happened, as well as a human-readable representation that shows where the error occurred in the document.
Example ¶
doc := `name = 123__456`
s := map[string]interface{}{}
err := Unmarshal([]byte(doc), &s)
fmt.Println(err)
var derr *DecodeError
if errors.As(err, &derr) {
fmt.Println(derr.String())
row, col := derr.Position()
fmt.Println("error occurred at row", row, "column", col)
}
Output: toml: number must have at least one digit between underscores 1| name = 123__456 | ~~ number must have at least one digit between underscores error occurred at row 1 column 11
func (*DecodeError) Error ¶
func (e *DecodeError) Error() string
Error returns the error message contained in the DecodeError.
func (*DecodeError) Key ¶
func (e *DecodeError) Key() Key
Key that was being processed when the error occurred. The key is present only if this DecodeError is part of a StrictMissingError.
func (*DecodeError) Position ¶
func (e *DecodeError) Position() (row int, column int)
Position returns the (line, column) pair indicating where the error occurred in the document. Positions are 1-indexed.
func (*DecodeError) String ¶
func (e *DecodeError) String() string
String returns the human-readable contextualized error. This string is multi-line.
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder reads and decode a TOML document from an input stream.
func NewDecoder ¶
NewDecoder creates a new Decoder that will read from r.
func (*Decoder) Decode ¶
Decode the whole content of r into v.
By default, values in the document that don't exist in the target Go value are ignored. See Decoder.DisallowUnknownFields() to change this behavior.
When a TOML local date, time, or date-time is decoded into a time.Time, its value is represented in time.Local timezone. Otherwise the appropriate Local* structure is used. For time values, precision up to the nanosecond is supported by truncating extra digits.
Empty tables decoded in an interface{} create an empty initialized map[string]interface{}.
Types implementing the encoding.TextUnmarshaler interface are decoded from a TOML string.
When decoding a number, go-toml will return an error if the number is out of bounds for the target type (which includes negative numbers when decoding into an unsigned int).
If an error occurs while decoding the content of the document, this function returns a toml.DecodeError, providing context about the issue. When using strict mode and a field is missing, a `toml.StrictMissingError` is returned. In any other case, this function returns a standard Go error.
Type mapping ¶
List of supported TOML types and their associated accepted Go types:
String -> string Integer -> uint*, int*, depending on size Float -> float*, depending on size Boolean -> bool Offset Date-Time -> time.Time Local Date-time -> LocalDateTime, time.Time Local Date -> LocalDate, time.Time Local Time -> LocalTime, time.Time Array -> slice and array, depending on elements types Table -> map and struct Inline Table -> same as Table Array of Tables -> same as Array and Table
func (*Decoder) DisallowUnknownFields ¶
DisallowUnknownFields causes the Decoder to return an error when the destination is a struct and the input contains a key that does not match a non-ignored field.
In that case, the Decoder returns a StrictMissingError that can be used to retrieve the individual errors as well as generate a human readable description of the missing fields.
Example ¶
package main
import (
"errors"
"fmt"
"strings"
"git.sr.ht/~ixoh/toml"
)
func main() {
type S struct {
Key1 string
Key3 string
}
doc := `
key1 = "value1"
key2 = "value2"
key3 = "value3"
`
r := strings.NewReader(doc)
d := toml.NewDecoder(r)
d.DisallowUnknownFields()
s := S{}
err := d.Decode(&s)
fmt.Println(err.Error())
var details *toml.StrictMissingError
if !errors.As(err, &details) {
panic(fmt.Sprintf("err should have been a *toml.StrictMissingError, but got %s (%T)", err, err))
}
fmt.Println(details.String())
}
Output: strict mode: fields in the document are missing in the target struct 2| key1 = "value1" 3| key2 = "value2" | ~~~~ missing field 4| key3 = "value3"
func (*Decoder) EnableUnmarshalerInterface ¶
EnableUnmarshalerInterface allows to enable unmarshaler interface.
With this feature enabled, types implementing the unstable/Unmarshaler interface can be decoded from any structure of the document. It allows types that don't have a straightfoward TOML representation to provide their own decoding logic.
Currently, types can only decode from a single value. Tables and array tables are not supported.
*Unstable:* This method does not follow the compatibility guarantees of semver. It can be changed or removed without a new major version being issued.
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder writes a TOML document to an output stream.
func NewEncoder ¶
NewEncoder returns a new Encoder that writes to w.
func (*Encoder) Encode ¶
Encode writes a TOML representation of v to the stream.
If v cannot be represented to TOML it returns an error.
Encoding rules ¶
A top level slice containing only maps or structs is encoded as [[table array]].
All slices not matching rule 1 are encoded as [array]. As a result, any map or struct they contain is encoded as an {inline table}.
Nil interfaces and nil pointers are not supported.
Keys in key-values always have one part.
Intermediate tables are always printed.
By default, strings are encoded as literal string, unless they contain either a newline character or a single quote. In that case they are emitted as quoted strings.
Unsigned integers larger than math.MaxInt64 cannot be encoded. Doing so results in an error. This rule exists because the TOML specification only requires parsers to support at least the 64 bits integer range. Allowing larger numbers would create non-standard TOML documents, which may not be readable (at best) by other implementations. To encode such numbers, a solution is a custom type that implements encoding.TextMarshaler.
When encoding structs, fields are encoded in order of definition, with their exact name.
Tables and array tables are separated by empty lines. However, consecutive subtables definitions are not. For example:
[top1] [top2] [top2.child1] [[array]] [[array]] [array.child2]
Struct tags ¶
The encoding of each public struct field can be customized by the format string in the "toml" key of the struct field's tag. This follows encoding/json's convention. The format string starts with the name of the field, optionally followed by a comma-separated list of options. The name may be empty in order to provide options without overriding the default name.
The "multiline" option emits strings as quoted multi-line TOML strings. It has no effect on fields that would not be encoded as strings.
The "inline" option turns fields that would be emitted as tables into inline tables instead. It has no effect on other fields.
The "omitempty" option prevents empty values or groups from being emitted.
The "commented" option prefixes the value and all its children with a comment symbol.
In addition to the "toml" tag struct tag, a "comment" tag can be used to emit a TOML comment before the value being annotated. Comments are ignored inside inline tables. For array tables, the comment is only present before the first element of the array.
func (*Encoder) SetArraysMultiline ¶
SetArraysMultiline forces the encoder to emit all arrays with one element per line.
This behavior can be controlled on an individual struct field basis with the multiline tag:
MyField `multiline:"true"`
func (*Encoder) SetIndentSymbol ¶
SetIndentSymbol defines the string that should be used for indentation. The provided string is repeated for each indentation level. Defaults to two spaces.
func (*Encoder) SetIndentTables ¶
SetIndentTables forces the encoder to intent tables and array tables.
func (*Encoder) SetMarshalJsonNumbers ¶
SetMarshalJsonNumbers forces the encoder to serialize `json.Number` as a float or integer instead of relying on TextMarshaler to emit a string.
*Unstable:* This method does not follow the compatibility guarantees of semver. It can be changed or removed without a new major version being issued.
func (*Encoder) SetTablesInline ¶
SetTablesInline forces the encoder to emit all tables inline.
This behavior can be controlled on an individual struct field basis with the inline tag:
MyField `toml:",inline"`
type LocalDate ¶
LocalDate represents a calendar day in no specific timezone.
func (LocalDate) MarshalText ¶
MarshalText returns RFC 3339 representation of d.
type LocalDateTime ¶
LocalDateTime represents a time of a specific day in no specific timezone.
func (LocalDateTime) AsTime ¶
func (d LocalDateTime) AsTime(zone *time.Location) time.Time
AsTime converts d into a specific time instance in zone.
func (LocalDateTime) MarshalText ¶
func (d LocalDateTime) MarshalText() ([]byte, error)
MarshalText returns RFC 3339 representation of d.
func (LocalDateTime) String ¶
func (d LocalDateTime) String() string
String returns RFC 3339 representation of d.
func (*LocalDateTime) UnmarshalText ¶
func (d *LocalDateTime) UnmarshalText(data []byte) error
UnmarshalText parses b using RFC 3339 to fill d.
type LocalTime ¶
type LocalTime struct {
Hour int // Hour of the day: [0; 24[
Minute int // Minute of the hour: [0; 60[
Second int // Second of the minute: [0; 60[
Nanosecond int // Nanoseconds within the second: [0, 1000000000[
Precision int // Number of digits to display for Nanosecond.
}
LocalTime represents a time of day of no specific day in no specific timezone.
func (LocalTime) MarshalText ¶
MarshalText returns RFC 3339 representation of d.
type StrictMissingError ¶
type StrictMissingError struct {
// One error per field that could not be found.
Errors []DecodeError
}
StrictMissingError occurs in a TOML document that does not have a corresponding field in the target value. It contains all the missing fields in Errors.
Emitted by Decoder when DisallowUnknownFields() was called.
func (*StrictMissingError) Error ¶
func (s *StrictMissingError) Error() string
Error returns the canonical string for this error.
func (*StrictMissingError) String ¶
func (s *StrictMissingError) String() string
String returns a human readable description of all errors.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
jsontoml
Package jsontoml is a program that converts JSON to TOML.
|
Package jsontoml is a program that converts JSON to TOML. |
|
tomljson
Package tomljson is a program that converts TOML to JSON.
|
Package tomljson is a program that converts TOML to JSON. |
|
tomll
Package tomll is a linter program for TOML.
|
Package tomll is a linter program for TOML. |
|
tomltestgen
tomltestgen retrieves a given version of the language-agnostic TOML test suite in https://github.com/BurntSushi/toml-test and generates go-toml unit tests.
|
tomltestgen retrieves a given version of the language-agnostic TOML test suite in https://github.com/BurntSushi/toml-test and generates go-toml unit tests. |
|
internal
|
|
|
testsuite
Package testsuite provides helper functions for interoperating with the language-agnostic TOML test suite at github.com/BurntSushi/toml-test.
|
Package testsuite provides helper functions for interoperating with the language-agnostic TOML test suite at github.com/BurntSushi/toml-test. |
|
Package unstable provides APIs that do not meet the backward compatibility guarantees yet.
|
Package unstable provides APIs that do not meet the backward compatibility guarantees yet. |