README
¶
This is a fork of toml lib, which adds the yaml.MapSlice data structure support.
TOML stands for Tom's Obvious, Minimal Language. This Go package provides a
reflection interface similar to Go's standard library json and xml packages.
Compatible with TOML version v1.0.0.
Examples
For the simplest example, consider some TOML file as just a list of keys and values:
Age = 25
Cats = [ "Cauchy", "Plato" ]
Pi = 3.14
Perfection = [ 6, 28, 496, 8128 ]
DOB = 1987-07-05T05:45:00Z
Which can be decoded with:
type Config struct {
Age int
Cats []string
Pi float64
Perfection []int
DOB time.Time
}
var conf Config
_, err := toml.Decode(tomlData, &conf)
You can also use struct tags if your struct field name doesn't map to a TOML key value directly:
some_key_NAME = "wat"
type TOML struct {
ObscureKey string `toml:"some_key_NAME"`
}
Beware that like other decoders only exported fields are considered when encoding and decoding; private fields are silently ignored.
Using the Marshaler and encoding.TextUnmarshaler interfaces
Here's an example that automatically parses values in a mail.Address:
contacts = [
"Donald Duck <donald@duckburg.com>",
"Scrooge McDuck <scrooge@duckburg.com>",
]
Can be decoded with:
// 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"}
}
To target TOML specifically you can implement UnmarshalTOML TOML interface in
a similar way.
More complex usage
See the _example/ directory for a more complex example.
Documentation
¶
Overview ¶
Package toml implements decoding and encoding of TOML files.
This package supports TOML v1.0.0, as specified at https://toml.io
The kcl-lang.io/kcl-go/pkg/3rdparty/toml/cmd/tomlv package implements a TOML validator, and can be used to verify if TOML document is valid. It can also be used to print the type of each key.
Index ¶
- func Marshal(v any) ([]byte, error)
- func PrimitiveDecode(primValue Primitive, v any) errordeprecated
- func Unmarshal(data []byte, v any) error
- type Decoder
- type Encoder
- type Key
- type Marshaler
- type MetaData
- type ParseError
- type Position
- type Primitive
- type TextMarshalerdeprecated
- type TextUnmarshalerdeprecated
- type Unmarshaler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Marshal ¶
Marshal returns a TOML representation of the Go value.
See Encoder for a description of the encoding process.
func PrimitiveDecode
deprecated
Types ¶
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder decodes TOML data.
TOML tables correspond to Go structs or maps; they can be used interchangeably, but structs offer better type safety.
TOML table arrays correspond to either a slice of structs or a slice of maps.
TOML datetimes correspond to time.Time. Local datetimes are parsed in the local timezone.
time.Duration types are treated as nanoseconds if the TOML value is an integer, or they're parsed with time.ParseDuration() if they're strings.
All other TOML types (float, string, int, bool and array) correspond to the obvious Go types.
An exception to the above rules is if a type implements the TextUnmarshaler interface, in which case any primitive TOML value (floats, strings, integers, booleans, datetimes) will be converted to a []byte and given to the value's UnmarshalText method. See the Unmarshaler example for a demonstration with email addresses.
Key mapping ¶
TOML keys can map to either keys in a Go map or field names in a Go struct. The special `toml` struct tag can be used to map TOML keys to struct fields that don't match the key name exactly (see the example). A case insensitive match to struct names will be tried if an exact match can't be found.
The mapping between TOML values and Go values is loose. That is, there may exist TOML values that cannot be placed into your representation, and there may be parts of your representation that do not correspond to TOML values. This loose mapping can be made stricter by using the IsDefined and/or Undecoded methods on the MetaData returned.
This decoder does not handle cyclic types. Decode will not terminate if a cyclic type is passed.
type Encoder ¶
type Encoder struct {
Indent string // string for a single indentation level; default is two spaces.
// contains filtered or unexported fields
}
Encoder encodes a Go to a TOML document.
The mapping between Go values and TOML values should be precisely the same as for Decode.
time.Time is encoded as a RFC 3339 string, and time.Duration as its string representation.
The Marshaler and encoding.TextMarshaler interfaces are supported to encoding the value as custom TOML.
If you want to write arbitrary binary data then you will need to use something like base64 since TOML does not have any binary types.
When encoding TOML hashes (Go maps or structs), keys without any sub-hashes are encoded first.
Go maps will be sorted alphabetically by key for deterministic output.
The toml struct tag can be used to provide the key name; if omitted the struct field name will be used. If the "omitempty" option is present the following value will be skipped:
- arrays, slices, maps, and string with len of 0
- struct with all zero values
- bool false
If omitzero is given all int and float types with a value of 0 will be skipped.
Encoding Go values without a corresponding TOML representation will return an error. Examples of this includes maps with non-string keys, slices with nil elements, embedded non-struct types, and nested slices containing maps or structs. (e.g. [][]map[string]string is not allowed but []map[string]string is okay, as is []map[string][]string).
NOTE: only exported keys are encoded due to the use of reflection. Unexported keys are silently discarded.
type Key ¶
type Key []string
Key represents any TOML key, including key groups. Use MetaData.Keys to get values of this type.
type Marshaler ¶
Marshaler is the interface implemented by types that can marshal themselves into valid TOML.
type MetaData ¶
type MetaData struct {
// contains filtered or unexported fields
}
MetaData allows access to meta information about TOML data that's not accessible otherwise.
It allows checking if a key is defined in the TOML data, whether any keys were undecoded, and the TOML type of a key.
func Decode ¶
Decode the TOML data in to the pointer v.
See Decoder for a description of the decoding process.
func DecodeFile ¶
DecodeFile reads the contents of a file and decodes it with Decode.
func (*MetaData) IsDefined ¶
IsDefined reports if the key exists in the TOML data.
The key should be specified hierarchically, for example to access the TOML key "a.b.c" you would use IsDefined("a", "b", "c"). Keys are case sensitive.
Returns false for an empty key.
func (*MetaData) Keys ¶
Keys returns a slice of every key in the TOML data, including key groups.
Each key is itself a slice, where the first element is the top of the hierarchy and the last is the most specific. The list will have the same order as the keys appeared in the TOML data.
All keys returned are non-empty.
func (*MetaData) PrimitiveDecode ¶
PrimitiveDecode is just like the other Decode* functions, except it decodes a TOML value that has already been parsed. Valid primitive values can *only* be obtained from values filled by the decoder functions, including this method. (i.e., v may contain more Primitive values.)
Meta data for primitive values is included in the meta data returned by the Decode* functions with one exception: keys returned by the Undecoded method will only reflect keys that were decoded. Namely, any keys hidden behind a Primitive will be considered undecoded. Executing this method will update the undecoded keys in the meta data. (See the example.)
func (*MetaData) Type ¶
Type returns a string representation of the type of the key specified.
Type will return the empty string if given an empty key or a key that does not exist. Keys are case sensitive.
func (*MetaData) Undecoded ¶
Undecoded returns all keys that have not been decoded in the order in which they appear in the original TOML document.
This includes keys that haven't been decoded because of a Primitive value. Once the Primitive value is decoded, the keys will be considered decoded.
Also note that decoding into an empty interface will result in no decoding, and so no keys will be considered decoded.
In this sense, the Undecoded keys correspond to keys in the TOML document that do not have a concrete type in your representation.
type ParseError ¶
type ParseError struct {
Message string // Short technical message.
Usage string // Longer message with usage guidance; may be blank.
Position Position // Position of the error
LastKey string // Last parsed key, may be blank.
// Line the error occurred.
//
// Deprecated: use [Position].
Line int
// contains filtered or unexported fields
}
ParseError is returned when there is an error parsing the TOML syntax such as invalid syntax, duplicate keys, etc.
In addition to the error message itself, you can also print detailed location information with context by using [ErrorWithPosition]:
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
^^^^^
[ErrorWithUsage] can be used to print the above with some more detailed usage guidance:
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}
It is invalid to split them over multiple lines like so:
# INVALID
table = {
key = 42,
second = 43
}
Use regular for this:
[table]
key = 42
second = 43
func (ParseError) Error ¶
func (pe ParseError) Error() string
func (ParseError) ErrorWithPosition ¶
func (pe ParseError) ErrorWithPosition() string
ErrorWithPosition returns the error with detailed location context.
See the documentation on ParseError.
func (ParseError) ErrorWithUsage ¶
func (pe ParseError) ErrorWithUsage() string
ErrorWithUsage returns the error with detailed location context and usage guidance.
See the documentation on ParseError.
type Position ¶
type Position struct {
Line int // Line number, starting at 1.
Col int // Error column, starting at 1.
Start int // Start of error, as byte offset starting at 0.
Len int // Lenght of the error in bytes.
}
Position of an error.
type Primitive ¶
type Primitive struct {
// contains filtered or unexported fields
}
Primitive is a TOML value that hasn't been decoded into a Go value.
This type can be used for any value, which will cause decoding to be delayed. You can use PrimitiveDecode to "manually" decode these values.
NOTE: The underlying representation of a `Primitive` value is subject to change. Do not rely on it.
NOTE: Primitive values are still parsed, so using them will only avoid the overhead of reflection. They can be useful when you don't know the exact type of TOML data until runtime.
type TextMarshaler
deprecated
type TextMarshaler encoding.TextMarshaler
TextMarshaler is an alias for encoding.TextMarshaler.
Deprecated: use encoding.TextMarshaler
type TextUnmarshaler
deprecated
type TextUnmarshaler encoding.TextUnmarshaler
TextUnmarshaler is an alias for encoding.TextUnmarshaler.
Deprecated: use encoding.TextUnmarshaler
type Unmarshaler ¶
Unmarshaler is the interface implemented by objects that can unmarshal a TOML description of themselves.
Source Files
Directories