gojsonq

package module
v2.5.9 Latest Latest
Warning

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

 Go to latest Published: Jan 19, 2023 License: MIT Imports: 11 Imported by: 0

README

gojsonq-logo

Build Status Project status Go Report Card Coverage Status GoDoc License

A simple Go package to Query over JSON Data. It provides simple, elegant and fast ODM like API to access, query JSON document

Installation

Install the package using

$ go get github.com/thedevsaddam/gojsonq/v2

Usage

To use the package import it in your *.go code

import "github.com/thedevsaddam/gojsonq/v2"

Let's see a quick example:

See in playground

package main

import gojsonq "github.com/thedevsaddam/gojsonq/v2"

func main() {
	const json = `{"name":{"first":"Tom","last":"Hanks"},"age":61}`
	name := gojsonq.New().FromString(json).Find("name.first")
	println(name.(string)) // Tom
}

Another example:

See in playground

package main

import (
	"fmt"

	gojsonq "github.com/thedevsaddam/gojsonq/v2"
)

func main() {
	const json = `{"city":"dhaka","type":"weekly","temperatures":[30,39.9,35.4,33.5,31.6,33.2,30.7]}`
	avg := gojsonq.New().FromString(json).From("temperatures").Avg()
	fmt.Printf("Average temperature: %.2f", avg) // 33.471428571428575
}

You can query your document using the various query methods such as Find, First, Nth, Pluck, Where, OrWhere, WhereIn, WhereStartsWith, WhereEndsWith, WhereContains, Sort, GroupBy, SortBy and so on. Also you can aggregate data after query using Avg, Count, Max, Min, Sum etc.

Find more query API in Wiki page

Bugs and Issues

If you encounter any bugs or issues, feel free to open an issue at github.

Also, you can shoot me an email to mailto:thedevsaddam@gmail.com for hugs or bugs.

Credit

Special thanks to Nahid Bin Azhar for the inspiration and guidance for the package. Thanks to Ahmed Shamim Hasan Shaon for his support from the very beginning.

Contributors

Contribution

If you are interested to make the package better please send pull requests or create an issue so that others can fix. Read the contribution guide here

License

The gojsonq is an open-source software licensed under the MIT License.

Documentation

Overview

Package gojsonq provides a simple, elegant and fast ODM like API to access/query JSON document.

JSON document can be read from file, string or io.Reader. Accessing the value of json property or querying document is simple as the example below: 

 package main

 import "github.com/thedevsaddam/gojsonq"

 const json = `{"name":{"first":"Tom","last":"Hanks"},"age":61}`

 func main() {
	 name := gojsonq.New().FromString(json).Find("name.first")
	 println(name.(string)) // Tom
 }

For more details, see the documentation and examples.

Index

Constants

View Source 
const (
	DateTimeFormat      = "2006-01-02T15:04:05"
	DateTimeSpaceFormat = "2006-01-02 15:04:05"
	DateFormat          = "2006-01-02"

	Select    = "s:"
	Where     = "w:"
	From      = "f:"
	Limit     = "l:"
	Offset    = "p:"
	SortBy    = "o:"
	Order     = "d:"
	Distinct  = "u:"
	GroupBy   = "g:"
	Time      = "t:"
	Each      = "e:"
	PipeSum   = "sum"
	PipeCount = "count"
	PipeMax   = "max"
	PipeMin   = "min"
	PipeAvg   = "avg"
	PipeFirst = "first"
	PipeLast  = "last"
	PipeNth   = "nth"
	PipeFind  = "find"
	PipePluck = "pluck"
	PipeOnly  = "only"
)

Variables

View Source 
var (
	ErrExpectsPointer = fmt.Errorf("gojsonq: failed to unmarshal, expects pointer")
	ErrImmutable      = fmt.Errorf("gojsonq: failed to unmarshal, target is not mutable")
	ErrTypeMismatch   = fmt.Errorf("gojsonq: failed to unmarshal, target type misatched")
)

Available named error values

Functions

This section is empty.

Types

type Decoder 

type Decoder interface {
	Decode(data []byte, v interface{}) error
}

Decoder provide contract to decode JSON using custom decoder

type DefaultDecoder 

type DefaultDecoder struct{}

DefaultDecoder use json.Unmarshal to decode JSON

func (*DefaultDecoder) Decode 

func (u *DefaultDecoder) Decode(data []byte, v interface{}) error

Decode decodes using json.Unmarshal

type JSONQ 

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

JSONQ describes a JSONQ type which contains all the state

func New 

func New(options ...OptionFunc) *JSONQ

New returns a new instance of JSONQ

func (*JSONQ) Avg 

func (j *JSONQ) Avg(property ...string) float64

Avg returns average of values from array or from map using property

func (*JSONQ) Copy 

func (j *JSONQ) Copy() *JSONQ

Copy returns a new fresh instance of JSONQ with the original copy of data so that you can do concurrent operation on the same data without being decoded again

func (*JSONQ) Count 

func (j *JSONQ) Count() int

Count returns the number of total items. This could be a length of list/array/map

func (*JSONQ) Distinct 

func (j *JSONQ) Distinct(property string) *JSONQ

Distinct builds distinct value using provided attribute/column/property

func (*JSONQ) Error 

func (j *JSONQ) Error() error

Error returns first occurred error

func (*JSONQ) Errors 

func (j *JSONQ) Errors() []error

Errors returns list of all errors

func (*JSONQ) File 

func (j *JSONQ) File(filename string) *JSONQ

File read the json content from physical file

func (*JSONQ) Find 

func (j *JSONQ) Find(path string) interface{}

Find returns the result of a exact matching path

func (*JSONQ) FindR 

func (j *JSONQ) FindR(path string) (*Result, error)

FindR returns the result as Result instance from the exact matching path

func (*JSONQ) First 

func (j *JSONQ) First() interface{}

First returns the first element of a list

func (*JSONQ) FirstR 

func (j *JSONQ) FirstR() (*Result, error)

FirstR returns the first element of a list as Result instance

func (*JSONQ) From 

func (j *JSONQ) From(node string) *JSONQ

From seeks the json content to provided node. e.g: "users.[0]" or "users.[0].name"

func (*JSONQ) FromInterface 

func (j *JSONQ) FromInterface(v interface{}) *JSONQ

FromInterface reads the content from valid map[string]interface{}

func (*JSONQ) FromString 

func (j *JSONQ) FromString(str string) *JSONQ

FromString reads the content from valid json/xml/csv/yml string

func (*JSONQ) Get 

func (j *JSONQ) Get() interface{}

Get return the result

func (*JSONQ) GetR 

func (j *JSONQ) GetR() (*Result, error)

GetR return the query results as Result instance

func (*JSONQ) GroupBy 

func (j *JSONQ) GroupBy(property string) *JSONQ

GroupBy builds a chunk of exact matched data in a group list using provided attribute/column/property

func (*JSONQ) JSONString 

func (j *JSONQ) JSONString(json string) *JSONQ

JSONString reads the json content from valid json string Deprecated: this method will remove in next major release

func (*JSONQ) Last 

func (j *JSONQ) Last() interface{}

Last returns the last element of a list

func (*JSONQ) LastR 

func (j *JSONQ) LastR() (*Result, error)

LastR returns the last element of a list as Result instance

func (*JSONQ) Limit 

func (j *JSONQ) Limit(limit int) *JSONQ

Limit limits the number of records in result

func (*JSONQ) Macro 

func (j *JSONQ) Macro(operator string, fn QueryFunc) *JSONQ

Macro adds a new query func to the JSONQ

func (*JSONQ) Max 

func (j *JSONQ) Max(property ...string) float64

Max returns maximum value from array or from map using property

func (*JSONQ) Min 

func (j *JSONQ) Min(property ...string) float64

Min returns minimum value from array or from map using property

func (*JSONQ) More 

func (j *JSONQ) More() *JSONQ

More provides the functionality to query over the resultant data. See https://github.com/thedevsaddam/gojsonq/wiki/Queries#More

func (*JSONQ) Nth 

func (j *JSONQ) Nth(index int) interface{}

Nth returns the nth element of a list

func (*JSONQ) NthR 

func (j *JSONQ) NthR(index int) (*Result, error)

NthR returns the nth element of a list as Result instance

func (*JSONQ) Offset 

func (j *JSONQ) Offset(offset int) *JSONQ

Offset skips the number of records in result

func (*JSONQ) Only 

func (j *JSONQ) Only(properties ...string) interface{}

Only collects the properties from a list of object

func (*JSONQ) OnlyR 

func (j *JSONQ) OnlyR(properties ...string) (*Result, error)

OnlyR collects the properties from a list of object and return as Result instance

func (*JSONQ) OrWhere 

func (j *JSONQ) OrWhere(key, cond string, val interface{}) *JSONQ

OrWhere builds an OrWhere clause, basically it's a group of AND clauses

func (*JSONQ) Out 

func (j *JSONQ) Out(v interface{})

Out write the queried data to defined custom type

func (*JSONQ) Pluck 

func (j *JSONQ) Pluck(property string) interface{}

Pluck build an array of values form a property of a list of objects

func (*JSONQ) PluckR 

func (j *JSONQ) PluckR(property string) (*Result, error)

PluckR build an array of values form a property of a list of objects and return as Result instance

func (*JSONQ) Reader 

func (j *JSONQ) Reader(r io.Reader) *JSONQ

Reader reads the json content from io reader

func (*JSONQ) Reset 

func (j *JSONQ) Reset() *JSONQ

Reset resets the current state of JSON instance and make a fresh object with the original json content

func (*JSONQ) Select 

func (j *JSONQ) Select(properties ...string) *JSONQ

Select use for selection of the properties from query result

func (*JSONQ) Sort 

func (j *JSONQ) Sort(order ...string) *JSONQ

Sort sorts an array default ascending order, pass "desc" for descending order

func (*JSONQ) SortBy 

func (j *JSONQ) SortBy(order ...string) *JSONQ

SortBy sorts an array default ascending order, pass "desc" for descending order

func (*JSONQ) String 

func (j *JSONQ) String() string

String satisfies stringer interface

func (*JSONQ) Sum 

func (j *JSONQ) Sum(property ...string) float64

Sum returns sum of values from array or from map using property

func (*JSONQ) Where 

func (j *JSONQ) Where(key, cond string, val interface{}) *JSONQ

Where builds a where clause. e.g: Where("name", "contains", "doe")

func (*JSONQ) WhereContains 

func (j *JSONQ) WhereContains(key string, val interface{}) *JSONQ

WhereContains satisfies Where clause which contains provided value(string)

func (*JSONQ) WhereEndsWith 

func (j *JSONQ) WhereEndsWith(key string, val interface{}) *JSONQ

WhereEndsWith satisfies Where clause which ends with provided value(string)

func (*JSONQ) WhereEqual 

func (j *JSONQ) WhereEqual(key string, val interface{}) *JSONQ

WhereEqual is an alias of Where("key", "=", val)

func (*JSONQ) WhereIn 

func (j *JSONQ) WhereIn(key string, val interface{}) *JSONQ

WhereIn is an alias for where("key", "in", []string{"a", "b"})

func (*JSONQ) WhereLenEqual 

func (j *JSONQ) WhereLenEqual(key string, val interface{}) *JSONQ

WhereLenEqual is an alias of Where("key", "leneq", val)

func (*JSONQ) WhereLenNotEqual 

func (j *JSONQ) WhereLenNotEqual(key string, val interface{}) *JSONQ

WhereLenNotEqual is an alias of Where("key", "lenneq", val)

func (*JSONQ) WhereNil 

func (j *JSONQ) WhereNil(key string) *JSONQ

WhereNil is an alias of Where("key", "=", nil)

func (*JSONQ) WhereNotEqual 

func (j *JSONQ) WhereNotEqual(key string, val interface{}) *JSONQ

WhereNotEqual is an alias of Where("key", "!=", val)

func (*JSONQ) WhereNotIn 

func (j *JSONQ) WhereNotIn(key string, val interface{}) *JSONQ

WhereNotIn is an alias for where("key", "notIn", []string{"a", "b"})

func (*JSONQ) WhereNotNil 

func (j *JSONQ) WhereNotNil(key string) *JSONQ

WhereNotNil is an alias of Where("key", "!=", nil)

func (*JSONQ) WhereStartsWith 

func (j *JSONQ) WhereStartsWith(key string, val interface{}) *JSONQ

WhereStartsWith satisfies Where clause which starts with provided value(string)

func (*JSONQ) WhereStrictContains 

func (j *JSONQ) WhereStrictContains(key string, val interface{}) *JSONQ

WhereStrictContains satisfies Where clause which contains provided value(string). This is case sensitive

func (*JSONQ) Writer 

func (j *JSONQ) Writer(w io.Writer)

Writer write the queried data to a io.Writer

type OptionFunc 

type OptionFunc func(*JSONQ) error

OptionFunc represents a contract for option func, it basically set options to jsonq instance options

func SetDecoder 

func SetDecoder(u Decoder) OptionFunc

SetDecoder take a custom decoder to decode JSON Deprecated - use WithDecoder

func SetSeparator 

func SetSeparator(s string) OptionFunc

SetSeparator set custom separator for traversing child node, default separator is DOT (.) Deprecated - use WithSeparator

func WithDecoder 

func WithDecoder(u Decoder) OptionFunc

WithDecoder take a custom decoder to decode JSON

func WithSeparator 

func WithSeparator(s string) OptionFunc

WithSeparator set custom separator for traversing child node, default separator is DOT (.)

type Query 

type Query struct {
	Raw              string
	Select           []string
	SelectMapAsArray bool
	Each             string
	From             string
	Where            [][]query
	Limit            int
	Offset           int
	SortBy           string
	Order            string
	Distinct         string
	Pipe             string
	PipeParam        string
	GroupBy          string
	Next             *Query
}

func Parse 

func Parse(str string) *Query

func (*Query) Chain 

func (q *Query) Chain(jq *JSONQ) *JSONQ

func (*Query) Get 

func (q *Query) Get(data interface{}) interface{}

func (*Query) PipeResult 

func (q *Query) PipeResult(jq *JSONQ) interface{}

func (*Query) Prepare 

func (q *Query) Prepare(data interface{}) *JSONQ

type QueryFunc 

type QueryFunc func(x, y interface{}) (bool, error)

QueryFunc describes a conditional function which perform comparison

type Result 

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

Result represent custom type

func NewResult 

func NewResult(v interface{}) *Result

NewResult return an instance of Result

func (*Result) As 

func (r *Result) As(v interface{}) error

As sets the value of Result to v; It does not support methods with argument available in Result

func (*Result) Bool 

func (r *Result) Bool() (bool, error)

Bool assert the result to boolean value

func (*Result) BoolSlice 

func (r *Result) BoolSlice() ([]bool, error)

BoolSlice assert the result to []bool

func (*Result) Duration 

func (r *Result) Duration() (time.Duration, error)

Duration assert the result to time.Duration

func (*Result) DurationSlice 

func (r *Result) DurationSlice() ([]time.Duration, error)

DurationSlice assert the result to []time.Duration

func (*Result) Float32 

func (r *Result) Float32() (float32, error)

Float32 assert the result to float32

func (*Result) Float32Slice 

func (r *Result) Float32Slice() ([]float32, error)

Float32Slice assert the result to []float32

func (*Result) Float64 

func (r *Result) Float64() (float64, error)

Float64 assert the result to 64

func (*Result) Float64Slice 

func (r *Result) Float64Slice() ([]float64, error)

Float64Slice assert the result to []float64

func (*Result) Int 

func (r *Result) Int() (int, error)

Int assert the result to int

func (*Result) Int16 

func (r *Result) Int16() (int16, error)

Int16 assert the result to int16

func (*Result) Int16Slice 

func (r *Result) Int16Slice() ([]int16, error)

Int16Slice assert the result to []int16

func (*Result) Int32 

func (r *Result) Int32() (int32, error)

Int32 assert the result to int32

func (*Result) Int32Slice 

func (r *Result) Int32Slice() ([]int32, error)

Int32Slice assert the result to []int32

func (*Result) Int64 

func (r *Result) Int64() (int64, error)

Int64 assert the result to int64

func (*Result) Int64Slice 

func (r *Result) Int64Slice() ([]int64, error)

Int64Slice assert the result to []int64

func (*Result) Int8 

func (r *Result) Int8() (int8, error)

Int8 assert the result to int8

func (*Result) Int8Slice 

func (r *Result) Int8Slice() ([]int8, error)

Int8Slice assert the result to []int8

func (*Result) IntSlice 

func (r *Result) IntSlice() ([]int, error)

IntSlice assert the result to []int

func (*Result) Nil 

func (r *Result) Nil() bool

Nil check the query has result or not

func (*Result) String 

func (r *Result) String() (string, error)

String assert the result to String

func (*Result) StringSlice 

func (r *Result) StringSlice() ([]string, error)

StringSlice assert the result to []string

func (*Result) Time 

func (r *Result) Time(layout string) (time.Time, error)

Time assert the result to time.Time

func (*Result) TimeSlice 

func (r *Result) TimeSlice(layout string) ([]time.Time, error)

TimeSlice assert the result to []time.Time

func (*Result) Uint 

func (r *Result) Uint() (uint, error)

Uint assert the result to uint

func (*Result) Uint16 

func (r *Result) Uint16() (uint16, error)

Uint16 assert the result to uint16

func (*Result) Uint16Slice 

func (r *Result) Uint16Slice() ([]uint16, error)

Uint16Slice assert the result to []uint16

func (*Result) Uint32 

func (r *Result) Uint32() (uint32, error)

Uint32 assert the result to uint32

func (*Result) Uint32Slice 

func (r *Result) Uint32Slice() ([]uint32, error)

Uint32Slice assert the result to []uint32

func (*Result) Uint64 

func (r *Result) Uint64() (uint64, error)

Uint64 assert the result to uint64

func (*Result) Uint64Slice 

func (r *Result) Uint64Slice() ([]uint64, error)

Uint64Slice assert the result to []uint64

func (*Result) Uint8 

func (r *Result) Uint8() (uint8, error)

Uint8 assert the result to uint8

func (*Result) Uint8Slice 

func (r *Result) Uint8Slice() ([]uint8, error)

Uint8Slice assert the result to []uint8

func (*Result) UintSlice 

func (r *Result) UintSlice() ([]uint, error)

UintSlice assert the result to []uint

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.