diff options
Diffstat (limited to 'vendor/github.com/pelletier/go-toml/doc.go')
| -rw-r--r-- | vendor/github.com/pelletier/go-toml/doc.go | 251 |
1 files changed, 12 insertions, 239 deletions
diff --git a/vendor/github.com/pelletier/go-toml/doc.go b/vendor/github.com/pelletier/go-toml/doc.go index 9156b73..3c89619 100644 --- a/vendor/github.com/pelletier/go-toml/doc.go +++ b/vendor/github.com/pelletier/go-toml/doc.go @@ -1,250 +1,23 @@ -// Package toml is a TOML markup language parser. +// 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 // -// TOML Parsing +// Marshaling // -// TOML data may be parsed in two ways: by file, or by string. +// Go-toml can marshal and unmarshal TOML documents from and to data +// structures. // -// // load TOML data by filename -// tree, err := toml.LoadFile("filename.toml") +// TOML document as a tree // -// // load TOML data stored in a string -// tree, err := toml.Load(stringContainingTomlData) +// 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. // -// Either way, the result is a TomlTree object that can be used to navigate the -// structure and data within the original document. +// JSONPath-like queries // -// -// Getting data from the TomlTree -// -// After parsing TOML data with Load() or LoadFile(), use the Has() and Get() -// methods on the returned TomlTree, to find your way through the document data. -// -// if tree.Has("foo") { -// fmt.Println("foo is:", tree.Get("foo")) -// } -// -// Working with Paths -// -// Go-toml has support for basic dot-separated key paths on the Has(), Get(), Set() -// and GetDefault() methods. These are the same kind of key paths used within the -// TOML specification for struct tames. -// -// // looks for a key named 'baz', within struct 'bar', within struct 'foo' -// tree.Has("foo.bar.baz") -// -// // returns the key at this path, if it is there -// tree.Get("foo.bar.baz") -// -// TOML allows keys to contain '.', which can cause this syntax to be problematic -// for some documents. In such cases, use the GetPath(), HasPath(), and SetPath(), -// methods to explicitly define the path. This form is also faster, since -// it avoids having to parse the passed key for '.' delimiters. -// -// // looks for a key named 'baz', within struct 'bar', within struct 'foo' -// tree.HasPath([]string{"foo","bar","baz"}) -// -// // returns the key at this path, if it is there -// tree.GetPath([]string{"foo","bar","baz"}) -// -// Note that this is distinct from the heavyweight query syntax supported by -// TomlTree.Query() and the Query() struct (see below). -// -// Position Support -// -// Each element within the TomlTree is stored with position metadata, which is -// invaluable for providing semantic feedback to a user. This helps in -// situations where the TOML file parses correctly, but contains data that is -// not correct for the application. In such cases, an error message can be -// generated that indicates the problem line and column number in the source -// TOML document. -// -// // load TOML data -// tree, _ := toml.Load("filename.toml") -// -// // get an entry and report an error if it's the wrong type -// element := tree.Get("foo") -// if value, ok := element.(int64); !ok { -// return fmt.Errorf("%v: Element 'foo' must be an integer", tree.GetPosition("foo")) -// } -// -// // report an error if an expected element is missing -// if !tree.Has("bar") { -// return fmt.Errorf("%v: Expected 'bar' element", tree.GetPosition("")) -// } -// -// Query Support -// -// The TOML query path implementation is based loosely on the JSONPath specification: -// http://goessner.net/articles/JsonPath/ -// -// The idea behind a query path is to allow quick access to any element, or set -// of elements within TOML document, with a single expression. -// -// result, err := tree.Query("$.foo.bar.baz") -// -// This is roughly equivalent to: -// -// next := tree.Get("foo") -// if next != nil { -// next = next.Get("bar") -// if next != nil { -// next = next.Get("baz") -// } -// } -// result := next -// -// err is nil if any parsing exception occurs. -// -// If no node in the tree matches the query, result will simply contain an empty list of -// items. -// -// As illustrated above, the query path is much more efficient, especially since -// the structure of the TOML file can vary. Rather than making assumptions about -// a document's structure, a query allows the programmer to make structured -// requests into the document, and get zero or more values as a result. -// -// The syntax of a query begins with a root token, followed by any number -// sub-expressions: -// -// $ -// Root of the TOML tree. This must always come first. -// .name -// Selects child of this node, where 'name' is a TOML key -// name. -// ['name'] -// Selects child of this node, where 'name' is a string -// containing a TOML key name. -// [index] -// Selcts child array element at 'index'. -// ..expr -// Recursively selects all children, filtered by an a union, -// index, or slice expression. -// ..* -// Recursive selection of all nodes at this point in the -// tree. -// .* -// Selects all children of the current node. -// [expr,expr] -// Union operator - a logical 'or' grouping of two or more -// sub-expressions: index, key name, or filter. -// [start:end:step] -// Slice operator - selects array elements from start to -// end-1, at the given step. All three arguments are -// optional. -// [?(filter)] -// Named filter expression - the function 'filter' is -// used to filter children at this node. -// -// Query Indexes And Slices -// -// Index expressions perform no bounds checking, and will contribute no -// values to the result set if the provided index or index range is invalid. -// Negative indexes represent values from the end of the array, counting backwards. -// -// // select the last index of the array named 'foo' -// tree.Query("$.foo[-1]") -// -// Slice expressions are supported, by using ':' to separate a start/end index pair. -// -// // select up to the first five elements in the array -// tree.Query("$.foo[0:5]") -// -// Slice expressions also allow negative indexes for the start and stop -// arguments. -// -// // select all array elements. -// tree.Query("$.foo[0:-1]") -// -// Slice expressions may have an optional stride/step parameter: -// -// // select every other element -// tree.Query("$.foo[0:-1:2]") -// -// Slice start and end parameters are also optional: -// -// // these are all equivalent and select all the values in the array -// tree.Query("$.foo[:]") -// tree.Query("$.foo[0:]") -// tree.Query("$.foo[:-1]") -// tree.Query("$.foo[0:-1:]") -// tree.Query("$.foo[::1]") -// tree.Query("$.foo[0::1]") -// tree.Query("$.foo[:-1:1]") -// tree.Query("$.foo[0:-1:1]") -// -// Query Filters -// -// Query filters are used within a Union [,] or single Filter [] expression. -// A filter only allows nodes that qualify through to the next expression, -// and/or into the result set. -// -// // returns children of foo that are permitted by the 'bar' filter. -// tree.Query("$.foo[?(bar)]") -// -// There are several filters provided with the library: -// -// tree -// Allows nodes of type TomlTree. -// int -// Allows nodes of type int64. -// float -// Allows nodes of type float64. -// string -// Allows nodes of type string. -// time -// Allows nodes of type time.Time. -// bool -// Allows nodes of type bool. -// -// Query Results -// -// An executed query returns a QueryResult object. This contains the nodes -// in the TOML tree that qualify the query expression. Position information -// is also available for each value in the set. -// -// // display the results of a query -// results := tree.Query("$.foo.bar.baz") -// for idx, value := results.Values() { -// fmt.Println("%v: %v", results.Positions()[idx], value) -// } -// -// Compiled Queries -// -// Queries may be executed directly on a TomlTree object, or compiled ahead -// of time and executed discretely. The former is more convienent, but has the -// penalty of having to recompile the query expression each time. -// -// // basic query -// results := tree.Query("$.foo.bar.baz") -// -// // compiled query -// query := toml.CompileQuery("$.foo.bar.baz") -// results := query.Execute(tree) -// -// // run the compiled query again on a different tree -// moreResults := query.Execute(anotherTree) -// -// User Defined Query Filters -// -// Filter expressions may also be user defined by using the SetFilter() -// function on the Query object. The function must return true/false, which -// signifies if the passed node is kept or discarded, respectively. -// -// // create a query that references a user-defined filter -// query, _ := CompileQuery("$[?(bazOnly)]") -// -// // define the filter, and assign it to the query -// query.SetFilter("bazOnly", func(node interface{}) bool{ -// if tree, ok := node.(*TomlTree); ok { -// return tree.Has("baz") -// } -// return false // reject all other node types -// }) -// -// // run the query -// query.Execute(tree) +// The package github.com/pelletier/go-toml/query implements a system +// similar to JSONPath to quickly retrive elements of a TOML document using a +// single expression. See the package documentation for more information. // package toml |