Documentation
¶
Overview ¶
Package toml is a TOML parser and manipulation library.
This version supports the specification as described in https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md
Marshaling ¶
Go-toml can marshal and unmarshal TOML documents from and to data structures.
TOML document as a tree ¶
Go-toml can operate on a TOML document as a tree. Use one of the Load* functions to parse TOML data and obtain a Tree instance, then one of its methods to manipulate the tree.
JSONPath-like queries ¶
The package github.com/meverselabs/meverse/cmd/config/go-toml/query implements a system similar to JSONPath to quickly retrieve elements of a TOML document using a single expression. See the package documentation for more information.
Example (Tree) ¶
package main import ( "fmt" toml "github.com/meverselabs/meverse/cmd/config/go-toml" ) func main() { config, err := toml.LoadFile("config.toml") if err != nil { fmt.Println("Error ", err.Error()) } else { // retrieve data directly user := config.Get("postgres.user").(string) password := config.Get("postgres.password").(string) // or using an intermediate object configTree := config.Get("postgres").(*toml.Tree) user = configTree.Get("user").(string) password = configTree.Get("password").(string) fmt.Println("User is", user, " and password is", password) // show where elements are in the file fmt.Printf("User position: %v\n", configTree.GetPosition("user")) fmt.Printf("Password position: %v\n", configTree.GetPosition("password")) } }
Output:
Example (Unmarshal) ¶
package main import ( "fmt" toml "github.com/meverselabs/meverse/cmd/config/go-toml" ) func main() { type Employer struct { Name string Phone string } type Person struct { Name string Age int64 Employer Employer } document := []byte(` name = "John" age = 30 [employer] name = "Company Inc." phone = "+1 234 567 89012" `) person := Person{} toml.Unmarshal(document, &person) fmt.Println(person.Name, "is", person.Age, "and works at", person.Employer.Name) }
Output: John is 30 and works at Company Inc.
Index ¶
- func Marshal(v interface{}) ([]byte, error)
- func Unmarshal(data []byte, v interface{}) error
- type Decoder
- type Encoder
- type Marshaler
- type Position
- type SetOptions
- type Tree
- func (t *Tree) Get(key string) interface{}
- func (t *Tree) GetDefault(key string, def interface{}) interface{}
- func (t *Tree) GetPath(keys []string) interface{}
- func (t *Tree) GetPosition(key string) Position
- func (t *Tree) GetPositionPath(keys []string) Position
- func (t *Tree) Has(key string) bool
- func (t *Tree) HasPath(keys []string) bool
- func (t *Tree) Keys() []string
- func (t *Tree) Marshal() ([]byte, error)
- func (t *Tree) Position() Position
- func (t *Tree) Set(key string, value interface{})
- func (t *Tree) SetPath(keys []string, value interface{})
- func (t *Tree) SetPathWithComment(keys []string, comment string, commented bool, value interface{})
- func (t *Tree) SetPathWithOptions(keys []string, opts SetOptions, value interface{})
- func (t *Tree) SetWithComment(key string, comment string, commented bool, value interface{})
- func (t *Tree) SetWithOptions(key string, opts SetOptions, value interface{})
- func (t *Tree) String() string
- func (t *Tree) ToMap() map[string]interface{}
- func (t *Tree) ToTomlString() (string, error)
- func (t *Tree) Unmarshal(v interface{}) error
- func (t *Tree) WriteTo(w io.Writer) (int64, error)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Marshal ¶
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.Time time.Time{}, pointers to same
Example ¶
package main import ( "fmt" "log" toml "github.com/meverselabs/meverse/cmd/config/go-toml" ) func main() { type Postgres struct { User string `toml:"user"` Password string `toml:"password"` Database string `toml:"db" commented:"true" comment:"not used anymore"` } type Config struct { Postgres Postgres `toml:"postgres" comment:"Postgres configuration"` } config := Config{Postgres{User: "pelletier", Password: "mypassword", Database: "old_database"}} b, err := toml.Marshal(config) if err != nil { log.Fatal(err) } fmt.Println(string(b)) }
Output: # Postgres configuration [postgres] # not used anymore # db = "old_database" password = "mypassword" user = "pelletier"
func Unmarshal ¶
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.
See Marshal() documentation for types mapping table.
Example ¶
package main import ( "fmt" toml "github.com/meverselabs/meverse/cmd/config/go-toml" ) func main() { type Postgres struct { User string Password string } type Config struct { Postgres Postgres } doc := []byte(` [postgres] user = "pelletier" password = "mypassword"`) config := Config{} toml.Unmarshal(doc, &config) fmt.Println("user=", config.Postgres.User) }
Output: user= pelletier
Types ¶
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder reads and decodes TOML values from an input stream.
func NewDecoder ¶
NewDecoder returns a new decoder that reads from r.
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder writes TOML values to an output stream.
func NewEncoder ¶
NewEncoder returns a new encoder that writes to w.
func (*Encoder) ArraysWithOneElementPerLine ¶
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 (*Encoder) Encode ¶
Encode writes the TOML encoding of v to the stream.
See the documentation for Marshal for details.
func (*Encoder) QuoteMapKeys ¶
QuoteMapKeys sets up the encoder to encode maps with string type keys with quoted TOML keys.
This relieves the character limitations on map keys.
type Marshaler ¶
Marshaler is the interface implemented by types that can marshal themselves into valid TOML.
type Position ¶
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 SetOptions ¶
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 Tree ¶
type Tree struct {
// contains filtered or unexported fields
}
Tree is the result of the parsing of a TOML file.
func LoadReader ¶
LoadReader creates a Tree from any io.Reader.
func TreeFromMap ¶
TreeFromMap initializes a new Tree object using the given map.
func (*Tree) Get ¶
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 (*Tree) GetDefault ¶
GetDefault works like Get but with a default value
func (*Tree) GetPath ¶
GetPath returns the element in the tree indicated by 'keys'. If keys is of length zero, the current tree is returned.
func (*Tree) GetPosition ¶
GetPosition returns the position of the given key.
func (*Tree) GetPositionPath ¶
GetPositionPath returns the element in the tree indicated by 'keys'. If keys is of length zero, the current tree is returned.
func (*Tree) Marshal ¶
Marshal returns the TOML encoding of Tree. See Marshal() documentation for types mapping table.
func (*Tree) Set ¶
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 (*Tree) SetPath ¶
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 (*Tree) SetPathWithComment ¶
SetPathWithComment is the same as SetPath, but allows you to provide comment information to the key, that will be reused by Marshal().
func (*Tree) SetPathWithOptions ¶
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 (*Tree) SetWithComment ¶
SetWithComment is the same as Set, but allows you to provide comment information to the key, that will be reused by Marshal().
func (*Tree) SetWithOptions ¶
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 (*Tree) String ¶
String generates a human-readable representation of the current tree. Alias of ToString. Present to implement the fmt.Stringer interface.
func (*Tree) ToMap ¶
ToMap recursively generates a representation of the tree using Go built-in structures. The following types are used:
- bool
- float64
- int64
- string
- uint64
- time.Time
- map[string]interface{} (where interface{} is any of this list)
- []interface{} (where interface{} is any of this list)
func (*Tree) ToTomlString ¶
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.
Source Files
¶
Directories
¶
Path | Synopsis |
---|---|
tomljson
Tomljson reads TOML and converts to JSON.
|
Tomljson reads TOML and converts to JSON. |
tomll
Tomll is a linter for TOML
|
Tomll is a linter for TOML |
Package query performs JSONPath-like queries on a TOML document.
|
Package query performs JSONPath-like queries on a TOML document. |