jq

func Get ¶

func Get(obj any, jspath string) (val any, err error)

Get returns the value at jspath in obj.

An empty path returns obj itself unless obj is nil. Values containing maps, slices, or pointers may share their backing data with obj.

Struct components exactly match names selected by encoding/json's default struct-field rules, including JSON tag names and unambiguous promoted fields. Traversing a nil pointer returns an error matching ErrPathNotFound. An unexported embedded field with an explicit JSON name cannot itself be returned, although its exported fields remain accessible through longer paths.

When traversal reaches an array or slice, a component is a valid index only if it is "0" or begins with an ASCII digit from '1' through '9' followed by zero or more ASCII decimal digits. The index must be at most 4294967294 and representable as int; otherwise the error matches ErrPathNotFound.

func GetAs ¶

func GetAs[T any](obj any, jspath string) (val T, err error)

GetAs returns the value at jspath in obj as T.

It returns ErrTypeMismatch when the resolved value is not assignable to T.

func Set ¶

func Set(obj any, jspath string, val any) (changed bool, err error)

Set updates jspath in obj and reports whether it performed a write.

obj must be a non-nil pointer. An empty path replaces the pointed-to value. Array and slice components follow the index syntax documented by Get. A path into a settable slice may append one element by using an index equal to the slice's current length. Map paths address existing string-keyed entries and do not create new entries. A nil val stores the destination type's zero value.

Struct components and string keys in map-to-struct assignments follow Get's field-selection rules. Set does not allocate nil pointers; a path or map key that would traverse one returns an error matching ErrPathNotFound.

Set leaves obj unchanged when it returns an error. It does not synchronize access to obj; callers must prevent concurrent reads and writes.

func SetChecked ¶ added in v0.2.0

func SetChecked(obj any, jspath string, val any, check func() error) (changed bool, err error)

SetChecked updates jspath only when check accepts the tentative result.

It performs the same update as Set. If the update reports a change, SetChecked calls check exactly once while obj contains the tentative result. A nil error commits the update. If check returns an error, SetChecked restores obj, returns false, and returns the error unchanged. If check panics, SetChecked restores obj before the panic continues. A nil check behaves like Set.

check is not called if the update is invalid or reports no change. It may inspect obj but must not mutate obj or values reachable from it, call Set or SetChecked on them, or retain references into a rejected value. Rollback restores only changes made by SetChecked.

SetChecked does not synchronize access to obj. Callers must prevent concurrent access for the entire call, including while check runs.

package main

import (
	"encoding/json"
	"errors"
	"fmt"

	"github.com/linkdata/jq"
)

func main() {
	value := []string{"one"}
	maxBytes := len(`["one"]`)

	_, err := jq.SetChecked(&value, "1", "two", func() (err error) {
		var data []byte
		if data, err = json.Marshal(value); err == nil && len(data) > maxBytes {
			err = errors.New("value is too large")
		}
		return
	})

	fmt.Println(value)
	fmt.Println(err)
}

Output:
[one]
value is too large