func Marshal(v interface{}) ([]byte, error)
Marshal returns the TOML encoding of v. Behavior is similar to the Go json encoder, except that there is no concept of a Marshaler interface or MarshalTOML function for sub-structs, and currently only definite types can be marshaled (i.e. no `interface{}`).
The following struct annotations are supported:
toml:"Field" Overrides the field's name to output. omitempty When set, empty values and groups are not emitted. comment:"comment" Emits a # comment on the same line. This supports new lines. commented:"true" Emits the value as commented.
Note that pointers are automatically assigned the "omitempty" option, as TOML explicitly does not handle null values (saying instead the label should be dropped).
Tree structural types and corresponding marshal types:
*Tree (*)struct, (*)map[string]interface{} []*Tree (*)[](*)struct, (*)[](*)map[string]interface{} []interface{} (as interface{}) (*)[]primitive, (*)[]([]interface{}) interface{} (*)primitive
Tree primitive types and corresponding marshal types:
uint64 uint, uint8-uint64, pointers to same int64 int, int8-uint64, pointers to same float64 float32, float64, pointers to same string string, pointers to same bool bool, pointers to same time.LocalTime time.LocalTime{}, pointers to same
For additional flexibility, use the Encoder API.
▹ Example
func Unmarshal(data []byte, v interface{}) error
Unmarshal parses the TOML-encoded data and stores the result in the value pointed to by v. Behavior is similar to the Go json encoder, except that there is no concept of an Unmarshaler interface or UnmarshalTOML function for sub-structs, and currently only definite types can be unmarshaled to (i.e. no `interface{}`).
The following struct annotations are supported:
toml:"Field" Overrides the field's name to map to. default:"foo" Provides a default value.
For default values, only fields of the following types are supported:
See Marshal() documentation for types mapping table.
▹ Example
func ValueStringRepresentation(v interface{}, commented string, indent string, ord MarshalOrder, arraysOneElementPerLine bool) (string, error)
ValueStringRepresentation transforms an interface{} value into its toml string representation.
Decoder reads and decodes TOML values from an input stream.
type Decoder struct {
// contains filtered or unexported fields
}
func NewDecoder(r io.Reader) *Decoder
NewDecoder returns a new decoder that reads from r.
func (d *Decoder) Decode(v interface{}) error
Decode reads a TOML-encoded value from it's input and unmarshals it in the value pointed at by v.
See the documentation for Marshal for details.
func (d *Decoder) SetTagName(v string) *Decoder
SetTagName allows changing default tag "toml"
func (d *Decoder) Strict(strict bool) *Decoder
Strict allows changing to strict decoding. Any fields that are found in the input data and do not have a corresponding struct member cause an error.
Encoder writes TOML values to an output stream.
type Encoder struct {
// contains filtered or unexported fields
}
▹ Example (Anonymous)
func NewEncoder(w io.Writer) *Encoder
NewEncoder returns a new encoder that writes to w.
func (e *Encoder) ArraysWithOneElementPerLine(v bool) *Encoder
ArraysWithOneElementPerLine sets up the encoder to encode arrays with more than one element on multiple lines instead of one.
For example:
A = [1,2,3]
Becomes
A = [ 1, 2, 3, ]
func (e *Encoder) CompactComments(cc bool) *Encoder
CompactComments removes the new line before each comment in the tree.
func (e *Encoder) Encode(v interface{}) error
Encode writes the TOML encoding of v to the stream.
See the documentation for Marshal for details.
func (e *Encoder) Indentation(indent string) *Encoder
Indentation allows to change indentation when marshalling.
func (e *Encoder) Order(ord MarshalOrder) *Encoder
Order allows to change in which order fields will be written to the output stream.
func (e *Encoder) PromoteAnonymous(promote bool) *Encoder
PromoteAnonymous allows to change how anonymous struct fields are marshaled. Usually, they are marshaled as if the inner exported fields were fields in the outer struct. However, if an anonymous struct field is given a name in its TOML tag, it is treated like a regular struct field with that name. rather than being anonymous.
In case anonymous promotion is enabled, all anonymous structs are promoted and treated like regular struct fields.
func (e *Encoder) QuoteMapKeys(v bool) *Encoder
QuoteMapKeys sets up the encoder to encode maps with string type keys with quoted TOML keys.
This relieves the character limitations on map keys.
func (e *Encoder) SetTagComment(v string) *Encoder
SetTagComment allows changing default tag "comment"
func (e *Encoder) SetTagCommented(v string) *Encoder
SetTagCommented allows changing default tag "commented"
func (e *Encoder) SetTagMultiline(v string) *Encoder
SetTagMultiline allows changing default tag "multiline"
func (e *Encoder) SetTagName(v string) *Encoder
SetTagName allows changing default tag "toml"
A LocalDate represents a date (year, month, day).
This type does not include location information, and therefore does not describe a unique 24-hour timespan.
type LocalDate struct { Year int // Year (e.g., 2014). Month time.Month // Month of the year (January = 1, ...). Day int // Day of the month, starting at 1. }
func LocalDateOf(t time.Time) LocalDate
LocalDateOf returns the LocalDate in which a time occurs in that time's location.
func ParseLocalDate(s string) (LocalDate, error)
ParseLocalDate parses a string in RFC3339 full-date format and returns the date value it represents.
func (d LocalDate) AddDays(n int) LocalDate
AddDays returns the date that is n days in the future. n can also be negative to go into the past.
func (d1 LocalDate) After(d2 LocalDate) bool
After reports whether d1 occurs after d2.
func (d1 LocalDate) Before(d2 LocalDate) bool
Before reports whether d1 occurs before d2.
func (d LocalDate) DaysSince(s LocalDate) (days int)
DaysSince returns the signed number of days between the date and s, not including the end day. This is the inverse operation to AddDays.
func (d LocalDate) In(loc *time.Location) time.Time
In returns the time corresponding to time 00:00:00 of the date in the location.
In is always consistent with time.LocalDate, even when time.LocalDate returns a time on a different day. For example, if loc is America/Indiana/Vincennes, then both
time.LocalDate(1955, time.May, 1, 0, 0, 0, 0, loc)
and
civil.LocalDate{Year: 1955, Month: time.May, Day: 1}.In(loc)
return 23:00:00 on April 30, 1955.
In panics if loc is nil.
func (d LocalDate) IsValid() bool
IsValid reports whether the date is valid.
func (d LocalDate) MarshalText() ([]byte, error)
MarshalText implements the encoding.TextMarshaler interface. The output is the result of d.String().
func (d LocalDate) String() string
String returns the date in RFC3339 full-date format.
func (d *LocalDate) UnmarshalText(data []byte) error
UnmarshalText implements the encoding.TextUnmarshaler interface. The date is expected to be a string in a format accepted by ParseLocalDate.
A LocalDateTime represents a date and time.
This type does not include location information, and therefore does not describe a unique moment in time.
type LocalDateTime struct { Date LocalDate Time LocalTime }
func LocalDateTimeOf(t time.Time) LocalDateTime
LocalDateTimeOf returns the LocalDateTime in which a time occurs in that time's location.
func ParseLocalDateTime(s string) (LocalDateTime, error)
ParseLocalDateTime parses a string and returns the LocalDateTime it represents. ParseLocalDateTime accepts a variant of the RFC3339 date-time format that omits the time offset but includes an optional fractional time, as described in ParseLocalTime. Informally, the accepted format is
YYYY-MM-DDTHH:MM:SS[.FFFFFFFFF]
where the 'T' may be a lower-case 't'.
func (dt1 LocalDateTime) After(dt2 LocalDateTime) bool
After reports whether dt1 occurs after dt2.
func (dt1 LocalDateTime) Before(dt2 LocalDateTime) bool
Before reports whether dt1 occurs before dt2.
func (dt LocalDateTime) In(loc *time.Location) time.Time
In returns the time corresponding to the LocalDateTime in the given location.
If the time is missing or ambigous at the location, In returns the same result as time.LocalDate. For example, if loc is America/Indiana/Vincennes, then both
time.LocalDate(1955, time.May, 1, 0, 30, 0, 0, loc)
and
civil.LocalDateTime{ civil.LocalDate{Year: 1955, Month: time.May, Day: 1}}, civil.LocalTime{Minute: 30}}.In(loc)
return 23:30:00 on April 30, 1955.
In panics if loc is nil.
func (dt LocalDateTime) IsValid() bool
IsValid reports whether the datetime is valid.
func (dt LocalDateTime) MarshalText() ([]byte, error)
MarshalText implements the encoding.TextMarshaler interface. The output is the result of dt.String().
func (dt LocalDateTime) String() string
String returns the date in the format described in ParseLocalDate.
func (dt *LocalDateTime) UnmarshalText(data []byte) error
UnmarshalText implements the encoding.TextUnmarshaler interface. The datetime is expected to be a string in a format accepted by ParseLocalDateTime
A LocalTime represents a time with nanosecond precision.
This type does not include location information, and therefore does not describe a unique moment in time.
This type exists to represent the TIME type in storage-based APIs like BigQuery. Most operations on Times are unlikely to be meaningful. Prefer the LocalDateTime type.
type LocalTime struct { Hour int // The hour of the day in 24-hour format; range [0-23] Minute int // The minute of the hour; range [0-59] Second int // The second of the minute; range [0-59] Nanosecond int // The nanosecond of the second; range [0-999999999] }
func LocalTimeOf(t time.Time) LocalTime
LocalTimeOf returns the LocalTime representing the time of day in which a time occurs in that time's location. It ignores the date.
func ParseLocalTime(s string) (LocalTime, error)
ParseLocalTime parses a string and returns the time value it represents. ParseLocalTime accepts an extended form of the RFC3339 partial-time format. After the HH:MM:SS part of the string, an optional fractional part may appear, consisting of a decimal point followed by one to nine decimal digits. (RFC3339 admits only one digit after the decimal point).
func (t LocalTime) IsValid() bool
IsValid reports whether the time is valid.
func (t LocalTime) MarshalText() ([]byte, error)
MarshalText implements the encoding.TextMarshaler interface. The output is the result of t.String().
func (t LocalTime) String() string
String returns the date in the format described in ParseLocalTime. If Nanoseconds is zero, no fractional part will be generated. Otherwise, the result will end with a fractional part consisting of a decimal point and nine digits.
func (t *LocalTime) UnmarshalText(data []byte) error
UnmarshalText implements the encoding.TextUnmarshaler interface. The time is expected to be a string in a format accepted by ParseLocalTime.
type MarshalOrder int
Orders the Encoder can write the fields to the output stream.
const ( // Sort fields alphabetically. OrderAlphabetical MarshalOrder = iota + 1 // Preserve the order the fields are encountered. For example, the order of fields in // a struct. OrderPreserve )
Marshaler is the interface implemented by types that can marshal themselves into valid TOML.
type Marshaler interface { MarshalTOML() ([]byte, error) }
Position of a document element within a TOML document.
Line and Col are both 1-indexed positions for the element's line number and column number, respectively. Values of zero or less will cause Invalid(), to return true.
type Position struct { Line int // line within the document Col int // column within the line }
func (p Position) Invalid() bool
Invalid returns whether or not the position is valid (i.e. with negative or null values)
func (p Position) String() string
String representation of the position. Displays 1-indexed line and column numbers.
PubTOMLValue wrapping tomlValue in order to access all properties from outside.
type PubTOMLValue = tomlValue
func (ptv *PubTOMLValue) Comment() string
func (ptv *PubTOMLValue) Commented() bool
func (ptv *PubTOMLValue) Multiline() bool
func (ptv *PubTOMLValue) Position() Position
func (ptv *PubTOMLValue) SetComment(s string)
func (ptv *PubTOMLValue) SetCommented(c bool)
func (ptv *PubTOMLValue) SetMultiline(m bool)
func (ptv *PubTOMLValue) SetPosition(p Position)
func (ptv *PubTOMLValue) SetValue(v interface{})
func (ptv *PubTOMLValue) Value() interface{}
PubTree wrapping Tree in order to access all properties from outside.
type PubTree = Tree
func (pt *PubTree) Comment() string
func (pt *PubTree) Commented() bool
func (pt *PubTree) Inline() bool
func (pt *PubTree) SetComment(c string)
func (pt *PubTree) SetCommented(c bool)
func (pt *PubTree) SetInline(i bool)
func (pt *PubTree) SetValues(v map[string]interface{})
func (pt *PubTree) Values() map[string]interface{}
SetOptions arguments are supplied to the SetWithOptions and SetPathWithOptions functions to modify marshalling behaviour. The default values within the struct are valid default options.
type SetOptions struct { Comment string Commented bool Multiline bool Literal bool }
Tree is the result of the parsing of a TOML file.
type Tree struct {
// contains filtered or unexported fields
}
func Load(content string) (tree *Tree, err error)
Load creates a Tree from a string.
func LoadBytes(b []byte) (tree *Tree, err error)
LoadBytes creates a Tree from a []byte.
func LoadFile(path string) (tree *Tree, err error)
LoadFile creates a Tree from a file.
func LoadReader(reader io.Reader) (tree *Tree, err error)
LoadReader creates a Tree from any io.Reader.
func TreeFromMap(m map[string]interface{}) (*Tree, error)
TreeFromMap initializes a new Tree object using the given map.
func (t *Tree) Delete(key string) error
Delete removes a key from the tree. Key is a dot-separated path (e.g. a.b.c).
func (t *Tree) DeletePath(keys []string) error
DeletePath removes a key from the tree. Keys is an array of path elements (e.g. {"a","b","c"}).
func (t *Tree) Get(key string) interface{}
Get the value at key in the Tree. Key is a dot-separated path (e.g. a.b.c) without single/double quoted strings. If you need to retrieve non-bare keys, use GetPath. Returns nil if the path does not exist in the tree. If keys is of length zero, the current tree is returned.
func (t *Tree) GetArray(key string) interface{}
GetArray returns the value at key in the Tree. It returns []string, []int64, etc type if key has homogeneous lists Key is a dot-separated path (e.g. a.b.c) without single/double quoted strings. Returns nil if the path does not exist in the tree. If keys is of length zero, the current tree is returned.
func (t *Tree) GetArrayPath(keys []string) interface{}
GetArrayPath returns the element in the tree indicated by 'keys'. If keys is of length zero, the current tree is returned.
func (t *Tree) GetDefault(key string, def interface{}) interface{}
GetDefault works like Get but with a default value
func (t *Tree) GetPath(keys []string) interface{}
GetPath returns the element in the tree indicated by 'keys'. If keys is of length zero, the current tree is returned.
func (t *Tree) GetPosition(key string) Position
GetPosition returns the position of the given key.
func (t *Tree) GetPositionPath(keys []string) Position
GetPositionPath returns the element in the tree indicated by 'keys'. If keys is of length zero, the current tree is returned.
func (t *Tree) Has(key string) bool
Has returns a boolean indicating if the given key exists.
func (t *Tree) HasPath(keys []string) bool
HasPath returns true if the given path of keys exists, false otherwise.
func (t *Tree) Keys() []string
Keys returns the keys of the toplevel tree (does not recurse).
func (t *Tree) Marshal() ([]byte, error)
Marshal returns the TOML encoding of Tree. See Marshal() documentation for types mapping table.
func (t *Tree) Position() Position
Position returns the position of the tree.
func (t *Tree) Set(key string, value interface{})
Set an element in the tree. Key is a dot-separated path (e.g. a.b.c). Creates all necessary intermediate trees, if needed.
func (t *Tree) SetPath(keys []string, value interface{})
SetPath sets an element in the tree. Keys is an array of path elements (e.g. {"a","b","c"}). Creates all necessary intermediate trees, if needed.
func (t *Tree) SetPathWithComment(keys []string, comment string, commented bool, value interface{})
SetPathWithComment is the same as SetPath, but allows you to provide comment information to the key, that will be reused by Marshal().
func (t *Tree) SetPathWithOptions(keys []string, opts SetOptions, value interface{})
SetPathWithOptions is the same as SetPath, but allows you to provide formatting instructions to the key, that will be reused by Marshal().
func (t *Tree) SetPositionPath(keys []string, pos Position)
SetPositionPath sets the position of element in the tree indicated by 'keys'. If keys is of length zero, the current tree position is set.
func (t *Tree) SetWithComment(key string, comment string, commented bool, value interface{})
SetWithComment is the same as Set, but allows you to provide comment information to the key, that will be reused by Marshal().
func (t *Tree) SetWithOptions(key string, opts SetOptions, value interface{})
SetWithOptions is the same as Set, but allows you to provide formatting instructions to the key, that will be used by Marshal().
func (t *Tree) String() string
String generates a human-readable representation of the current tree. Alias of ToString. Present to implement the fmt.Stringer interface.
func (t *Tree) ToMap() map[string]interface{}
ToMap recursively generates a representation of the tree using Go built-in structures. The following types are used:
func (t *Tree) ToTomlString() (string, error)
ToTomlString generates a human-readable representation of the current tree. Output spans multiple lines, and is suitable for ingest by a TOML parser. If the conversion cannot be performed, ToString returns a non-nil error.
func (t *Tree) Unmarshal(v interface{}) error
Unmarshal attempts to unmarshal the Tree into a Go struct pointed by v. Neither Unmarshaler interfaces nor UnmarshalTOML functions are supported for sub-structs, and only definite types can be unmarshaled.
func (t *Tree) WriteTo(w io.Writer) (int64, error)
WriteTo encode the Tree as Toml and writes it to the writer w. Returns the number of bytes written in case of success, or an error if anything happened.
Unmarshaler is the interface implemented by types that can unmarshal a TOML description of themselves.
type Unmarshaler interface { UnmarshalTOML(interface{}) error }
Name | Synopsis |
---|---|
.. | |
cmd | |
jsontoml | Jsontoml reads JSON and converts to TOML. |
tomljson | Tomljson reads TOML and converts to JSON. |
tomll | Tomll is a linter for TOML |
tomltestgen | Tomltestgen is a program that retrieves a given version of https://github.com/BurntSushi/toml-test and generates go code for go-toml's unit tests based on the test files. |
query | Package query performs JSONPath-like queries on a TOML document. |
v2 | Package toml is a library to read and write TOML documents. |
cmd | |
gotoml-test-decoder | |
gotoml-test-encoder | |
jsontoml | Package jsontoml is a program that converts JSON to TOML. |
tomljson | Package tomljson is a program that converts TOML to JSON. |
tomll | 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. |
ossfuzz | |
unstable | Package unstable provides APIs that do not meet the backward compatibility guarantees yet. |