jq

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 25, 2017 License: MIT Imports: 7 Imported by: 4

Documentation

Overview

Package jq provides go bindings for libjq providing a streaming filter of JSON documents.

This package provides a thin layer on top of stedolan's libjq -- it would likely be helpful to read through the wiki pages about it:

jv: the JSON value type https://github.com/stedolan/jq/wiki/C-API:-jv

libjq: https://github.com/stedolan/jq/wiki/C-API:-libjq

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Jq 

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

Jq encapsulates the state needed to interface with the libjq C library

func New 

func New() (*Jq, error)

New initializes a new JQ object and the underlying C library.

func (*Jq) Close 

func (jq *Jq) Close()

Close the handle to libjq and free C resources.

If Start() has been called this will block until the input Channel it returns has been closed.

func (*Jq) Compile added in v0.1.0 

func (jq *Jq) Compile(prog string, args *Jv) (errs []error)

Compile the program and make it ready to Execute()

Only a single program can be compiled on a Jq object at once. Calling this again a second time will replace the current program.

args is a list of key/value pairs to bind as variables into the program, and must be an array type even if empty. Each element of the array should be an object with a "name" and "value" properties. Name should exclude the "$" sign. For example this is `[ {"name": "n", "value": 1 } ]` would then be `$n` in the program.

func (*Jq) Execute added in v0.1.0 

func (jq *Jq) Execute(input *Jv) (results []*Jv, err error)

Execute will run the Compiled() program against a single input and return the results.

Using this interface directly is not thread-safe -- it is up to the caller to ensure that this is not called from two goroutines concurrently.

func (*Jq) Start 

func (jq *Jq) Start(program string, args *Jv) (in chan<- *Jv, out <-chan *Jv, errs <-chan error)

Start will compile `program` and return a three channels: input, output and error. Sending a jq.Jv* to input cause the program to be run to it and one-or-more results returned as jq.Jv* on the output channel, or one or more error values sent to the error channel. When you are done sending values close the input channel.

args is a list of key/value pairs to bind as variables into the program, and must be an array type even if empty. Each element of the array should be an object with a "name" and "value" properties. Name should exclude the "$" sign. For example this is `[ {"name": "n", "value": 1 } ]` would then be `$n` in the programm.

This function is not reentereant -- in that you cannot and should not call Start again until you have closed the previous input channel.

If there is a problem compiling the JQ program then the errors will be reported on error channel before any input is read so makle sure you account for this case.

Any jq.Jv* values passed to the input channel will be owned by the channel. If you want to keep them afterwards ensure you Copy() them before passing to the channel

type Jv 

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

Jv represents a JSON value from libjq.

The go wrapper uses the same memory management semantics as the underlying C library, so you should familiarize yourself with https://github.com/stedolan/jq/wiki/C-API:-jv#memory-management. In summary this package and all JQ functions operate on the assumption that any jv value you pass to a function is then owned by that function -- if you do not wish this to be the case call Copy() on it first.

func JvArray 

func JvArray() *Jv

JvArray creates a new, empty array-typed JV

func JvFromBool added in v0.1.0 

func JvFromBool(b bool) *Jv

JvFromBool returns a new jv of "true" or "false" kind depending on the given boolean value

func JvFromFloat added in v0.1.0 

func JvFromFloat(n float64) *Jv

JvFromFloat returns a new jv number-typed value containing the given float value.

func JvFromInterface added in v0.1.0 

func JvFromInterface(intf interface{}) (*Jv, error)

func JvFromJSONBytes 

func JvFromJSONBytes(b []byte) (*Jv, error)

JvFromJSONBytes takes a utf-8 byte sequence containing JSON and returns the jv representation of it.

func JvFromJSONString 

func JvFromJSONString(str string) (*Jv, error)

JvFromJSONString takes a JSON string and returns the jv representation of it.

func JvFromString 

func JvFromString(str string) *Jv

JvFromString returns a new jv string-typed value containing the given go string.

func JvInvalid 

func JvInvalid() *Jv

JvInvalid returns an invalid jv object without an error property

func JvInvalidWithMessage 

func JvInvalidWithMessage(msg *Jv) *Jv

JvInvalidWithMessage creates an "invalid" jv with the given error message.

msg can be a string or an object

Consumes `msg`

func JvNull 

func JvNull() *Jv

JvNull returns a value representing a JSON null

func JvObject 

func JvObject() *Jv

func (*Jv) ArrayAppend 

func (jv *Jv) ArrayAppend(val *Jv) *Jv

ArrayAppend appends a single value to the end of the array.

If jv is not an array this will cause an assertion.

Consumes the invocant

func (*Jv) ArrayGet 

func (jv *Jv) ArrayGet(idx int) *Jv

ArrayGet returns the element at the given array index.

If the index is out of bounds it will return an Invalid Jv object (with no error message set).

`idx` cannot be negative.

Consumes the invocant

func (*Jv) ArrayLength 

func (jv *Jv) ArrayLength() int

ArrayLength returns the number of elements in the array.

Consumes the invocant

func (*Jv) Copy 

func (jv *Jv) Copy() *Jv

Copy returns a *Jv so that the original won't get freed.

Does not consume the invocant.

func (*Jv) Dump 

func (jv *Jv) Dump(flags JvPrintFlags) string

Dump produces a human readable version of the string with the requested formatting.

Consumes the invocant

func (*Jv) Free 

func (jv *Jv) Free() *Jv

Free this reference to a Jv value.

Don't call this more than once per jv - might not actually free the memory as libjq uses reference counting. To make this more like the libjq interface we return a nil pointer.

func (*Jv) GetInvalidMessage 

func (jv *Jv) GetInvalidMessage() *Jv

GetInvalidMessage returns the message associcated

func (*Jv) GetInvalidMessageAsString 

func (jv *Jv) GetInvalidMessageAsString() (string, bool)

GetInvalidMessageAsString gets the error message for this Jv. If there is none it will return ("", false). Otherwise it will return the message as a string and true, converting non-string values if necessary. If you want the message in it's native Jv type use `GetInvalidMessage()`

Consumes the invocant.

func (*Jv) IsValid 

func (jv *Jv) IsValid() bool

IsValid returns true if this Jv represents a valid JSON type, or false if it is unitiaizlied or if it represents an error type

Does not consume the invocant.

func (*Jv) Kind 

func (jv *Jv) Kind() JvKind

Kind returns a JvKind saying what type this jv contains.

Does not consume the invocant.

func (*Jv) ObjectSet 

func (jv *Jv) ObjectSet(key *Jv, val *Jv) *Jv

ObjectSet will add val to the object under the given key.

This is the equivalent of `jv[key] = val`.

Consumes invocant and both key and val

func (*Jv) String 

func (jv *Jv) String() (string, error)

If jv is a string, return its value. Will not stringify other types

Does not consume the invocant.

func (*Jv) ToGoVal 

func (jv *Jv) ToGoVal() interface{}

ToGoVal converts a jv into it's closest Go approximation

Does not consume the invocant.

type JvKind 

type JvKind int

JvKind represents the type of value that a `Jv` contains. 

const (
	JV_KIND_INVALID JvKind = C.JV_KIND_INVALID
	JV_KIND_NULL    JvKind = C.JV_KIND_NULL
	JV_KIND_FALSE   JvKind = C.JV_KIND_FALSE
	JV_KIND_TRUE    JvKind = C.JV_KIND_TRUE
	JV_KIND_NUMBER  JvKind = C.JV_KIND_NUMBER
	JV_KIND_STRING  JvKind = C.JV_KIND_STRING
	JV_KIND_ARRAY   JvKind = C.JV_KIND_ARRAY
	JV_KIND_OBJECT  JvKind = C.JV_KIND_OBJECT
)

func (JvKind) String 

func (kind JvKind) String() string

String returns a string representation of what type this Jv contains

type JvPrintFlags 

type JvPrintFlags int
const (
	JvPrintNone     JvPrintFlags = 0                   // None of the below
	JvPrintPretty   JvPrintFlags = C.JV_PRINT_PRETTY   // Print across multiple lines
	JvPrintAscii    JvPrintFlags = C.JV_PRINT_ASCII    // Escape non-ascii printable characters
	JvPrintColour   JvPrintFlags = C.JV_PRINT_COLOUR   // Include ANSI color escapes based on data types
	JvPrintSorted   JvPrintFlags = C.JV_PRINT_SORTED   // Sort output keys
	JvPrintInvalid  JvPrintFlags = C.JV_PRINT_INVALID  // Print invalid as "<invalid>"
	JvPrintRefCount JvPrintFlags = C.JV_PRINT_REFCOUNT // Display refcount of objects in in parenthesis
	JvPrintTab      JvPrintFlags = C.JV_PRINT_TAB      // Indent with tabs,
	JvPrintIsATty   JvPrintFlags = C.JV_PRINT_ISATTY   //
	JvPrintSpace0   JvPrintFlags = C.JV_PRINT_SPACE0   // Indent with zero extra chars beyond the parent bracket
	JvPrintSpace1   JvPrintFlags = C.JV_PRINT_SPACE1   // Indent with zero extra chars beyond the parent bracket
	JvPrintSpace2   JvPrintFlags = C.JV_PRINT_SPACE2   // Indent with zero extra chars beyond the parent bracket
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.