fetch

README

go-fetch

A small library that affords the use of simple jq/javascript/python-style accessors on nested interface{}s. go-fetch is not a replacement for properly unmarshalling JSON into appropriate structs and is intended to be used in situations where embedded data-accessing/querying is needed.

Documentation available at http://godoc.org/github.com/nikhan/go-fetch.

For example, given a map with the following structure:

{
    "foo":{
        "bar":[1,2,3]
    }
}

the third element of bar can be accessed by:

result, err := Fetch.Fetch(".foo.bar[2]", obj)

All queries must start with ., as this refers to the root of the value that is passed to go-fetch. Making a query . will return the entire value itself.

go-fetch supports bracket accessors for maps, so if you need to access a key that has characters that need to be avoided (such as a .,#,$,*,%,!), you can do so:

result, err := Fetch.Fetch(`.["foo"].bar[2]`, obj)

Fetch.Fetch() is a convenience function that runs both Fetch.Parse() and Fetch.Run(). If you have a situation where you will be running the same query over lots of values it is highly recommended that you Fetch.Parse() your query once and Fetch.Run() each value that needs to be queried.

query, _ := Fetch.Parse(`.["stop.trying"].to[0].make.fetch.happen`)
for{
    select {
        case m := <-data:
            Fetch.Run(query, m)
...

BenchmarkFetch	  				200000	     17778 ns/op
BenchmarkFetchParseOnce	  	  10000000	       168 ns/op
BenchmarkNoFetch			  20000000	       117 ns/op
BenchmarkNoFetchNoCheck		2000000000	      1.45 ns/op

The above benchmarks were run on a 2010 Macbook Pro. BenchmarkFetch is running Fetch.Fetch(). You can see that parsing the query every time can be costly. The second benchmark, BenchmarkFetchParseOnce compiles the query once with Fetch.Parse(). BenchmarkNoFetch is testing the time it takes to do all of the assertions on a map of interfaces{}. Finally, BenchmarkNoFetchNoCheck is what happens when dealing with properly typed structs.

Documentation

Index

• func Fetch(input string, obj interface{}) (interface{}, error)
• func Run(l *Query, o interface{}) (interface{}, error)
• type Query
  • func Parse(input string) (*Query, error)
  • func (l *Query) MarshalJSON() ([]byte, error)
  • func (l *Query) String() string

Functions

func Fetch

func Fetch(input string, obj interface{}) (interface{}, error)

A convenience function that runs both Parse() and Run() automatically. It is highly recommended that you parse your query ahead of time with Fetch.Parse() and follow up with Fetch.Run() instead.

func Run

func Run(l *Query, o interface{}) (interface{}, error)

Executes a *Fetch.Query on some data. Returns the result of the query.

Types

type Query

type Query struct {
	// contains filtered or unexported fields
}

func Parse

func Parse(input string) (*Query, error)

Converts a query string into a *Fetch.Query. Fetch.Parse is similar to jq, in that in order to reference the base value, you must begin a query with '.' For example, a query string of '.' will return an entire value, a query string of '.foo' will return the value of key foo on the root of the value. Every subsequent field can be accessed through javascript-style dot/bracket notation. for example, .foo[0] would return the first element of array foo, and .["foo"][0] would do the same as well.

func (*Query) MarshalJSON

func (l *Query) MarshalJSON() ([]byte, error)

func (*Query) String

func (l *Query) String() string