doc.go

// Package toml is a TOML markup language parser.
//
// 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
//
// TOML data may be parsed in two ways: by file, or by string.
//
//   // load TOML data by filename
//   tree, err := toml.LoadFile("filename.toml")
//
//   // load TOML data stored in a string
//   tree, err := toml.Load(stringContainingTomlData)
//
// Either way, the result is a TomlTree object that can be used to navigate the
// structure and data within the original document.
//
//
// 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.Prinln("foo is: %v", 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)
//
package toml