command

README

docs

Documentation

Index

• Constants
• func AsMap(v Value) (map[string]Value, bool)
• func Decode() gloo.Command[[]byte, []byte]
• func JSON(opts ...any) gloo.Command[[]byte, []byte]
• func Process(p Processor) gloo.Command[[]byte, []byte]
• func Query(q QueryScript) gloo.Command[[]byte, []byte]
• type Processor
• type QueryScript
• type Value

Examples

• Decode
• JSON
• Process

Constants

const (
	// ErrInvalidJSON marks a parse failure on a single JSON input line.
	ErrInvalidJSON errs.Const = "json: invalid JSON"
	// ErrInvalidInput marks a decode failure on a single Process line.
	ErrInvalidInput errs.Const = "json: invalid input"
	// ErrDecode marks a streaming decode failure in Decode.
	ErrDecode errs.Const = "json: decode"
	// ErrMarshal marks a re-encoding failure.
	ErrMarshal errs.Const = "json: marshal"
	// ErrQuery marks a cirql query failure (parse or run).
	ErrQuery errs.Const = "json: query"
)

The package's error vocabulary. Every error the package emits is one of these errs.Const sentinels (wrapped around its cause with Const.With), so callers match failure classes with errors.Is rather than comparing strings.

Functions

func AsMap

func AsMap(v Value) (map[string]Value, bool)

AsMap returns v as a JSON object together with ok=true when v is an object; otherwise it returns nil, false. It is a convenience for Processors that only act on objects.

func Decode

func Decode() gloo.Command[[]byte, []byte]

Decode normalizes arbitrary JSON framing into the one-value-per-line form the other json commands expect. It accepts JSON Lines, whitespace/newline separated values, a pretty-printed document, or a single top-level array (whose elements are streamed individually), and emits each value as compact JSON on its own line.

Because reconstructing values can span line boundaries, Decode buffers its input; downstream value-by-value commands (Process and friends) then stream normally.

Example

package main

import (
	"fmt"

	"github.com/gloo-foo/testable"

	command "github.com/gloo-foo/cmd-json"
)

func main() {
	lines, _ := testable.TestLines(command.Decode(), `[{"a":1},{"b":2}]`+"\n")
	for _, line := range lines {
		fmt.Println(line)
	}
}

Output:
{"a":1}
{"b":2}

func JSON

func JSON(opts ...any) gloo.Command[[]byte, []byte]

JSON returns a command that parses each input line as JSON and re-emits it in compact form. Each input line must be valid JSON.

Example

package main

import (
	"fmt"

	"github.com/gloo-foo/testable"

	command "github.com/gloo-foo/cmd-json"
)

func main() {
	lines, _ := testable.TestLines(command.JSON(), `{"b":2,"a":1}`+"\n")
	for _, line := range lines {
		fmt.Println(line)
	}
}

Output:
{"a":1,"b":2}

func Process

func Process(p Processor) gloo.Command[[]byte, []byte]

Process returns a command that, for each input line, decodes one JSON value, applies p, and re-encodes kept values as compact JSON — one value per output line. Blank lines are skipped. Values flow one at a time, so the command streams with backpressure and never buffers the whole input.

This is the shared core every value-oriented json command is built on (see cmd-json/pluck and cmd-json/select).

Example

package main

import (
	"fmt"

	"github.com/gloo-foo/testable"

	command "github.com/gloo-foo/cmd-json"
)

func main() {
	upper := command.Process(func(v command.Value) (command.Value, bool, error) {
		obj, _ := command.AsMap(v)
		return obj, true, nil
	})
	lines, _ := testable.TestLines(upper, `{"b":2,"a":1}`+"\n")
	for _, line := range lines {
		fmt.Println(line)
	}
}

Output:
{"a":1,"b":2}

func Query

func Query(q QueryScript) gloo.Command[[]byte, []byte]

Query returns a command that runs a cirql pipeline query over the JSON input. The full input is decoded into a result set (accepting JSON Lines, a stream of values, or a single top-level array), run through the cirql pipeline, and each result emitted as a compact JSON line. An invalid query fails the stream.

cirql is the GraphQL-influenced JSON pipeline language (map/filter/reduce/ sort/flatMap/limit/uniq over .field expressions) — this is how cmd-json rivals jq in pure Go. See github.com/gomatic/cirql.

cmd-json query 'filter .stars > 1000 | map { name: .name } | sort .name | limit 10'

Types

type Processor

type Processor func(in Value) (out Value, isKeep bool, err error)

Processor transforms a single decoded JSON value. It returns the (possibly rewritten) value and whether to keep it: returning keep=false drops the value from the output stream (filter semantics). Returning a non-nil error stops the stream.

type QueryScript

type QueryScript string

QueryScript is the source text of a cirql pipeline query.

type Value

type Value = any

Value is a decoded JSON value: an object (map[string]Value), array ([]Value), string, float64, bool, or nil. It is the unit every json command operates on.