Documentation ¶
Overview ¶
Package gojq provides the parser and interpreter of gojq.
Please refer to https://github.com/itchyny/gojq#usage-as-a-library for introduction of the usage as a library.
Index ¶
- func Marshal(v interface{}) ([]byte, error)
- type Array
- type Bind
- type Code
- type CompilerOption
- func WithEnvironLoader(environLoader func() []string) CompilerOption
- func WithFunction(name string, minarity, maxarity int, ...) CompilerOption
- func WithInputIter(inputIter Iter) CompilerOption
- func WithIterFunction(name string, minarity, maxarity int, f func(interface{}, []interface{}) Iter) CompilerOption
- func WithModuleLoader(moduleLoader ModuleLoader) CompilerOption
- func WithVariables(variables []string) CompilerOption
- type ConstArray
- type ConstObject
- type ConstObjectKeyVal
- type ConstTerm
- type Foreach
- type Func
- type FuncDef
- type If
- type IfElif
- type Import
- type Index
- type Iter
- type Label
- type ModuleLoader
- type Object
- type ObjectKeyVal
- type ObjectVal
- type Operator
- type Pattern
- type PatternObject
- type Query
- type Reduce
- type String
- type Suffix
- type Term
- type TermType
- type Try
- type Unary
- type ValueError
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Marshal ¶ added in v0.12.0
Marshal returns the jq-flavored JSON encoding of v.
This method only accepts limited types (nil, bool, int, float64, *big.Int, string, []interface{} and map[string]interface{}) because these are the possible types a gojq iterator can emit. This method marshals NaN to null, truncates infinities to (+|-) math.MaxFloat64, uses \b and \f in strings, and does not escape '<' and '>' for embedding in HTML. These behaviors are based on the marshaler of jq command and different from Go standard library method json.Marshal.
Types ¶
type Code ¶ added in v0.8.0
type Code struct {
// contains filtered or unexported fields
}
Code is a compiled jq query.
func Compile ¶ added in v0.8.0
func Compile(q *Query, options ...CompilerOption) (*Code, error)
Compile compiles a query.
Example ¶
package main import ( "fmt" "log" "github.com/itchyny/gojq" ) func main() { query, err := gojq.Parse(".[] | .foo") if err != nil { log.Fatalln(err) } code, err := gojq.Compile(query) if err != nil { log.Fatalln(err) } iter := code.Run([]interface{}{ nil, "string", 42, []interface{}{"foo"}, map[string]interface{}{"foo": 42}, }) for { v, ok := iter.Next() if !ok { break } if err, ok := v.(error); ok { fmt.Println(err) continue } fmt.Printf("%#v\n", v) } }
Output: <nil> expected an object but got: string ("string") expected an object but got: number (42) expected an object but got: array (["foo"]) 42
func (*Code) Run ¶ added in v0.8.0
Run runs the code with the variable values (which should be in the same order as the given variables using WithVariables) and returns a result iterator.
It is safe to call this method of a *Code in multiple goroutines.
Example ¶
package main import ( "fmt" "log" "github.com/itchyny/gojq" ) func main() { query, err := gojq.Parse(".foo") if err != nil { log.Fatalln(err) } code, err := gojq.Compile(query) if err != nil { log.Fatalln(err) } input := map[string]interface{}{"foo": 42} iter := code.Run(input) for { v, ok := iter.Next() if !ok { break } if err, ok := v.(error); ok { log.Fatalln(err) } fmt.Printf("%#v\n", v) } }
Output: 42
func (*Code) RunWithContext ¶ added in v0.8.0
RunWithContext runs the code with context.
Example ¶
package main import ( "context" "fmt" "log" "time" "github.com/itchyny/gojq" ) func main() { query, err := gojq.Parse("def f: f; f, f") if err != nil { log.Fatalln(err) } code, err := gojq.Compile(query) if err != nil { log.Fatalln(err) } ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) defer cancel() iter := code.RunWithContext(ctx, nil) for { v, ok := iter.Next() if !ok { break } if err, ok := v.(error); ok { fmt.Println(err) continue } _ = v } }
Output: context deadline exceeded
type CompilerOption ¶ added in v0.8.0
type CompilerOption func(*compiler)
CompilerOption is a compiler option.
func WithEnvironLoader ¶ added in v0.9.0
func WithEnvironLoader(environLoader func() []string) CompilerOption
WithEnvironLoader is a compiler option for environment variables loader. The OS environment variables are not accessible by default due to security reason. You can pass os.Environ if you allow to access it.
Example ¶
package main import ( "fmt" "log" "github.com/itchyny/gojq" ) func main() { query, err := gojq.Parse("env | keys[]") if err != nil { log.Fatalln(err) } code, err := gojq.Compile( query, gojq.WithEnvironLoader(func() []string { return []string{"foo=42", "bar=128"} }), ) if err != nil { log.Fatalln(err) } iter := code.Run(nil) for { v, ok := iter.Next() if !ok { break } if err, ok := v.(error); ok { log.Fatalln(err) } fmt.Printf("%#v\n", v) } }
Output: "bar" "foo"
func WithFunction ¶ added in v0.12.0
func WithFunction(name string, minarity, maxarity int, f func(interface{}, []interface{}) interface{}) CompilerOption
WithFunction is a compiler option for adding a custom internal function. Specify the minimum and maximum count of the function arguments. These values should satisfy 0 <= minarity <= maxarity <= 30, otherwise panics. On handling numbers, you should take account to int, float64 and *big.Int. These are the number types you are allowed to return, so do not return int64. Refer to ValueError to return a value error just like built-in error function. If you want to emit multiple values, call the empty function, accept a filter for its argument, or call another built-in function, then use LoadInitModules of the module loader.
Example ¶
package main import ( "encoding/json" "fmt" "log" "math/big" "strconv" "github.com/itchyny/gojq" ) func toFloat(x interface{}) (float64, bool) { switch x := x.(type) { case int: return float64(x), true case float64: return x, true case *big.Int: f, err := strconv.ParseFloat(x.String(), 64) return f, err == nil default: return 0.0, false } } func main() { query, err := gojq.Parse(".[] | f | f(3)") if err != nil { log.Fatalln(err) } code, err := gojq.Compile( query, gojq.WithFunction("f", 0, 1, func(x interface{}, xs []interface{}) interface{} { if x, ok := toFloat(x); ok { if len(xs) == 1 { if y, ok := toFloat(xs[0]); ok { x *= y } else { return fmt.Errorf("f cannot be applied to: %v, %v", x, xs) } } else { x += 2 } return x } return fmt.Errorf("f cannot be applied to: %v, %v", x, xs) }), ) if err != nil { log.Fatalln(err) } input := []interface{}{0, 1, 2.5, json.Number("10000000000000000000000000000000000000000")} iter := code.Run(input) for { v, ok := iter.Next() if !ok { break } if err, ok := v.(error); ok { log.Fatalln(err) } fmt.Printf("%#v\n", v) } }
Output: 6 9 13.5 3e+40
func WithInputIter ¶ added in v0.10.0
func WithInputIter(inputIter Iter) CompilerOption
WithInputIter is a compiler option for input iterator used by input(s)/0. Note that input and inputs functions are not allowed by default. We have to distinguish the query input and the values for input(s) functions. For example, consider using inputs with --null-input. If you want to allow input(s) functions, create an Iter and use WithInputIter option.
Example ¶
package main import ( "fmt" "log" "github.com/itchyny/gojq" ) func main() { query, err := gojq.Parse("reduce inputs as $x (0; . + $x)") if err != nil { log.Fatalln(err) } code, err := gojq.Compile( query, gojq.WithInputIter(gojq.NewIter(1, 2, 3, 4, 5)), ) if err != nil { log.Fatalln(err) } iter := code.Run(nil) for { v, ok := iter.Next() if !ok { break } if err, ok := v.(error); ok { log.Fatalln(err) } fmt.Printf("%#v\n", v) } }
Output: 15
func WithIterFunction ¶ added in v0.12.4
func WithIterFunction(name string, minarity, maxarity int, f func(interface{}, []interface{}) Iter) CompilerOption
WithIterFunction is a compiler option for adding a custom iterator function. This is like the WithFunction option, but you can add a function which returns an Iter to emit multiple values. You cannot define both iterator and non-iterator functions of the same name (with possibly different arities). See also NewIter, which can be used to convert values or an error to an Iter.
Example ¶
package main import ( "fmt" "log" "github.com/itchyny/gojq" ) // Implementation of range/2 using WithIterFunction option. type rangeIter struct { value, max int } func (iter *rangeIter) Next() (interface{}, bool) { if iter.value >= iter.max { return nil, false } v := iter.value iter.value++ return v, true } func main() { query, err := gojq.Parse("f(3; 7)") if err != nil { log.Fatalln(err) } code, err := gojq.Compile( query, gojq.WithIterFunction("f", 2, 2, func(_ interface{}, xs []interface{}) gojq.Iter { if x, ok := xs[0].(int); ok { if y, ok := xs[1].(int); ok { return &rangeIter{x, y} } } return gojq.NewIter(fmt.Errorf("f cannot be applied to: %v", xs)) }), ) if err != nil { log.Fatalln(err) } iter := code.Run(nil) for { v, ok := iter.Next() if !ok { break } if err, ok := v.(error); ok { log.Fatalln(err) } fmt.Printf("%#v\n", v) } }
Output: 3 4 5 6
func WithModuleLoader ¶ added in v0.8.0
func WithModuleLoader(moduleLoader ModuleLoader) CompilerOption
WithModuleLoader is a compiler option for module loader. If you want to load modules from the filesystem, use NewModuleLoader.
Example ¶
package main import ( "fmt" "log" "github.com/itchyny/gojq" ) type moduleLoader struct{} func (*moduleLoader) LoadModule(name string) (*gojq.Query, error) { switch name { case "module1": return gojq.Parse(` module { name: "module1", test: 42 }; import "module2" as foo; def f: foo::f; `) case "module2": return gojq.Parse(` def f: .foo; `) } return nil, fmt.Errorf("module not found: %q", name) } func main() { query, err := gojq.Parse(` import "module1" as m; m::f `) if err != nil { log.Fatalln(err) } code, err := gojq.Compile( query, gojq.WithModuleLoader(&moduleLoader{}), ) if err != nil { log.Fatalln(err) } input := map[string]interface{}{"foo": 42} iter := code.Run(input) for { v, ok := iter.Next() if !ok { break } if err, ok := v.(error); ok { log.Fatalln(err) } fmt.Printf("%#v\n", v) } }
Output: 42
func WithVariables ¶ added in v0.8.0
func WithVariables(variables []string) CompilerOption
WithVariables is a compiler option for variable names. The variables can be used in the query. You have to give the values to code.Run in the same order.
Example ¶
package main import ( "fmt" "log" "github.com/itchyny/gojq" ) func main() { query, err := gojq.Parse("$x * 100 + $y, $z") if err != nil { log.Fatalln(err) } code, err := gojq.Compile( query, gojq.WithVariables([]string{ "$x", "$y", "$z", }), ) if err != nil { log.Fatalln(err) } iter := code.Run(nil, 12, 42, 128) for { v, ok := iter.Next() if !ok { break } if err, ok := v.(error); ok { log.Fatalln(err) } fmt.Printf("%#v\n", v) } }
Output: 1242 128
type ConstArray ¶ added in v0.8.0
type ConstArray struct {
Elems []*ConstTerm
}
ConstArray ...
func (*ConstArray) String ¶ added in v0.8.0
func (e *ConstArray) String() string
type ConstObject ¶ added in v0.8.0
type ConstObject struct {
KeyVals []*ConstObjectKeyVal
}
ConstObject ...
func (*ConstObject) String ¶ added in v0.8.0
func (e *ConstObject) String() string
func (*ConstObject) ToValue ¶ added in v0.10.0
func (e *ConstObject) ToValue() map[string]interface{}
ToValue converts the object to map[string]interface{}.
type ConstObjectKeyVal ¶ added in v0.8.0
ConstObjectKeyVal ...
func (*ConstObjectKeyVal) String ¶ added in v0.8.0
func (e *ConstObjectKeyVal) String() string
type ConstTerm ¶ added in v0.8.0
type ConstTerm struct { Object *ConstObject Array *ConstArray Number string Str string Null bool True bool False bool }
ConstTerm ...
type Import ¶ added in v0.8.0
type Import struct { ImportPath string ImportAlias string IncludePath string Meta *ConstObject }
Import ...
type Iter ¶ added in v0.4.0
type Iter interface {
Next() (interface{}, bool)
}
Iter is an interface for an iterator.
type ModuleLoader ¶ added in v0.8.0
type ModuleLoader interface{}
ModuleLoader is an interface for loading modules.
Implement following optional methods. Use NewModuleLoader to load local modules.
LoadModule(string) (*Query, error) LoadModuleWithMeta(string, map[string]interface{}) (*Query, error) LoadInitModules() ([]*Query, error) LoadJSON(string) (interface{}, error) LoadJSONWithMeta(string, map[string]interface{}) (interface{}, error)
func NewModuleLoader ¶ added in v0.10.4
func NewModuleLoader(paths []string) ModuleLoader
NewModuleLoader creates a new ModuleLoader reading local modules in the paths.
type ObjectKeyVal ¶ added in v0.4.0
type ObjectKeyVal struct { Key string KeyString *String KeyQuery *Query Val *ObjectVal KeyOnly string KeyOnlyString *String }
ObjectKeyVal ...
func (*ObjectKeyVal) String ¶ added in v0.4.0
func (e *ObjectKeyVal) String() string
type Operator ¶ added in v0.1.0
type Operator int
Operator ...
const ( OpPipe Operator = iota + 1 OpComma OpAdd OpSub OpMul OpDiv OpMod OpEq OpNe OpGt OpLt OpGe OpLe OpAnd OpOr OpAlt OpAssign OpModify OpUpdateAdd OpUpdateSub OpUpdateMul OpUpdateDiv OpUpdateMod OpUpdateAlt )
Operators ...
type Pattern ¶ added in v0.3.0
type Pattern struct { Name string Array []*Pattern Object []*PatternObject }
Pattern ...
type PatternObject ¶ added in v0.4.0
type PatternObject struct { Key string KeyString *String KeyQuery *Query Val *Pattern KeyOnly string }
PatternObject ...
func (*PatternObject) String ¶ added in v0.4.0
func (e *PatternObject) String() string
type Query ¶
type Query struct { Meta *ConstObject Imports []*Import FuncDefs []*FuncDef Term *Term Left *Query Op Operator Right *Query Func string }
Query represents the abstract syntax tree of a jq query.
func (*Query) Run ¶ added in v0.1.0
Run the query.
It is safe to call this method of a *Query in multiple goroutines.
Example ¶
package main import ( "fmt" "log" "github.com/itchyny/gojq" ) func main() { query, err := gojq.Parse(".foo | ..") if err != nil { log.Fatalln(err) } input := map[string]interface{}{"foo": []interface{}{1, 2, 3}} iter := query.Run(input) for { v, ok := iter.Next() if !ok { break } if err, ok := v.(error); ok { log.Fatalln(err) } fmt.Printf("%#v\n", v) } }
Output: []interface {}{1, 2, 3} 1 2 3
func (*Query) RunWithContext ¶ added in v0.8.0
RunWithContext runs the query with context.
Example ¶
package main import ( "context" "fmt" "log" "time" "github.com/itchyny/gojq" ) func main() { query, err := gojq.Parse("def f: f; f, f") if err != nil { log.Fatalln(err) } ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) defer cancel() iter := query.RunWithContext(ctx, nil) for { v, ok := iter.Next() if !ok { break } if err, ok := v.(error); ok { fmt.Println(err) continue } _ = v } }
Output: context deadline exceeded
type Term ¶
type Term struct { Type TermType Index *Index Func *Func Object *Object Array *Array Number string Unary *Unary Format string Str *String If *If Try *Try Reduce *Reduce Foreach *Foreach Label *Label Break string Query *Query SuffixList []*Suffix }
Term ...
type TermType ¶ added in v0.11.0
type TermType int
TermType represents the type of Term.
const ( TermTypeIdentity TermType = iota + 1 TermTypeRecurse TermTypeNull TermTypeTrue TermTypeFalse TermTypeIndex TermTypeFunc TermTypeObject TermTypeArray TermTypeNumber TermTypeUnary TermTypeFormat TermTypeString TermTypeIf TermTypeTry TermTypeReduce TermTypeForeach TermTypeLabel TermTypeBreak TermTypeQuery )
TermType list.
type ValueError ¶ added in v0.12.2
type ValueError interface { error Value() interface{} }
ValueError is an interface for errors with a value for internal function. Return an error implementing this interface when you want to catch error values (not error messages) by try-catch, just like built-in error function. Refer to WithFunction to add a custom internal function.