Documentation
¶
Overview ¶
Package toml implements decoding and encoding of TOML files.
This pakcage supports TOML v1.0.0, as listed on https://toml.io
There is also support for delaying decoding with the Primitive type, and querying the set of keys in a TOML document with the MetaData type.
The sub-command github.com/BurntSushi/toml/cmd/tomlv can be used to verify whether a file is a valid TOML document. It can also be used to print the type of each key in a TOML document.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( LocalDatetime = time.FixedZone("datetime-local", localOffset) LocalDate = time.FixedZone("date-local", localOffset) LocalTime = time.FixedZone("time-local", localOffset) )
Timezones used for local datetime, date, and time.
Functions ¶
Types ¶
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decode TOML data.
TOML tables correspond to Go structs or maps (dealer's choice – they can be used interchangeably).
TOML table arrays correspond to either a slice of structs or a slice of maps.
TOML datetimes correspond to Go `time.Time` values. Local datetimes are parsed in the local timezone and have the Location set to toml.LocalDatetime. Local dates and times have the Location set to toml.LocalDate and toml.LocalTime.
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 encoding.TextUnmarshaler interface. In this case, any primitive TOML value (floats, strings, integers, booleans and datetimes) will be converted to a byte string and given to the value's UnmarshalText method. See the Unmarshaler example for a demonstration with time duration strings.
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 {
// A single indentation level. By default it is two spaces.
Indent string
// contains filtered or unexported fields
}
func NewEncoder ¶
NewEncoder returns a TOML encoder that encodes Go values to the io.Writer given. By default, a single indentation level is 2 spaces.
func (*Encoder) Encode ¶
Encode writes a TOML representation of the Go value to the underlying io.Wri ter. If the value given cannot be encoded to a valid TOML document, then a n error is returned.
The mapping between Go values and TOML values should be precisely the same as for the Decode* functions. Similarly, the TextMarshaler interface is supported by encoding the resulting bytes as strings. (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 (i.e., Go maps or structs), keys without any sub-hashes are encoded first.
If a Go map is encoded, then its keys are sorted alphabetically for deterministic output. More control over this behavior may be provided if there is demand for it.
Encoding Go values without a corresponding TOML representation---like map types with non-string keys---will cause an error to be returned. Similarly for mixed arrays/slices, arrays/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 OK and so is []map[string][]string.)
Beware: due to the use of reflection, only exported keys are encoded. Non exported keys are silently discarded.
type Key ¶
type Key []string
Key is the type of any TOML key, including key groups. Use (MetaData).Keys to get values of this type.
type MetaData ¶
type MetaData struct {
// contains filtered or unexported fields
}
MetaData allows access to meta information about TOML data that may not be inferrable via reflection. In particular, whether a key has been defined and the TOML type of a key.
func DecodeFS ¶
DecodeFS is just like Decode, except it will automatically read the contents of the file at `fpath` from a fs.FS instance.
func DecodeFile ¶
DecodeFile is just like Decode, except it will automatically read the contents of the file at `fpath` and decode it for you.
func (*MetaData) IsDefined ¶
IsDefined returns true if the key given exists in the TOML data. The key should be specified hierarchially. e.g.,
// access the TOML key 'a.b.c'
IsDefined("a", "b", "c")
IsDefined will return false if an empty key given. Keys are case sensitive.
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 ¶
ParseError is used when a file can't be parsed: for example invalid integer literals, duplicate keys, etc.
func (ParseError) Error ¶
func (pe ParseError) Error() string
type Primitive ¶
type Primitive struct {
// contains filtered or unexported fields
}
Primitive is a TOML value that hasn't been decoded into a Go value. When using the various `Decode*` functions, the type `Primitive` may be given to any value, and its decoding will be delayed.
A `Primitive` value can be decoded using the `PrimitiveDecode` function.
The underlying representation of a `Primitive` value is subject to change. Do not rely on it.
N.B. 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 run time.
type TextMarshaler ¶
type TextMarshaler encoding.TextMarshaler
DEPRECATED!
Use the identical encoding.TextMarshaler instead. It is defined here to support Go 1.1 and older.
type TextUnmarshaler ¶
type TextUnmarshaler encoding.TextUnmarshaler
DEPRECATED!
Use the identical encoding.TextUnmarshaler instead. It is defined here to support Go 1.1 and older.
type Unmarshaler ¶
type Unmarshaler interface {
UnmarshalTOML(interface{}) error
}
Unmarshaler is the interface implemented by objects that can unmarshal a TOML description of themselves.
Notes ¶
Bugs ¶
The behavior here is incorrect whenever a Go type satisfies the encoding.TextUnmarshaler interface but also corresponds to a TOML hash or array. In particular, the unmarshaler should only be applied to primitive TOML values. But at this point, it will be applied to all kinds of values and produce an incorrect error whenever those values are hashes or arrays (including arrays of tables).
Source Files