gojq package - github.com/itchyny/gojq

gojq package - github.com/itchyny/gojq - Go Packages

Package gojq provides the parser and the interpreter of gojq. Please refer to Usage as a library for introduction.

This section is empty.

Compare l and r, and returns jq-flavored comparison value. The result will be 0 if l == r, -1 if l < r, and +1 if l > r. This comparison is used by built-in operators and functions.

Marshal returns the jq-flavored JSON encoding of v.

This method accepts only limited types (nil, bool, int, float64, *big.Int, json.Number, string, []any, and map[string]any) 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 '<', '>', '&', '\u2028', and '\u2029'. These behaviors are based on the marshaler of jq command, and different from json.Marshal in the Go standard library. Note that the result is not safe to embed in HTML.

Preview returns the preview string of v. The preview string is basically the same as the jq-flavored JSON encoding returned by Marshal, but is truncated by 30 bytes, and more efficient than truncating the result of Marshal.

This method is used by error messages of built-in operators and functions, and accepts only limited types (nil, bool, int, float64, *big.Int, json.Number, string, []any, and map[string]any). Note that the maximum width and trailing strings on truncation may be changed in the future.

TypeOf returns the jq-flavored type name of v.

This method is used by built-in type/0 function, and accepts only limited types (nil, bool, int, float64, *big.Int, json.Number, string, []any, and map[string]any).

type Array struct {
	Query *Query
}

Array ...

Code is a compiled jq query.

func Compile(q *Query, options ...CompilerOption) (*Code, error)

Compile compiles a query.

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([]any{
		nil,
		"string",
		42,
		[]any{"foo"},
		map[string]any{"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 (c *Code) Run(v any, values ...any) Iter

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 in goroutines, to reuse a compiled *Code.

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]any{"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

RunWithContext runs the code with context.

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 func(*compiler)

CompilerOption is a compiler option.

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 reasons. You can specify os.Environ as argument if you allow to access.

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"

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, take account of int, float64, *big.Int, and json.Number. 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.

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"math/big"
	"strconv"

	"github.com/itchyny/gojq"
)

func toFloat(x any) (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
	case json.Number:
		f, err := x.Float64()
		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 any, xs []any) any {
			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 := []any{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(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.

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

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.

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() (any, 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(_ any, xs []any) 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(moduleLoader ModuleLoader) CompilerOption

WithModuleLoader is a compiler option for module loader. If you want to load modules from the filesystem, use NewModuleLoader.

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 g: foo::f;
		`)
	case "module2":
		return gojq.Parse(`
			def f: .foo;
		`)
	case "module3":
		return gojq.Parse("")
	}
	return nil, fmt.Errorf("module not found: %q", name)
}

func main() {
	query, err := gojq.Parse(`
		import "module1" as m;
		m::g
	`)
	if err != nil {
		log.Fatalln(err)
	}
	code, err := gojq.Compile(
		query,
		gojq.WithModuleLoader(&moduleLoader{}),
	)
	if err != nil {
		log.Fatalln(err)
	}
	input := map[string]any{"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(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.

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 struct {
	Elems []*ConstTerm
}

ConstArray ...

type ConstObject struct {
	KeyVals []*ConstObjectKeyVal
}

ConstObject ...

ToValue converts the object to map[string]any.

type ConstObjectKeyVal struct {
	Key       string
	KeyString string
	Val       *ConstTerm
}

ConstObjectKeyVal ...

type Foreach struct {
	Query   *Query
	Pattern *Pattern
	Start   *Query
	Update  *Query
}

Foreach ...

type Func struct {
	Name string
	Args []*Query
}

Func ...

type HaltError exitCodeError

HaltError is an error emitted by halt and halt_error functions. It implements ValueError, and if the value is nil, discard the error and stop the iteration. Consider a query like "1, halt, 2"; the first value is 1, and the second value is a HaltError with nil value. You might think the iterator should not emit an error this case, but it should so that we can recognize the halt error to stop the outer loop of iterating input values; echo 1 2 3 | gojq "., halt".

func (err *HaltError) ExitCode() int

ExitCode returns the exit code of the error.

func (err *HaltError) Value() any

Value returns the value of the error. This implements ValueError, but halt error is not catchable by try-catch.

type If struct {
	Cond *Query
	Then *Query
	Elif []*IfElif
	Else *Query
}

If ...

type IfElif struct {
	Cond *Query
	Then *Query
}

IfElif ...

type Index struct {
	Name    string
	Str     *String
	Start   *Query
	End     *Query
	IsSlice bool
}

Index ...

type Iter interface {
	Next() (any, bool)
}

Iter is an interface for an iterator.

func NewIter[T any](values ...T) Iter

NewIter creates a new Iter from values.

type Label struct {
	Ident string
	Body  *Query
}

Label ...

ModuleLoader is the interface for loading modules.

Implement following optional methods. Use NewModuleLoader to load local modules.

LoadInitModules() ([]*Query, error)
LoadModule(string) (*Query, error)
LoadModuleWithMeta(string, map[string]any) (*Query, error)
LoadJSON(string) (any, error)
LoadJSONWithMeta(string, map[string]any) (any, error)

func NewModuleLoader(paths []string) ModuleLoader

NewModuleLoader creates a new ModuleLoader loading local modules in the paths. Note that user can load modules outside the paths using "search" path of metadata. Empty paths are ignored, so specify "." for the current working directory.

type Object struct {
	KeyVals []*ObjectKeyVal
}

Object ...

type ObjectKeyVal struct {
	Key       string
	KeyString *String
	KeyQuery  *Query
	Val       *Query
}

ObjectKeyVal ...

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 ParseError struct {
	Offset int    
	Token  string 
	
}

ParseError represents a description of a query parsing error.

type Pattern struct {
	Name   string
	Array  []*Pattern
	Object []*PatternObject
}

Pattern ...

type PatternObject struct {
	Key       string
	KeyString *String
	KeyQuery  *Query
	Val       *Pattern
}

PatternObject ...

type Query struct {
	Meta     *ConstObject
	Imports  []*Import
	FuncDefs []*FuncDef
	Term     *Term
	Left     *Query
	Right    *Query
	Patterns []*Pattern
	Op       Operator
}

Query represents the abstract syntax tree of a jq query.

Parse a query string, and returns the query struct.

If parsing failed, it returns an error of type *ParseError, which has the byte offset and the invalid token. The byte offset is the scanned bytes when the error occurred. The token is empty if the error occurred after scanning the entire query string.

func (e *Query) Run(v any) Iter

Run the query.

It is safe to call this method in goroutines, to reuse a parsed *Query.

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]any{"foo": []any{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

RunWithContext runs the query with context.

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 Reduce struct {
	Query   *Query
	Pattern *Pattern
	Start   *Query
	Update  *Query
}

Reduce ...

type String struct {
	Str     string
	Queries []*Query
}

String ...

type Suffix struct {
	Index    *Index
	Iter     bool
	Optional bool
}

Suffix ...

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 ...

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 Try struct {
	Body  *Query
	Catch *Query
}

Try ...

type Unary struct {
	Op   Operator
	Term *Term
}

Unary ...

type ValueError interface {
	error
	Value() any
}

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.