Console tool for highlighted formatting and struct query fetching JSON

Console JSON formatter with query feature.

Install:

```$ go get github.com/miolini/jsonf```

Usage:

```
Usage of jsonf:
  -c=true: colorize output
  -d=false: debug output to stderr
  -f=true: format output json to stdout
  -q="": json query
  -s=true: syntax hightlight
  -v=false: verbose output to stderr
```

Examples:

```
$ echo '{"uid":1,"email":"user@gmail.com","address":{"city":"New-York","country":"US"}}' | jsonf
```
 
![Output](https://cdn.rawgit.com/miolini/jsonf/master/output.png "Output")

 
```
$ echo '{"uid":1,"email":"user@gmail.com","address":{"city":"New-York","country":"US"}}' \
  | jsonf -q 'value["address"]["country"]'
```

```
"US"
```

## Using from another Golang program

```go
import (
  ...
  "github.com/miolini/jsonf/jsonflib"
  ...
)
...
    jsonRaw, err := jsonflib.Highlight(
      jsonRaw,
      jsonflib.HighlightFlags{Colorize: true, Verbose: false, Debug: false},
    )
    if err != nil {
      return err
    }
```


jsonf

Abstract JSON for golang with JSONPath support

# Abstract JSON 

[![Build](https://github.com/spyzhov/ajson/actions/workflows/main.yml/badge.svg)](https://github.com/spyzhov/ajson/actions/workflows/main.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/spyzhov/ajson)](https://goreportcard.com/report/github.com/spyzhov/ajson)
[![GoDoc](https://godoc.org/github.com/spyzhov/ajson?status.svg)](https://godoc.org/github.com/spyzhov/ajson)
[![codecov](https://codecov.io/gh/spyzhov/ajson/branch/master/graph/badge.svg)](https://codecov.io/gh/spyzhov/ajson)
[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/avelino/awesome-go#json)

Abstract [JSON](https://www.json.org/) is a small golang package provides a parser for JSON with support of JSONPath, in case when you are not sure in its structure.

Method `Unmarshal` will scan all the byte slice to create a root node of JSON structure, with all its behaviors.

Method `Marshal` will serialize current `Node` object to JSON structure.

Each `Node` has its own type and calculated value, which will be calculated on demand. 
Calculated value saves in `atomic.Value`, so it's thread safe.

Method `JSONPath` will returns slice of found elements in current JSON data, by [JSONPath](http://goessner.net/articles/JsonPath/) request.

## Compare with other solutions

Check the [cburgmer/json-path-comparison](https://cburgmer.github.io/json-path-comparison/) project.

# Usage

[Playground](https://play.golang.com/p/iIxkktxN0SK)

```go
package main

import (
	"fmt"
	"github.com/spyzhov/ajson"
)

func main() {
	json := []byte(`...`)

	root, _ := ajson.Unmarshal(json)
	nodes, _ := root.JSONPath("$..price")
	for _, node := range nodes {
		node.SetNumeric(node.MustNumeric() * 1.25)
		node.Parent().AppendObject("currency", ajson.StringNode("", "EUR"))
	}
	result, _ := ajson.Marshal(root)

	fmt.Printf("%s", result)
}
```

# Console application

You can download `ajson` cli from the [release page](https://github.com/spyzhov/ajson/releases), or install from the source:

```shell script
go get github.com/spyzhov/ajson/cmd/ajson@v0.9.6
```

Usage:

```
Usage: ajson [-mq] "jsonpath" ["input"]
  Read JSON and evaluate it with JSONPath.
Parameters:
  -m, --multiline  Input file/stream will be read as a multiline JSON. Each line should have a full valid JSON.
  -q, --quiet      Do not print errors into the STDERR.
Argument:
  jsonpath         Valid JSONPath or evaluate string (Examples: "$..[?(@.price)]", "$..price", "avg($..price)")
  input            Path to the JSON file. Leave it blank to use STDIN.
```

Examples:

```shell script
  ajson "avg($..registered.age)" "https://randomuser.me/api/?results=5000"
  ajson "$.results.*.name" "https://randomuser.me/api/?results=10"
  curl -s "https://randomuser.me/api/?results=10" | ajson "$..coordinates"
  ajson "$" example.json
  echo "3" | ajson "2 * pi * $"
  docker logs image-name -f | ajson -qm 'root($[?(@=="ERROR" && key(@)=="severity")])'
```

# JSONPath

Current package supports JSONPath selection described at [http://goessner.net/articles/JsonPath/](http://goessner.net/articles/JsonPath/).

JSONPath expressions always refer to a JSON structure in the same way as XPath expression are used in combination with an XML document. 
Since a JSON structure is usually anonymous and doesn't necessarily have a "root member object" JSONPath assumes the abstract name $ assigned to the outer level object.

JSONPath expressions can use the dot–notation

`$.store.book[0].title`

or the bracket–notation

`$['store']['book'][0]['title']`

for input paths. Internal or output paths will always be converted to the more general bracket–notation.

JSONPath allows the wildcard symbol `*` for member names and array indices. 
It borrows the descendant operator `..` from E4X and the array slice syntax proposal `[start:end:step]` from ECMASCRIPT 4.

Expressions of the underlying scripting language `(<expr>)` can be used as an alternative to explicit names or indices as in

`$.store.book[(@.length-1)].title`

using the symbol `@` for the current object. Filter expressions are supported via the syntax `?(<boolean expr>)` as in

`$.store.book[?(@.price < 10)].title`

Here is a complete overview and a side by side comparison of the JSONPath syntax elements with its XPath counterparts.

| JSONPath | Description |
|----------|---|
| `$`      | the root object/element |
| `@`      | the current object/element |
| `.` or `[]` | child operator |
| `..`     | recursive descent. JSONPath borrows this syntax from E4X. |
| `*`      | wildcard. All objects/elements regardless their names. |
| `[]`     | subscript operator. XPath uses it to iterate over element collections and for predicates. In Javascript and JSON it is the native array operator. |
| `[,]`    | Union operator in XPath results in a combination of node sets. JSONPath allows alternate names or array indices as a set. |
| `[start:end:step]` | array slice operator borrowed from ES4. |
| `?()`    | applies a filter (script) expression. |
| `()`     | script expression, using the underlying script engine. |

## Script engine

### Predefined constant

Package has several predefined constants. 

     e       math.E     float64
     pi      math.Pi    float64
     phi     math.Phi   float64
     
     sqrt2     math.Sqrt2   float64
     sqrte     math.SqrtE   float64
     sqrtpi    math.SqrtPi  float64
     sqrtphi   math.SqrtPhi float64
     
     ln2     math.Ln2    float64
     log2e   math.Log2E  float64
     ln10    math.Ln10   float64
     log10e  math.Log10E float64
          
     true    true       bool
     false   false      bool
     null    nil        interface{}
     
You are free to add new one with function `AddConstant`:

```go
    AddConstant("c", NumericNode("speed of light in vacuum", 299_792_458))
```

#### Examples

<details>
<summary>Using `true` in path</summary>

[Playground](https://play.golang.org/p/h0oFLaE11Tn)

```go
package main

import (
	"fmt"
	
	"github.com/spyzhov/ajson"
)

func main() {
	json := []byte(`{"foo": [true, null, false, 1, "bar", true, 1e3], "bar": [true, "baz", false]}`)
	result, _ := ajson.JSONPath(json, `$..[?(@ == true)]`)
	fmt.Printf("Count of `true` values: %d", len(result))
}
```
Output:
```
Count of `true` values: 3
```
</details>
<details>
<summary>Using `null` in eval</summary>

[Playground](https://play.golang.org/p/wpqh1Fw5vWE)

```go
package main

import (
	"fmt"
	
	"github.com/spyzhov/ajson"
)

func main() {
	json := []byte(`{"foo": [true, null, false, 1, "bar", true, 1e3], "bar": [true, "baz", false]}`)
	result, _ := ajson.JSONPath(json, `$..[?(@ == true)]`)
	fmt.Printf("Count of `true` values: %d", len(result))
}
```
Output:
```
Count of `true` values: 3
```
</details>

### Supported operations

Package has several predefined operators.

[Operator precedence](https://golang.org/ref/spec#Operator_precedence)

	Precedence    Operator
	    6	    	  **
	    5             *  /  %  <<  >>  &  &^
	    4             +  -  |  ^
	    3             ==  !=  <  <=  >  >= =~
	    2             &&
	    1             ||

[Arithmetic operators](https://golang.org/ref/spec#Arithmetic_operators)

	**   power                  integers, floats
	+    sum                    integers, floats, strings
	-    difference             integers, floats
	*    product                integers, floats
	/    quotient               integers, floats
	%    remainder              integers

	&    bitwise AND            integers
	|    bitwise OR             integers
	^    bitwise XOR            integers
	&^   bit clear (AND NOT)    integers

	<<   left shift             integer << unsigned integer
	>>   right shift            integer >> unsigned integer

	==  equals                  any
	!=  not equals              any
	<   less                    any
	<=  less or equals          any
	>   larger                  any
	>=  larger or equals        any
	=~  equals regex string     strings

You are free to add new one with function `AddOperation`:

```go
	AddOperation("<>", 3, false, func(left *ajson.Node, right *ajson.Node) (node *ajson.Node, err error) {
		result, err := left.Eq(right)
		if err != nil {
			return nil, err
		}
		return BoolNode("neq", !result), nil
	})
```

#### Examples

<details>
<summary>Using `regex` operator</summary>

[Playground](https://play.golang.org/p/Lm_F4OGTMWl)

```go
package main

import (
	"fmt"
	
	"github.com/spyzhov/ajson"
)

func main() {
	json := []byte(`[{"name":"Foo","mail":"foo@example.com"},{"name":"bar","mail":"bar@example.org"}]`)
	result, err := ajson.JSONPath(json, `$.[?(@.mail =~ '.+@example\\.com')]`)
	if err != nil {
		panic(err)
	}
	fmt.Printf("JSON: %s", result[0].Source())
	// Output:
	// JSON: {"name":"Foo","mail":"foo@example.com"}
}

```
Output:
```
JSON: {"name":"Foo","mail":"foo@example.com"}
```
</details>

### Supported functions

Package has several predefined functions.

    abs          math.Abs           integers, floats
    acos         math.Acos          integers, floats
    acosh        math.Acosh         integers, floats
    asin         math.Asin          integers, floats
    asinh        math.Asinh         integers, floats
    atan         math.Atan          integers, floats
    atanh        math.Atanh         integers, floats
    avg          Average            array of integers or floats
    b64decode    b64 Decoding       string
    b64encode    b64 Encoding       string 
    b64encoden   b64 Encoding (no padding)    string
    cbrt         math.Cbrt          integers, floats
    ceil         math.Ceil          integers, floats
    cos          math.Cos           integers, floats
    cosh         math.Cosh          integers, floats
    erf          math.Erf           integers, floats
    erfc         math.Erfc          integers, floats
    erfcinv      math.Erfcinv       integers, floats
    erfinv       math.Erfinv        integers, floats
    exp          math.Exp           integers, floats
    exp2         math.Exp2          integers, floats
    expm1        math.Expm1         integers, floats
    factorial    N!                 unsigned integer
    first        Get first element  any
    floor        math.Floor         integers, floats
    gamma        math.Gamma         integers, floats
    is_array     Is type Array      any
    is_bool      Is type Bool       any
    is_float     Is type Float      any
    is_int       Is type Int        any
    is_null      Is type Null       any
    is_numeric   Is type Numeric    any
    is_object    Is type Object     any
    is_string    Is type String     any
    is_uint      Is type Uint       any
    j0           math.J0            integers, floats
    j1           math.J1            integers, floats
    key          Key of element     string
    last         Get last element   any
    length       Length of array    array, string
    log          math.Log           integers, floats
    log10        math.Log10         integers, floats
    log1p        math.Log1p         integers, floats
    log2         math.Log2          integers, floats
    logb         math.Logb          integers, floats
    not          not                any
    parent       Get parent element any
    pow10        math.Pow10         integer
    rand         N*rand.Float64     float
    randint      rand.Intn          integer
    root         Get root element   any
    round        math.Round         integers, floats
    roundtoeven  math.RoundToEven   integers, floats
    sin          math.Sin           integers, floats
    sinh         math.Sinh          integers, floats
    size         Count of elements  array, object
    sum          Sum                array of integers or floats
    sqrt         math.Sqrt          integers, floats
    tan          math.Tan           integers, floats
    tanh         math.Tanh          integers, floats
    trunc        math.Trunc         integers, floats
    y0           math.Y0            integers, floats
    y1           math.Y1            integers, floats

You are free to add new one with function `AddFunction`:

```go
	AddFunction("trim", func(node *ajson.Node) (result *Node, err error) {
		if node.IsString() {
			return StringNode("trim", strings.TrimSpace(node.MustString())), nil
		}
		return
	})
```

#### Examples

<details>
<summary>Using `avg` for array</summary>

[Playground](https://play.golang.org/p/cM66hTE-CX1)

```go
package main

import (
	"fmt"
	
	"github.com/spyzhov/ajson"
)

func main() {
	json := []byte(`{"prices": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]}`)
	root, err := ajson.Unmarshal(json)
	if err != nil {
		panic(err)
	}
	result, err := ajson.Eval(root, `avg($.prices)`)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Avg price: %0.1f", result.MustNumeric())
	// Output:
	// Avg price: 5.5
}
```
Output:
```
Avg price: 5.5
```
</details>

# Examples

Calculating `AVG(price)` when object is heterogeneous.

```json
{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      {
        "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
      {
        "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      },
      {
        "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    },
    "tools": null
  }
}
```

## Unmarshal

[Playground](https://play.golang.org/p/xny93dzjZCK)
```go
package main

import (
	"fmt"
	"github.com/spyzhov/ajson"
)

func main() {
	data := []byte(`{"store": {"book": [
{"category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95}, 
{"category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99}, 
{"category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99}, 
{"category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99}], 
"bicycle": {"color": "red", "price": 19.95}, "tools": null}}`)

	root, err := ajson.Unmarshal(data)
	if err != nil {
		panic(err)
	}

	store := root.MustKey("store").MustObject()

	var prices float64
	size := 0
	for _, objects := range store {
		if objects.IsArray() && objects.Size() > 0 {
			size += objects.Size()
			for _, object := range objects.MustArray() {
				prices += object.MustKey("price").MustNumeric()
			}
		} else if objects.IsObject() && objects.HasKey("price") {
			size++
			prices += objects.MustKey("price").MustNumeric()
		}
	}

	if size > 0 {
		fmt.Println("AVG price:", prices/float64(size))
	} else {
		fmt.Println("AVG price:", 0)
	}
}
```

## JSONPath:

[Playground](https://play.golang.org/p/7twZHOd6dbT)
```go
package main

import (
	"fmt"
	"github.com/spyzhov/ajson"
)

func main() {
	data := []byte(`{"store": {"book": [
{"category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95}, 
{"category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99}, 
{"category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99}, 
{"category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99}], 
"bicycle": {"color": "red", "price": 19.95}, "tools": null}}`)

	nodes, err := ajson.JSONPath(data, "$..price")
	if err != nil {
		panic(err)
	}

	var prices float64
	size := len(nodes)
	for _, node := range nodes {
		prices += node.MustNumeric()
	}

	if size > 0 {
		fmt.Println("AVG price:", prices/float64(size))
	} else {
		fmt.Println("AVG price:", 0)
	}
}
```

## Eval

[Playground](https://play.golang.org/p/lTXnlRU3sgR)
```go
package main

import (
	"fmt"
	"github.com/spyzhov/ajson"
)

func main() {
	json := []byte(`{"store": {"book": [
{"category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95}, 
{"category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99}, 
{"category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99}, 
{"category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99}], 
"bicycle": {"color": "red", "price": 19.95}, "tools": null}}`)
	root, err := ajson.Unmarshal(json)
	if err != nil {
		panic(err)
	}
	result, err := ajson.Eval(root, "avg($..price)")
	if err != nil {
		panic(err)
	}
	fmt.Println("AVG price:", result.MustNumeric())
}
```

## Marshal

[Playground](https://play.golang.org/p/i4gXXcA2VLU)
```go
package main

import (
	"fmt"
	"github.com/spyzhov/ajson"
)

func main() {
	json := []byte(`{"store": {"book": [
{"category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95}, 
{"category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99}, 
{"category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99}, 
{"category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99}], 
"bicycle": {"color": "red", "price": 19.95}, "tools": null}}`)
	root := ajson.Must(ajson.Unmarshal(json))
	result := ajson.Must(ajson.Eval(root, "avg($..price)"))
	err := root.AppendObject("price(avg)", result)
	if err != nil {
		panic(err)
	}
	marshalled, err := ajson.Marshal(root)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%s", marshalled)
}
```

# Benchmarks

Current package is comparable with `encoding/json` package. 

Test data:
```json
{ "store": {
    "book": [ 
      { "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      },
      { "category": "fiction",
        "author": "Evelyn Waugh",
        "title": "Sword of Honour",
        "price": 12.99
      },
      { "category": "fiction",
        "author": "Herman Melville",
        "title": "Moby Dick",
        "isbn": "0-553-21311-3",
        "price": 8.99
      },
      { "category": "fiction",
        "author": "J. R. R. Tolkien",
        "title": "The Lord of the Rings",
        "isbn": "0-395-19395-8",
        "price": 22.99
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    }
  }
}
```
JSONPath: `$.store..price`

```
$ go test -bench=. -cpu=1 -benchmem
goos: linux
goarch: amd64
pkg: github.com/spyzhov/ajson
BenchmarkUnmarshal_AJSON          121656             10060 ns/op            5712 B/op        118 allocs/op
BenchmarkUnmarshal_JSON           102674             11381 ns/op             960 B/op         32 allocs/op
BenchmarkJSONPath_all_prices       63314             16385 ns/op            7496 B/op        178 allocs/op
```

# License

MIT licensed. See the [LICENSE](LICENSE) file for details.


ajson

Easy access to nested values in maps and slices. Works in combination with encoding/json and other packages that "Unmarshal" arbitrary data into Go data-types

<p align="center">
<img src="logo.svg" height="100" border="0" alt="ASK">
<br/>
<a href="https://pkg.go.dev/github.com/simonnilsson/ask"><img src="https://pkg.go.dev/badge/github.com/simonnilsson/ask" alt="PkgGoDev" /></a>
<a href="https://goreportcard.com/report/github.com/simonnilsson/ask"><img src="https://goreportcard.com/badge/github.com/simonnilsson/ask" alt="Go Report Card" /></a>
<a href="https://raw.githack.com/wiki/simonnilsson/ask/coverage.html"><img src="https://github.com/simonnilsson/ask/wiki/coverage.svg" alt="Go Coverage" /></a>
<a href="https://github.com/avelino/awesome-go#json"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Go" /></a>  
<br/>
and you shall receive.
</p>
Ask provides a simple way of accessing nested properties in maps and slices. Works great in combination with encoding/json and other packages that "Unmarshal" arbitrary data into Go data-types. Inspired by the get function in the lodash javascript library.
<br/><br/>

:warning: From version `v0.3.0`, the package requires [Go 1.17+](https://golang.org/doc/install), due to the usage of new additions to the reflect package.

## Use

```go
package main

import "json"
import "github.com/simonnilsson/ask"

func main() {

	// Use parsed JSON as source data
	var object map[string]interface{}
	json.Unmarshal([]byte(`{ "a": [{ "b": { "c": 3 } }] }`), &object)

	// Extract the 3
	res, ok := ask.For(object, "a[0].b.c").Int(0)

	fmt.Println(res, ok)
	// Output: 3 true

	// Attempt extracting a string at path .d that does not exist
	res2, ok := ask.ForArgs(object, "a", 0, "b", "d").String("nothing")

	fmt.Println(res2, ok)
	// Output: nothing false

}
```

## API

Internally ask uses type assertions to traverse down the path supplied. Each invocation starts by calling For() with your data structure **source** and the **path** in this structure to extract. You can also use ForArgs() if want to supply each part of the path as a seperate argument, this can be usefull if your field names contain dots for example. The same accessors used in For can be used in ForArgs, but ForArgs can also take integers for slice indexes.

```go
For(source interface{}, path string) *Answer
ForArgs(source interface{}, parts ...interface{}) *Answer
```
Additional paths can be traversed by calling Path()/PathArgs() on the resulting answer.
```go
(a *Answer) Path(path string) *Answer
(a *Answer) PathArgs(parts ...interface{}) *Answer
```


### Type assertion

After receiving an `*Answer` from a call to For() it can be asserted to a type. The methods for this is seen below. Each function takes a default value as a parameter that will be returned in case the value can not be asserted from the answer. A second return value is used to indicate if the assertion was successful.

```go
(a *Answer) String(d string) (string, bool)
(a *Answer) Bool(d bool) (bool, bool)
(a *Answer) Int(d int64) (int64, bool)
(a *Answer) Uint(d uint64) (uint64, bool)
(a *Answer) Float(d float64) (float64, bool)
(a *Answer) Slice(d []interface{}) ([]interface{}, bool)
(a *Answer) Map(d map[string]interface{}) (map[string]interface{}, bool)
```

If a number is found but it is of different type than requested it will be casted to desired type and return success. If the value would not fit within the valid range of requested type the operation will fail however and the default parameter will be returned instead.

Two additional methods are available, one to check if the answer has a value (not nil) and one to return the raw value as a interface{}.

```go
(a *Answer) Exists() bool
(a *Answer) Value() interface{}
```

For full documentation see [pkg.go.dev](https://pkg.go.dev/github.com/simonnilsson/ask).

## License

[MIT](LICENSE)


Fast JSON parser and validator for Go. No custom structs, no code generation, no reflection

[![Build Status](https://travis-ci.org/valyala/fastjson.svg)](https://travis-ci.org/valyala/fastjson)
[![GoDoc](https://godoc.org/github.com/valyala/fastjson?status.svg)](http://godoc.org/github.com/valyala/fastjson)
[![Go Report](https://goreportcard.com/badge/github.com/valyala/fastjson)](https://goreportcard.com/report/github.com/valyala/fastjson)
[![codecov](https://codecov.io/gh/valyala/fastjson/branch/master/graph/badge.svg)](https://codecov.io/gh/valyala/fastjson)

# fastjson - fast JSON parser and validator for Go


## Features

  * Fast. As usual, up to 15x faster than the standard [encoding/json](https://golang.org/pkg/encoding/json/).
    See [benchmarks](#benchmarks).
  * Parses arbitrary JSON without schema, reflection, struct magic and code generation
    contrary to [easyjson](https://github.com/mailru/easyjson).
  * Provides simple [API](http://godoc.org/github.com/valyala/fastjson).
  * Outperforms [jsonparser](https://github.com/buger/jsonparser) and [gjson](https://github.com/tidwall/gjson)
    when accessing multiple unrelated fields, since `fastjson` parses the input JSON only once.
  * Validates the parsed JSON unlike [jsonparser](https://github.com/buger/jsonparser)
    and [gjson](https://github.com/tidwall/gjson).
  * May quickly extract a part of the original JSON with `Value.Get(...).MarshalTo` and modify it
    with [Del](https://godoc.org/github.com/valyala/fastjson#Value.Del)
    and [Set](https://godoc.org/github.com/valyala/fastjson#Value.Set) functions.
  * May parse array containing values with distinct types (aka non-homogenous types).
    For instance, `fastjson` easily parses the following JSON array `[123, "foo", [456], {"k": "v"}, null]`.
  * `fastjson` preserves the original order of object items when calling
    [Object.Visit](https://godoc.org/github.com/valyala/fastjson#Object.Visit).


## Known limitations

  * Requies extra care to work with - references to certain objects recursively
    returned by [Parser](https://godoc.org/github.com/valyala/fastjson#Parser)
    must be released before the next call to [Parse](https://godoc.org/github.com/valyala/fastjson#Parser.Parse).
    Otherwise the program may work improperly. The same applies to objects returned by [Arena](https://godoc.org/github.com/valyala/fastjson#Arena).
    Adhere recommendations from [docs](https://godoc.org/github.com/valyala/fastjson).
  * Cannot parse JSON from `io.Reader`. There is [Scanner](https://godoc.org/github.com/valyala/fastjson#Scanner)
    for parsing stream of JSON values from a string.


## Usage

One-liner accessing a single field:
```go
	s := []byte(`{"foo": [123, "bar"]}`)
	fmt.Printf("foo.0=%d\n", fastjson.GetInt(s, "foo", "0"))

	// Output:
	// foo.0=123
```

Accessing multiple fields with error handling:
```go
        var p fastjson.Parser
        v, err := p.Parse(`{
                "str": "bar",
                "int": 123,
                "float": 1.23,
                "bool": true,
                "arr": [1, "foo", {}]
        }`)
        if err != nil {
                log.Fatal(err)
        }
        fmt.Printf("foo=%s\n", v.GetStringBytes("str"))
        fmt.Printf("int=%d\n", v.GetInt("int"))
        fmt.Printf("float=%f\n", v.GetFloat64("float"))
        fmt.Printf("bool=%v\n", v.GetBool("bool"))
        fmt.Printf("arr.1=%s\n", v.GetStringBytes("arr", "1"))

        // Output:
        // foo=bar
        // int=123
        // float=1.230000
        // bool=true
        // arr.1=foo
```

See also [examples](https://godoc.org/github.com/valyala/fastjson#pkg-examples).


## Security

  * `fastjson` shouldn't crash or panic when parsing input strings specially crafted
    by an attacker. It must return error on invalid input JSON.
  * `fastjson` requires up to `sizeof(Value) * len(inputJSON)` bytes of memory
    for parsing `inputJSON` string. Limit the maximum size of the `inputJSON`
    before parsing it in order to limit the maximum memory usage.


## Performance optimization tips

  * Re-use [Parser](https://godoc.org/github.com/valyala/fastjson#Parser) and [Scanner](https://godoc.org/github.com/valyala/fastjson#Scanner)
    for parsing many JSONs. This reduces memory allocations overhead.
    [ParserPool](https://godoc.org/github.com/valyala/fastjson#ParserPool) may be useful in this case.
  * Prefer calling `Value.Get*` on the value returned from [Parser](https://godoc.org/github.com/valyala/fastjson#Parser)
    instead of calling `Get*` one-liners when multiple fields
    must be obtained from JSON, since each `Get*` one-liner re-parses
    the input JSON again.
  * Prefer calling once [Value.Get](https://godoc.org/github.com/valyala/fastjson#Value.Get)
    for common prefix paths and then calling `Value.Get*` on the returned value
    for distinct suffix paths.
  * Prefer iterating over array returned from [Value.GetArray](https://godoc.org/github.com/valyala/fastjson#Object.Visit)
    with a range loop instead of calling `Value.Get*` for each array item.

## Fuzzing
Install [go-fuzz](https://github.com/dvyukov/go-fuzz) & optionally the go-fuzz-corpus.

```bash
go get -u github.com/dvyukov/go-fuzz/go-fuzz github.com/dvyukov/go-fuzz/go-fuzz-build
```

Build using `go-fuzz-build` and run `go-fuzz` with an optional corpus.

```bash
mkdir -p workdir/corpus
cp $GOPATH/src/github.com/dvyukov/go-fuzz-corpus/json/corpus/* workdir/corpus
go-fuzz-build github.com/valyala/fastjson
go-fuzz -bin=fastjson-fuzz.zip -workdir=workdir
```

## Benchmarks

Go 1.12 has been used for benchmarking.

Legend:

  * `small` - parse [small.json](testdata/small.json) (190 bytes).
  * `medium` - parse [medium.json](testdata/medium.json) (2.3KB).
  * `large` - parse [large.json](testdata/large.json) (28KB).
  * `canada` - parse [canada.json](testdata/canada.json) (2.2MB).
  * `citm` - parse [citm_catalog.json](testdata/citm_catalog.json) (1.7MB).
  * `twitter` - parse [twitter.json](testdata/twitter.json) (617KB).

  * `stdjson-map` - parse into a `map[string]interface{}` using `encoding/json`.
  * `stdjson-struct` - parse into a struct containing
    a subset of fields of the parsed JSON, using `encoding/json`.
  * `stdjson-empty-struct` - parse into an empty struct using `encoding/json`.
    This is the fastest possible solution for `encoding/json`, may be used
    for json validation. See also benchmark results for json validation.
  * `fastjson` - parse using `fastjson` without fields access.
  * `fastjson-get` - parse using `fastjson` with fields access similar to `stdjson-struct`.

```
$ GOMAXPROCS=1 go test github.com/valyala/fastjson -bench='Parse$'
goos: linux
goarch: amd64
pkg: github.com/valyala/fastjson
BenchmarkParse/small/stdjson-map         	  200000	      7305 ns/op	  26.01 MB/s	     960 B/op	      51 allocs/op
BenchmarkParse/small/stdjson-struct      	  500000	      3431 ns/op	  55.37 MB/s	     224 B/op	       4 allocs/op
BenchmarkParse/small/stdjson-empty-struct         	  500000	      2273 ns/op	  83.58 MB/s	     168 B/op	       2 allocs/op
BenchmarkParse/small/fastjson                     	 5000000	       347 ns/op	 547.53 MB/s	       0 B/op	       0 allocs/op
BenchmarkParse/small/fastjson-get                 	 2000000	       620 ns/op	 306.39 MB/s	       0 B/op	       0 allocs/op
BenchmarkParse/medium/stdjson-map                 	   30000	     40672 ns/op	  57.26 MB/s	   10196 B/op	     208 allocs/op
BenchmarkParse/medium/stdjson-struct              	   30000	     47792 ns/op	  48.73 MB/s	    9174 B/op	     258 allocs/op
BenchmarkParse/medium/stdjson-empty-struct        	  100000	     22096 ns/op	 105.40 MB/s	     280 B/op	       5 allocs/op
BenchmarkParse/medium/fastjson                    	  500000	      3025 ns/op	 769.90 MB/s	       0 B/op	       0 allocs/op
BenchmarkParse/medium/fastjson-get                	  500000	      3211 ns/op	 725.20 MB/s	       0 B/op	       0 allocs/op
BenchmarkParse/large/stdjson-map                  	    2000	    614079 ns/op	  45.79 MB/s	  210734 B/op	    2785 allocs/op
BenchmarkParse/large/stdjson-struct               	    5000	    298554 ns/op	  94.18 MB/s	   15616 B/op	     353 allocs/op
BenchmarkParse/large/stdjson-empty-struct         	    5000	    268577 ns/op	 104.69 MB/s	     280 B/op	       5 allocs/op
BenchmarkParse/large/fastjson                     	   50000	     35210 ns/op	 798.56 MB/s	       5 B/op	       0 allocs/op
BenchmarkParse/large/fastjson-get                 	   50000	     35171 ns/op	 799.46 MB/s	       5 B/op	       0 allocs/op
BenchmarkParse/canada/stdjson-map                 	      20	  68147307 ns/op	  33.03 MB/s	12260502 B/op	  392539 allocs/op
BenchmarkParse/canada/stdjson-struct              	      20	  68044518 ns/op	  33.08 MB/s	12260123 B/op	  392534 allocs/op
BenchmarkParse/canada/stdjson-empty-struct        	     100	  17709250 ns/op	 127.11 MB/s	     280 B/op	       5 allocs/op
BenchmarkParse/canada/fastjson                    	     300	   4182404 ns/op	 538.22 MB/s	  254902 B/op	     381 allocs/op
BenchmarkParse/canada/fastjson-get                	     300	   4274744 ns/op	 526.60 MB/s	  254902 B/op	     381 allocs/op
BenchmarkParse/citm/stdjson-map                   	      50	  27772612 ns/op	  62.19 MB/s	 5214163 B/op	   95402 allocs/op
BenchmarkParse/citm/stdjson-struct                	     100	  14936191 ns/op	 115.64 MB/s	    1989 B/op	      75 allocs/op
BenchmarkParse/citm/stdjson-empty-struct          	     100	  14946034 ns/op	 115.56 MB/s	     280 B/op	       5 allocs/op
BenchmarkParse/citm/fastjson                      	    1000	   1879714 ns/op	 918.87 MB/s	   17628 B/op	      30 allocs/op
BenchmarkParse/citm/fastjson-get                  	    1000	   1881598 ns/op	 917.94 MB/s	   17628 B/op	      30 allocs/op
BenchmarkParse/twitter/stdjson-map                	     100	  11289146 ns/op	  55.94 MB/s	 2187878 B/op	   31266 allocs/op
BenchmarkParse/twitter/stdjson-struct             	     300	   5779442 ns/op	 109.27 MB/s	     408 B/op	       6 allocs/op
BenchmarkParse/twitter/stdjson-empty-struct       	     300	   5738504 ns/op	 110.05 MB/s	     408 B/op	       6 allocs/op
BenchmarkParse/twitter/fastjson                   	    2000	    774042 ns/op	 815.86 MB/s	    2541 B/op	       2 allocs/op
BenchmarkParse/twitter/fastjson-get               	    2000	    777833 ns/op	 811.89 MB/s	    2541 B/op	       2 allocs/op
```

Benchmark results for json validation:

```
$ GOMAXPROCS=1 go test github.com/valyala/fastjson -bench='Validate$'
goos: linux
goarch: amd64
pkg: github.com/valyala/fastjson
BenchmarkValidate/small/stdjson 	 2000000	       955 ns/op	 198.83 MB/s	      72 B/op	       2 allocs/op
BenchmarkValidate/small/fastjson         	 5000000	       384 ns/op	 493.60 MB/s	       0 B/op	       0 allocs/op
BenchmarkValidate/medium/stdjson         	  200000	     10799 ns/op	 215.66 MB/s	     184 B/op	       5 allocs/op
BenchmarkValidate/medium/fastjson        	  300000	      3809 ns/op	 611.30 MB/s	       0 B/op	       0 allocs/op
BenchmarkValidate/large/stdjson          	   10000	    133064 ns/op	 211.31 MB/s	     184 B/op	       5 allocs/op
BenchmarkValidate/large/fastjson         	   30000	     45268 ns/op	 621.14 MB/s	       0 B/op	       0 allocs/op
BenchmarkValidate/canada/stdjson         	     200	   8470904 ns/op	 265.74 MB/s	     184 B/op	       5 allocs/op
BenchmarkValidate/canada/fastjson        	     500	   2973377 ns/op	 757.07 MB/s	       0 B/op	       0 allocs/op
BenchmarkValidate/citm/stdjson           	     200	   7273172 ns/op	 237.48 MB/s	     184 B/op	       5 allocs/op
BenchmarkValidate/citm/fastjson          	    1000	   1684430 ns/op	1025.39 MB/s	       0 B/op	       0 allocs/op
BenchmarkValidate/twitter/stdjson        	     500	   2849439 ns/op	 221.63 MB/s	     312 B/op	       6 allocs/op
BenchmarkValidate/twitter/fastjson       	    2000	   1036796 ns/op	 609.10 MB/s	       0 B/op	       0 allocs/op
```

## FAQ

  * Q: _There are a ton of other high-perf packages for JSON parsing in Go. Why creating yet another package?_
    A: Because other packages require either rigid JSON schema via struct magic
       and code generation or perform poorly when multiple unrelated fields
       must be obtained from the parsed JSON.
       Additionally, `fastjson` provides nicer [API](http://godoc.org/github.com/valyala/fastjson).

  * Q: _What is the main purpose for `fastjson`?_
    A: High-perf JSON parsing for [RTB](https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf)
       and other [JSON-RPC](https://en.wikipedia.org/wiki/JSON-RPC) services.

  * Q: _Why fastjson doesn't provide fast marshaling (serialization)?_
    A: Actually it provides some sort of marshaling - see [Value.MarshalTo](https://godoc.org/github.com/valyala/fastjson#Value.MarshalTo).
       But I'd recommend using [quicktemplate](https://github.com/valyala/quicktemplate#use-cases)
       for high-performance JSON marshaling :)

  * Q: _`fastjson` crashes my program!_
    A: There is high probability of improper use.
       * Make sure you don't hold references to objects recursively returned by `Parser` / `Scanner`
         beyond the next `Parser.Parse` / `Scanner.Next` call
         if such restriction is mentioned in [docs](https://github.com/valyala/fastjson/issues/new).
       * Make sure you don't access `fastjson` objects from concurrently running goroutines
         if such restriction is mentioned in [docs](https://github.com/valyala/fastjson/issues/new).
       * Build and run your program with [-race](https://golang.org/doc/articles/race_detector.html) flag.
         Make sure the race detector detects zero races.
       * If your program continue crashing after fixing issues mentioned above, [file a bug](https://github.com/valyala/fastjson/issues/new).


fastjson

Go package for handling common HTTP JSON responses

# go-respond

A Go package for handling common HTTP JSON responses.

[![GoDoc](https://godoc.org/github.com/nicklaw5/go-respond?status.svg)](https://godoc.org/github.com/nicklaw5/go-respond)
[![Build Status](https://travis-ci.org/nicklaw5/go-respond.svg?branch=master)](https://travis-ci.org/nicklaw5/go-respond)
[![Coverage Status](https://coveralls.io/repos/github/nicklaw5/go-respond/badge.svg)](https://coveralls.io/github/nicklaw5/go-respond)
[![Go Report Card](https://goreportcard.com/badge/github.com/nicklaw5/go-respond)](https://goreportcard.com/report/github.com/nicklaw5/go-respond)

## Installation

```bash
go get github.com/nicklaw5/go-respond
```

## Usage

The goal of `go-respond` is to take most of the grunt work out preparing your JSON response. Here's a simple example:

```go
package main

import (
    "net/http"

    resp "github.com/nicklaw5/go-respond"
)

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

func main() {
    http.HandleFunc("/api/users", func(w http.ResponseWriter, r *http.Request) {
        users := []User{
            {1, "Billy", "billy@example.com"},
            {2, "Joan", "joan@example.com"},
        }

        resp.NewResponse(w).Ok(users)
    })

    http.ListenAndServe(":8080", nil)
}
```

## Response Methods

| Response Code | Method Name |
| :---------- | :------------ |
| 200 | Ok() |
| 201 | Created() |
| 202 | Accepted() |
| 204 | NoContent() |
| 400 | BadRequest() |
| 401 | Unauthorized() |
| 403 | Forbidden() |
| 404 | NotFound() |
| 405 | MethodNotAllowed() |
| 406 | NotAcceptable() |
| 409 | Conflict() |
| 410 | Gone() |
| 411 | LengthRequired() |
| 412 | PreconditionFailed() |
| 413 | RequestEntityTooLarge() |
| 415 | UnsupportedMediaType() |
| 422 | UnprocessableEntity() |
| 500 | InternalServerError() |
| 501 | NotImplemented() |
| 502 | BadGateway() |
| 503 | ServiceUnavailable() |
| 504 | GatewayTimeout() |

See [here](https://httpstatuses.com/) for a complete list of HTTP responses, along with an explanation of each.

Please submit a PR if you want to add to this list. Only the most common response types have been included.

## To Long, Don't Write

Sometimes you don't need to return a specific content-message but don't want the response body to be empty.
In this case you can use the `DefaultMessage()` for responding with json containing the default message for the corresponding status code.

```go
package main

import (
    "net/http"
    resp "github.com/nicklaw5/go-respond"
)

func main() {
    http.HandleFunc("/api/users", func(w http.ResponseWriter, r *http.Request) {
        // ...
        if !authenticated {
            resp.NewResponse(w).DefaultMessage().
                Unauthorized(nil)
        }
        // ...
    })
    http.ListenAndServe(":8080", nil)
}
```

Would respond with `{"status":401,"message":"Unauthorized"}`

## Handling Errors

The best option for handling errors that may occur while marshalling the JSON response, is to use [Negroni's Recovery middleware](https://github.com/urfave/negroni#recovery). Here's an example:

```go
package main

import (
    "net/http"

    "github.com/urfave/negroni"
    resp "github.com/nicklaw5/go-respond"
)

type Response struct {
    Success bool `json:"success"`
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
        resp.NewResponse(w).Ok(&Response{true})
    })

    n := negroni.New()
    recovery := negroni.NewRecovery()
    recovery.ErrorHandlerFunc = func(error interface{}) {
        // do something with the unexpected error
    }

    n.Use(recovery)
    n.UseHandler(mux)

    http.ListenAndServe(":8080", n)
}
```

## License

This package is distributed under the terms of the [MIT](LICENSE) License.


go-respond

Get simple struct from complex json by json path

# gojmapr

![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/limiu82214/gojmapr?label=version) [![Go Reference](https://pkg.go.dev/badge/github.com/limiu82214/gojmapr.svg)](https://pkg.go.dev/github.com/limiu82214/gojmapr) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![codecov](https://codecov.io/gh/limiu82214/gojmapr/branch/master/graph/badge.svg?token=QX59JZM663)](https://codecov.io/gh/limiu82214/gojmapr) [![Go Report Card](https://goreportcard.com/badge/github.com/limiu82214/gojmapr)](https://goreportcard.com/report/github.com/limiu82214/gojmapr) ![github actions workflow](https://github.com/limiu82214/gojmapr/actions/workflows/lint.yml/badge.svg) [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)  


[中文版文檔](./README_ZH.md)

gojmapr is a Golang library that allows for quick extraction of specified properties from complex JSON strings and converts them into corresponding Go structures.

With gojmapr, you don't need to declare a complete Go structure that corresponds to the entire JSON structure, just provide the required properties.

This makes gojmapr particularly useful for extracting specific data when accessing third-party resources, making your code more concise and readable.

## Features

Easy to use: Easily extract required properties from JSON strings by adding a few tags.
Supports nested properties: Easily extract required properties from JSON strings with multiple nested levels.

## Installation

To use gojmapr, first add it to your Golang project:

```go
go get github.com/limiu82214/gojmapr
```

## Usage

To use the gojmapr library, simply import it into your code and follow these steps:

Define a struct that corresponds to the JSON string you want to parse.
Add the gojmapr tag to each property in the struct to specify the path to extract the property from the JSON string (reference jpath).
Use the gojmapr.Unmarshal function to parse the JSON string into a struct object.

## Example

Here's a simple example that shows how to use the gojmapr library to extract properties from a JSON string.

```go
package main

import (
    "fmt"

    "github.com/limiu82214/gojmapr"
)

func main() {
    jsonString := `{
        "user": {
            "name": "John",
            "email": "john@example.com"
        },
        "cart": {
            "items": [
                {
                    "product": {
                        "id": "123",
                        "name": "Product A",
                        "description": "Product A description",
                        "price": 10.99
                    },
                    "quantity": 2
                },
                {
                    "product": {
                        "id": "456",
                        "name": "Product B",
                        "description": "Product B description",
                        "price": 5.99
                    },
                    "quantity": 1
                }
            ],
            "total": 27.97
        },
        "shipping": {
            "method": "standard",
            "address": {
                "street": "123 Main St",
                "city": "Anytown",
                "state": "CA",
                "zip": "12345"
            },
            "fee": 5.99
        },
        "create_at": "2020-01-01T00:00:00Z"
    }`

    type tmpStruct struct {
        Name string `gojmapr:"user.name"`
    }

    var s tmpStruct
    err := gojmapr.Unmarshal([]byte(jsonString), &s)
    if err != nil {
        panic(err)
    }

    fmt.Println(s.Name) // Output: John

    type tmpStruct2 struct {
        ID    string  `gojmapr:"$.cart.items[0].product.id"`
        Price float64 `gojmapr:"$.cart.items.0.product.price"`
    }

    var s2 tmpStruct
    err := Unmarshal([]byte(jsonString), &s2)
    if err != nil {
        panic(err)
    }

    fmt.Println(s2.ID) // Output: 123
    fmt.Println(s2.Price) // Output: 10.99
}
```

More examples of usage can be found in the test code in the project.

## Use other Unmarshal package

```go

import jsoniter "github.com/json-iterator/go"

type tmpStruct struct {
    RequestID string `gojmapr:"$.request_id"`
}

SetUnmarshalFunc(jsoniter.Unmarshal) // You can use other Unmarshal module ex: json-iterator

var s tmpStruct
err := Unmarshal([]byte(jsonString), &s)
ex.Assert().Nil(err)
ex.Assert().Equal(ex.anserStruct.RequestID, s.RequestID)
```

gojmapr can use other Unmarshal package ex: json-iterator.  

## Testing

gojmapr uses the testify package for testing.  
To run the tests, use the following command:

```bash
go test -v ./...
```

## Dependency

* [github.com/limiu82214/gojpath](http://github.com/limiu82214/gojpath)

## Other

If you encounter any issues during use, please feel free to raise an issue on the GitHub project or contact me via email.  
If you find this project helpful, please consider giving it a star.

## LICENSE

[MIT License](./LICENSE)


gojmapr

Automatically generate Go (golang) struct definitions from example JSON

[![Build Status](https://travis-ci.org/ChimeraCoder/gojson.svg?branch=master)](https://travis-ci.org/ChimeraCoder/gojson)
gojson
======

gojson generates go struct definitions from json or yaml documents.

Example
----------

```sh
$ curl -s https://api.github.com/repos/chimeracoder/gojson | gojson -name=Repository

package main

type Repository struct {
	ArchiveURL       string      `json:"archive_url"`
	AssigneesURL     string      `json:"assignees_url"`
	BlobsURL         string      `json:"blobs_url"`
	BranchesURL      string      `json:"branches_url"`
	CloneURL         string      `json:"clone_url"`
	CollaboratorsURL string      `json:"collaborators_url"`
	CommentsURL      string      `json:"comments_url"`
	CommitsURL       string      `json:"commits_url"`
	CompareURL       string      `json:"compare_url"`
	ContentsURL      string      `json:"contents_url"`
	ContributorsURL  string      `json:"contributors_url"`
	CreatedAt        string      `json:"created_at"`
	DefaultBranch    string      `json:"default_branch"`
	Description      string      `json:"description"`
	DownloadsURL     string      `json:"downloads_url"`
	EventsURL        string      `json:"events_url"`
	Fork             bool        `json:"fork"`
	Forks            float64     `json:"forks"`
	ForksCount       float64     `json:"forks_count"`
	ForksURL         string      `json:"forks_url"`
	FullName         string      `json:"full_name"`
	GitCommitsURL    string      `json:"git_commits_url"`
	GitRefsURL       string      `json:"git_refs_url"`
	GitTagsURL       string      `json:"git_tags_url"`
	GitURL           string      `json:"git_url"`
	HasDownloads     bool        `json:"has_downloads"`
	HasIssues        bool        `json:"has_issues"`
	HasWiki          bool        `json:"has_wiki"`
	Homepage         interface{} `json:"homepage"`
	HooksURL         string      `json:"hooks_url"`
	HtmlURL          string      `json:"html_url"`
	ID               float64     `json:"id"`
	IssueCommentURL  string      `json:"issue_comment_url"`
	IssueEventsURL   string      `json:"issue_events_url"`
	IssuesURL        string      `json:"issues_url"`
	KeysURL          string      `json:"keys_url"`
	LabelsURL        string      `json:"labels_url"`
	Language         string      `json:"language"`
	LanguagesURL     string      `json:"languages_url"`
	MasterBranch     string      `json:"master_branch"`
	MergesURL        string      `json:"merges_url"`
	MilestonesURL    string      `json:"milestones_url"`
	MirrorURL        interface{} `json:"mirror_url"`
	Name             string      `json:"name"`
	NetworkCount     float64     `json:"network_count"`
	NotificationsURL string      `json:"notifications_url"`
	OpenIssues       float64     `json:"open_issues"`
	OpenIssuesCount  float64     `json:"open_issues_count"`
	Owner            struct {
		AvatarURL         string  `json:"avatar_url"`
		EventsURL         string  `json:"events_url"`
		FollowersURL      string  `json:"followers_url"`
		FollowingURL      string  `json:"following_url"`
		GistsURL          string  `json:"gists_url"`
		GravatarID        string  `json:"gravatar_id"`
		HtmlURL           string  `json:"html_url"`
		ID                float64 `json:"id"`
		Login             string  `json:"login"`
		OrganizationsURL  string  `json:"organizations_url"`
		ReceivedEventsURL string  `json:"received_events_url"`
		ReposURL          string  `json:"repos_url"`
		SiteAdmin         bool    `json:"site_admin"`
		StarredURL        string  `json:"starred_url"`
		SubscriptionsURL  string  `json:"subscriptions_url"`
		Type              string  `json:"type"`
		URL               string  `json:"url"`
	} `json:"owner"`
	Private         bool    `json:"private"`
	PullsURL        string  `json:"pulls_url"`
	PushedAt        string  `json:"pushed_at"`
	Size            float64 `json:"size"`
	SshURL          string  `json:"ssh_url"`
	StargazersURL   string  `json:"stargazers_url"`
	StatusesURL     string  `json:"statuses_url"`
	SubscribersURL  string  `json:"subscribers_url"`
	SubscriptionURL string  `json:"subscription_url"`
	SvnURL          string  `json:"svn_url"`
	TagsURL         string  `json:"tags_url"`
	TeamsURL        string  `json:"teams_url"`
	TreesURL        string  `json:"trees_url"`
	UpdatedAt       string  `json:"updated_at"`
	URL             string  `json:"url"`
	Watchers        float64 `json:"watchers"`
	WatchersCount   float64 `json:"watchers_count"`
}
```

CLI Installation
----------------

```sh
$ go get github.com/ChimeraCoder/gojson/gojson
```

Assuming `$GOPATH/bin` is in your `PATH`, you can now invoke `gojson` directly.


API Installation
----------------

```sh
$ go get github.com/ChimeraCoder/gojson/gojson
```

Development
-----------

```
$ git clone https://github.com/ChimeraCoder/gojson.git
$ cd gojson
$ go test
```

**Building CLI**

```
$ go build -o _build/gojson ./gojson
```

**Installing CLI**

```
$ go install ./gojson
```

**Formatting**

```
$ gofmt -w -e -s -l .
```

Related Work
------------

github.com/str1ngs/jflect

License
----------

gojson is free software distributed under Version 3 of the GNU Public License.

As of the time of writing, this is the same license used for gcc (and therefore gccgo), so it is unlikely to restrict use in any way. Note that the GPL does not extend to any output generated by gojson; the GPL only applies to software which includes copies of gojson itself.


gojson

Drop-in replacement for `encoding/json` that outputs colorized JSON

[![Actions Status](https://github.com/neilotoole/jsoncolor/workflows/Go/badge.svg)](https://github.com/neilotoole/jsoncolor/actions?query=workflow%3AGo)
[![Go Report Card](https://goreportcard.com/badge/neilotoole/jsoncolor)](https://goreportcard.com/report/neilotoole/jsoncolor)
[![release](https://img.shields.io/badge/release-v0.7.0-green.svg)](https://github.com/neilotoole/jsoncolor/releases/tag/v0.7.0)
[![Go Reference](https://pkg.go.dev/badge/github.com/neilotoole/jsoncolor.svg)](https://pkg.go.dev/github.com/neilotoole/jsoncolor)
[![license](https://img.shields.io/github/license/neilotoole/jsoncolor)](./LICENSE)

# jsoncolor

Package `neilotoole/jsoncolor` is a drop-in replacement for stdlib
[`encoding/json`](https://pkg.go.dev/encoding/json) that outputs colorized JSON.

Why? Well, [`jq`](https://jqlang.github.io/jq/) colorizes its output by default, and color output
is desirable for many Go CLIs. This package performs colorization (and indentation) inline
in the encoder, and is significantly faster than stdlib at indentation.

From the example [`jc`](./cmd/jc/main.go) app:

![jsoncolor-output](./splash.png)

## Usage

Get the package per the normal mechanism (requires Go 1.17+):

```shell
go get -u github.com/neilotoole/jsoncolor
```

Then:

```go
package main

import (
  "fmt"
  "github.com/mattn/go-colorable"
  json "github.com/neilotoole/jsoncolor"
  "os"
)

func main() {
  var enc *json.Encoder

  // Note: this check will fail if running inside Goland (and
  // other IDEs?) as IsColorTerminal will return false.
  if json.IsColorTerminal(os.Stdout) {
    // Safe to use color
    out := colorable.NewColorable(os.Stdout) // needed for Windows
    enc = json.NewEncoder(out)

    // DefaultColors are similar to jq
    clrs := json.DefaultColors()

    // Change some values, just for fun
    clrs.Bool = json.Color("\x1b[36m") // Change the bool color
    clrs.String = json.Color{}         // Disable the string color

    enc.SetColors(clrs)
  } else {
    // Can't use color; but the encoder will still work
    enc = json.NewEncoder(os.Stdout)
  }

  m := map[string]interface{}{
    "a": 1,
    "b": true,
    "c": "hello",
  }

  if err := enc.Encode(m); err != nil {
    fmt.Fprintln(os.Stderr, err)
    os.Exit(1)
  }
}
```

### Configuration

To enable colorization, invoke [`enc.SetColors`](https://pkg.go.dev/github.com/neilotoole/jsoncolor#Encoder.SetColors).

The [`Colors`](https://pkg.go.dev/github.com/neilotoole/jsoncolor#Colors) struct
holds color config. The zero value and `nil` are both safe for use (resulting in no colorization).

The [`DefaultColors`](https://pkg.go.dev/github.com/neilotoole/jsoncolor#DefaultColors) func
returns a `Colors` struct that produces results similar to `jq`:

```go
// DefaultColors returns the default Colors configuration.
// These colors largely follow jq's default colorization,
// with some deviation.
func DefaultColors() *Colors {
  return &Colors{
    Null:   Color("\x1b[2m"),
    Bool:   Color("\x1b[1m"),
    Number: Color("\x1b[36m"),
    String: Color("\x1b[32m"),
    Key:    Color("\x1b[34;1m"),
    Bytes:  Color("\x1b[2m"),
    Time:   Color("\x1b[32;2m"),
    Punc:   Color{}, // No colorization
  }
}
```

As seen above, use the `Color` zero value (`Color{}`) to
disable colorization for that JSON element.

### Helper for `fatih/color`

It can be inconvenient to use terminal codes, e.g. `json.Color("\x1b[36m")`.
A helper package provides an adapter for [`fatih/color`](https://github.com/fatih/color).

```go
  // import "github.com/neilotoole/jsoncolor/helper/fatihcolor"
  // import "github.com/fatih/color"
  // import "github.com/mattn/go-colorable"
  
  out := colorable.NewColorable(os.Stdout) // needed for Windows
  enc = json.NewEncoder(out)
  
  fclrs := fatihcolor.DefaultColors()
  // Change some values, just for fun
  fclrs.Number = color.New(color.FgBlue)
  fclrs.String = color.New(color.FgCyan)
  
  clrs := fatihcolor.ToCoreColors(fclrs)
  enc.SetColors(clrs)
```

### Drop-in for `encoding/json`

This package is a full drop-in for stdlib [`encoding/json`](https://pkg.go.dev/encoding/json)
(thanks to the ancestral [`segmentio/encoding/json`](https://pkg.go.dev/github.com/segmentio/encoding/json)
pkg being a full drop-in).

To drop-in, just use an import alias:

```go
  import json "github.com/neilotoole/jsoncolor"
```

## Example app: `jc`

See [`cmd/jc`](cmd/jc/main.go) for a trivial CLI implementation that can accept JSON input,
and output that JSON in color.

```shell
# From project root
$ go install ./cmd/jc
$ cat ./testdata/sakila_actor.json | jc
```

## Benchmarks

Note that this package contains [`golang_bench_test.go`](./golang_bench_test.go), which
is inherited from `segmentj`. But here we're interested in [`benchmark_test.go:BenchmarkEncode`](./benchmark_test.go),
which benchmarks encoding performance versus other JSON encoder packages.
The results below benchmark the following:

- Stdlib [`encoding/json`](https://pkg.go.dev/encoding/json) (`go1.17.1`).
- [`segmentj`](https://github.com/segmentio/encoding): `v0.1.14`, which was when `jsoncolor` was forked. The newer `segmentj` code performs even better.
- `neilotoole/jsoncolor`: (this package) `v0.6.0`.
- [`nwidger/jsoncolor`](https://github.com/nwidger/jsoncolor): `v0.3.0`, latest at time of benchmarks.

Note that two other Go JSON colorization packages ([`hokaccha/go-prettyjson`](https://github.com/hokaccha/go-prettyjson) and
[`TylerBrock/colorjson`](https://github.com/TylerBrock/colorjson)) are excluded from
these benchmarks because they do not provide a stdlib-compatible `Encoder` impl.

```
$ go test -bench=BenchmarkEncode -benchtime="5s"
goarch: amd64
pkg: github.com/neilotoole/jsoncolor
cpu: Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz
BenchmarkEncode/stdlib_NoIndent-16                           181          33047390 ns/op         8870685 B/op     120022 allocs/op
BenchmarkEncode/stdlib_Indent-16                             124          48093178 ns/op        10470366 B/op     120033 allocs/op
BenchmarkEncode/segmentj_NoIndent-16                         415          14658699 ns/op         3788911 B/op      10020 allocs/op
BenchmarkEncode/segmentj_Indent-16                           195          30628798 ns/op         5404492 B/op      10025 allocs/op
BenchmarkEncode/neilotoole_NoIndent_NoColor-16               362          16522399 ns/op         3789034 B/op      10020 allocs/op
BenchmarkEncode/neilotoole_Indent_NoColor-16                 303          20146856 ns/op         5460753 B/op      10021 allocs/op
BenchmarkEncode/neilotoole_NoIndent_Color-16                 295          19989420 ns/op        10326019 B/op      10029 allocs/op
BenchmarkEncode/neilotoole_Indent_Color-16                   246          24714163 ns/op        11996890 B/op      10030 allocs/op
BenchmarkEncode/nwidger_NoIndent_NoColor-16                   10         541107983 ns/op        92934231 B/op    4490210 allocs/op
BenchmarkEncode/nwidger_Indent_NoColor-16                      7         798088086 ns/op        117258321 B/op   6290213 allocs/op
BenchmarkEncode/nwidger_indent_NoIndent_Colo-16               10         542002051 ns/op        92935639 B/op    4490224 allocs/op
BenchmarkEncode/nwidger_indent_Indent_Color-16                 7         799928353 ns/op        117259195 B/op   6290220 allocs/op
```

As always, take benchmarks with a large grain of salt, as they're based on a (small) synthetic benchmark.
More benchmarks would give a better picture (and note as well that the benchmarked `segmentj` is an older version, `v0.1.14`).

All that having been said, what can we surmise from these particular results?

- `segmentj` performs better than `stdlib` at all encoding tasks.
- `jsoncolor` performs better than `segmentj` for indentation (which makes sense, as indentation is performed inline).
- `jsoncolor` performs better than `stdlib` at all encoding tasks.

Again, trust these benchmarks at your peril. Create your own benchmarks for your own workload.

## Notes

- The [`.golangci.yml`](./.golangci.yml) linter settings have been fiddled with to hush some
  linting issues inherited from the `segmentio` codebase at the time of forking. Thus, the linter report
  may not be of great use. In an ideal world, the `jsoncolor` functionality would be [ported](https://github.com/neilotoole/jsoncolor/issues/15) to a
  more recent (and better-linted) version of the `segementio` codebase.
- The `segmentio` encoder (at least as of `v0.1.14`) encodes `time.Duration` as string, while `stdlib` outputs as `int64`.
  This package follows `stdlib`.
- The [`Colors.Punc`](https://pkg.go.dev/github.com/neilotoole/jsoncolor#Colors) field controls all
  punctuation colorization, i.e. `[]{},:"`. It is probably worthwhile to [separate](https://github.com/neilotoole/jsoncolor/issues/16)
  these out into individually-configurable elements.

<a name="history"></a>
## CHANGELOG

History: this package is an extract of [`sq`](https://github.com/neilotoole/sq)'s JSON encoding package, which itself is a fork of the
[`segmentio/encoding`](https://github.com/segmentio/encoding) JSON encoding package. Note that the
original `sq` JSON encoder was forked from Segment's codebase at `v0.1.14`, so
the codebases have drifted significantly by now.

### [v0.7.2](https://github.com/neilotoole/jsoncolor/releases/tag/v0.7.2)

- [#38](https://github.com/neilotoole/jsoncolor/issues/38): Fix `TestCodec` failure on Go 1.22+ and update CI.
  - Use semantic JSON comparison in `TestCodec` to handle stdlib escape sequence changes.
  - Bump minimum Go version from 1.16 to 1.17.
  - Update CI workflows: expand test matrix to Go 1.17/1.24/1.26, fix `golangci-lint` workflow.

### [v0.7.1](https://github.com/neilotoole/jsoncolor/releases/tag/v0.7.1)

- [#27](https://github.com/neilotoole/jsoncolor/pull/27): Improved Windows terminal color support checking.

### [v0.7.0](https://github.com/neilotoole/jsoncolor/releases/tag/v0.7.0)

- [#21](https://github.com/neilotoole/jsoncolor/pull/21): Support for [`encoding.TextMarshaler`](https://pkg.go.dev/encoding#TextMarshaler).
- [#22](https://github.com/neilotoole/jsoncolor/pull/22): Removed redundant dependencies.
- [#26](https://github.com/neilotoole/jsoncolor/pull/26): Updated dependencies.

## Acknowledgments

- [`jq`](https://stedolan.github.io/jq/): sine qua non.
- [`segmentio/encoding`](https://github.com/segmentio/encoding): `jsoncolor` is layered into Segment's JSON encoder. They did the hard work. Much gratitude to that team.
- [`sq`](https://github.com/neilotoole/sq): `jsoncolor` is effectively an extract of code created specifically for `sq`.
- [`mattn/go-colorable`](https://github.com/mattn/go-colorable): no project is complete without `mattn` having played a role.
- [`fatih/color`](https://github.com/fatih/color): the color library.
- [`@hermannm`](https://github.com/hermannm): for several PRs.

### Related

- [`nwidger/jsoncolor`](https://github.com/nwidger/jsoncolor)
- [`hokaccha/go-prettyjson`](https://github.com/hokaccha/go-prettyjson)
- [`TylerBrock/colorjson`](https://github.com/TylerBrock/colorjson)


jsoncolor

JSON diff library for Go based on RFC6902 (JSON Patch)

jsondiff

Simple Go package to make custom structs marshal into HAL compatible JSON responses

## jsonhal

A simple Go package to make custom structs marshal into [HAL](http://stateless.co/hal_specification.html) compatible JSON responses.

[![Travis Status for RichardKnop/jsonhal](https://travis-ci.org/RichardKnop/jsonhal.svg?branch=master&label=linux+build)](https://travis-ci.org/RichardKnop/jsonhal)
[![godoc for RichardKnop/jsonhal](https://godoc.org/github.com/nathany/looper?status.svg)](http://godoc.org/github.com/RichardKnop/jsonhal)
[![codecov for RichardKnop/jsonhal](https://codecov.io/gh/RichardKnop/jsonhal/branch/master/graph/badge.svg)](https://codecov.io/gh/RichardKnop/jsonhal)

---


Just add `jsonhal.Hal` as anonymous field to your structs and use `SetLink` to set hyperlinks and optionally `SetEmbedded` to set embedded resources.

Example:

```go
package main

import (
	"encoding/json"
	"log"

	"github.com/RichardKnop/jsonhal"
)

// HelloWorld ...
type HelloWorld struct {
	jsonhal.Hal
	ID   uint   `json:"id"`
	Name string `json:"name"`
}

// Foobar ...
type Foobar struct {
	jsonhal.Hal
	ID   uint   `json:"id"`
	Name string `json:"name"`
}

func main() {
	var (
		helloWorld   *HelloWorld
		jsonResponse []byte
		err          error
	)

	helloWorld = &HelloWorld{ID: 1, Name: "Hello World"}
	helloWorld.SetLink("self", "/v1/hello/world/1", "")

	jsonResponse, err = json.Marshal(helloWorld)
	if err != nil {
		log.Fatal(err)
	}
	log.Print(string(jsonResponse))
	// {
	// 	"_links": {
	// 		"self": {
	// 			"href": "/v1/hello/world/1"
	// 		}
	// 	},
	// 	"id": 1,
	// 	"name": "Hello World"
	// }

	helloWorld = &HelloWorld{ID: 1, Name: "Hello World"}
	helloWorld.SetLink(
		"self", // name
		"/v1/hello/world?offset=2&limit=2", // href
		"", // title
	)
	helloWorld.SetLink(
		"next", // name
		"/v1/hello/world?offset=4&limit=2", // href
		"", // title
	)
	helloWorld.SetLink(
		"previous",                         // name
		"/v1/hello/world?offset=0&limit=2", // href
		"", // title
	)
	jsonResponse, err = json.Marshal(helloWorld)
	if err != nil {
		log.Fatal(err)
	}
	log.Print(string(jsonResponse))
	// {
	// 	"_links": {
	// 		"next": {
	// 			"href": "/v1/hello/world?offset=4\u0026limit=2"
	// 		},
	// 		"previous": {
	// 			"href": "/v1/hello/world?offset=0\u0026limit=2"
	// 		},
	// 		"self": {
	// 			"href": "/v1/hello/world?offset=2\u0026limit=2"
	// 		}
	// 	},
	// 	"id": 1,
	// 	"name": "Hello World"
	// }

	helloWorld = &HelloWorld{ID: 1, Name: "Hello World"}
	helloWorld.SetLink("self", "/v1/hello/world/1", "")

	// Add embedded resources
	foobars := []*Foobar{
		&Foobar{
			Hal: jsonhal.Hal{
				Links: map[string]*jsonhal.Link{
					"self": &jsonhal.Link{Href: "/v1/foo/bar/1"},
				},
			},
			ID:   1,
			Name: "Foo bar 1",
		},
		&Foobar{
			Hal: jsonhal.Hal{
				Links: map[string]*jsonhal.Link{
					"self": &jsonhal.Link{Href: "/v1/foo/bar/2"},
				},
			},
			ID:   2,
			Name: "Foo bar 2",
		},
	}
	helloWorld.SetEmbedded("foobars", Embedded(foobars))

	jsonResponse, err = json.Marshal(helloWorld)
	if err != nil {
		log.Fatal(err)
	}
	log.Print(string(jsonResponse))
	// {
	// 	"_links": {
	// 		"self": {
	// 			"href": "/v1/hello/world/1"
	// 		}
	// 	},
	// 	"_embedded": {
	// 		"foobars": [
	// 			{
	// 				"_links": {
	// 					"self": {
	// 						"href": "/v1/foo/bar/1"
	// 					}
	// 				},
	// 				"id": 1,
	// 				"name": "Foo bar 1"
	// 			},
	// 			{
	// 				"_links": {
	// 					"self": {
	// 						"href": "/v1/foo/bar/2"
	// 					}
	// 				},
	// 				"id": 2,
	// 				"name": "Foo bar 2"
	// 			}
	// 		]
	// 	},
	// 	"id": 1,
	// 	"name": "Hello World"
	// }
}
```


jsonhal

JSON library with standard compatible API/behavior

[![Go Report Card](https://goreportcard.com/badge/github.com/zerosnake0/jzon)](https://goreportcard.com/report/github.com/zerosnake0/jzon)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/zerosnake0/jzon)](https://pkg.go.dev/github.com/zerosnake0/jzon)
[![Github Workflow](https://github.com/zerosnake0/jzon/workflows/Test/badge.svg)](https://github.com/zerosnake0/jzon/actions?query=workflow%3ATest)
[![Build Status](https://travis-ci.org/zerosnake0/jzon.svg?branch=master)](https://travis-ci.org/zerosnake0/jzon)
[![codecov](https://codecov.io/gh/zerosnake0/jzon/branch/master/graph/badge.svg)](https://codecov.io/gh/zerosnake0/jzon)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)

# jzon

A high performance json library for Golang

## Why another jsoniter?

The code I write here is very similar to [github.com/json-iterator/go](https://github.com/json-iterator/go),
so you may ask why reinvent the wheel.

For sure that I benefit a lot from the `jsoniter` library, but i found some inconvenience for me to use it
in some condition, for example:

- the iterator methods ReadString accepts null, there is no method which accepts exactly string.
  I have to do some extra check before calling.
- some behavior is not compatible with the standard library.
- I want a chained streamer

On the other hand, I also want to learn how the `jsoniter` works, so there is this repo.

## What's different from jsoniter?

Here are some of the differences:

- the iterator methods accept the exact type, for example ReadString accepts only string, not null
- the behavior is almost the same as the standard library (when an error returns, the behavior may differ
  from the standard library)
- the error of the iterator is returned instead of being saved inside iterator
- the decoder/encoder interface has additional options, like struct tag options

Some features of `jsoniter` are not implemented, and may be not implemented in the future neither.
I choose only the ones I need to implement.

## Compatibility with standard library

I tried implemented a version which is completely compatible with the standard library:

https://github.com/zerosnake0/jzon/tree/reflect

The benchmark shows that it's much faster than the standard library.
However it is still much slower than the current version,
which cannot be exactly the same as standard library (at least in my POV).

The major incompatibility is about the two following interfaces:
- `json.Marshaler`
- `encoding.TextMarshaler`

The method on pointer receiver may be called with an unaddressable value,
for example:

```go
type field struct {}

func (*field) MarshalJSON() ([]byte, error)

type st struct {
    F field
}

json.Marshal(st{}) // will not call field.MarshalJSON
jzon.Marshal(st{}) // will call field.MarshalJSON
```

So the user should be care when marshaling a value when method on
pointer receiver is involved

You can check the tests for more detailed info about the difference

## How to use

### Standard library like

```go
import "github.com/zerosnake0/jzon"

// Unmarshal
err := jzon.Unmarshal(b, &data)

// Marshal
b, err := jzon.Marshal(&data)

// Decoder
dec := jzon.NewDecoder(reader)
defer dec.Release()
err := dec.Decode(&data)

// Encoder
enc := jzon.NewEncoder(writer)
defer enc.Release()
err := enc.Encode(&data)
```

### Iterator

```go
iter := jzon.NewIterator()
defer iter.Release()
iter.Reset(b)
jzon.ReadVal(&data)
```

### Streamer

```go
var w io.Writer

streamer := jzon.NewStreamer()
defer streamer.Release()
streamer.Reset(w)
streamer.Value(&data)
streamer.Flush()
```

### Custom Decoder

see `decoder_test.go`

```go
type testIntDecoder struct{}

func (*testIntDecoder) Decode(ptr unsafe.Pointer, it *Iterator, opts *DecOpts) error {
    ...
}

dec := NewDecoderConfig(&DecoderOption{
    ValDecoders: map[reflect.Type]ValDecoder{
        reflect.TypeOf(int(0)): (*testIntDecoder)(nil),
    },
    CaseSensitive: true,
})

// standard library like
err := dec.Unmarshal(b, &data)

// iterator
iter := dec.NewIterator()
defer iter.Release()
```

### Custom Encoder

see `encoder_test.go`

```go
type testIntEncoder struct{}

func (*testIntEncoder) IsEmpty(ptr unsafe.Pointer) bool {
    ...
}

func (*testIntEncoder) Encode(ptr unsafe.Pointer, s *Streamer, opts *EncOpts) {
    ...
}

enc := NewEncoderConfig(&EncoderOption{
    ValEncoders: map[reflect.Type]ValEncoder{
        reflect.TypeOf(int(0)): (*testIntEncoder)(nil),
    },
})

// standard library like
b, err := enc.Marshal(&data)

// streamer
streamer := enc.NewStreamer()
defer streamer.Release()
```


jzon

API for arbitrary transformation of JSON documents

# kazaam

[![Travis Build Status](https://img.shields.io/travis/qntfy/kazaam.svg?branch=master)](https://travis-ci.com/qntfy/kazaam)
[![Coverage Status](https://coveralls.io/repos/github/qntfy/kazaam/badge.svg?branch=master)](https://coveralls.io/github/qntfy/kazaam?branch=master)
[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![GitHub release](https://img.shields.io/github/release/qntfy/kazaam.svg?maxAge=3600)](https://github.com/qntfy/kazaam/releases/latest)
[![Go Report Card](https://goreportcard.com/badge/github.com/qntfy/kazaam)](https://goreportcard.com/report/github.com/qntfy/kazaam)
[![GoDoc](https://godoc.org/github.com/qntfy/kazaam?status.svg)](https://pkg.go.dev/github.com/qntfy/kazaam/v4)

## Description

Kazaam was created with the goal of supporting easy and fast transformations of JSON data with Golang.
This functionality provides us with an easy mechanism for taking intermediate JSON message representations
and transforming them to formats required by arbitrary third-party APIs.

Inspired by [Jolt](https://github.com/bazaarvoice/jolt), Kazaam supports JSON to JSON transformation via a
transform "specification" also defined in JSON. A specification is comprised of one or more "operations". See
Specification Support, below, for more details.

## Documentation

API Documentation is available on [pkg.go.dev](https://pkg.go.dev/github.com/qntfy/kazaam/v4).

## Features

Kazaam is primarily designed to be used as a library for transforming arbitrary JSON.
It ships with six built-in transform types, described below, which provide significant flexibility
in reshaping JSON data.

Also included when you `go get` Kazaam, is a binary implementation, `kazaam` that can be used for
development and testing of new transform specifications.

Finally, Kazaam supports the implementation of custom transform types. We encourage and appreciate
pull requests for new transform types so that they can be incorporated into the Kazaam distribution,
but understand sometimes time-constraints or licensing issues prevent this. See the API documentation
for details on how to write and register custom transforms.

Due to performance considerations, Kazaam does not fully validate that input data is valid JSON. The
`IsJson()` function is provided for convenience if this functionality is needed, it may significantly slow
down use of Kazaam.

## Specification Support

Kazaam currently supports the following transforms:

- shift
- concat
- coalesce
- extract
- timestamp
- uuid
- default
- pass
- delete

### Shift

The shift transform is the current Kazaam workhorse used for remapping of fields.
The specification supports jsonpath-esque JSON accesses and sets. Concretely

```javascript
{
  "operation": "shift",
  "spec": {
    "object.id": "doc.uid",
    "gid2": "doc.guid[1]",
    "allGuids": "doc.guidObjects[*].id"
  }
}
```

executed on a JSON message with format

```javascript
{
  "doc": {
    "uid": 12345,
    "guid": ["guid0", "guid2", "guid4"],
    "guidObjects": [{"id": "guid0"}, {"id": "guid2"}, {"id": "guid4"}]
  },
  "top-level-key": null
}
```

would result in

```javascript
{
  "object": {
    "id": 12345
  },
  "gid2": "guid2",
  "allGuids": ["guid0", "guid2", "guid4"]
}
```

The jsonpath implementation supports a few special cases:

- *Array accesses*: Retrieve `n`th element from array
- *Array wildcarding*: indexing an array with `[*]` will return every matching element in an array
- *Top-level object capture*: Mapping `$` into a field will nest the entire original object under the requested key
- *Array append/prepend and set*: Append and prepend an array with `[+]` and `[-]`. Attempting to write an array element that does not exist results in null padding as needed to add that element at the specified index (useful with `"inplace"`).

The shift transform also supports a `"require"` field. When set to `true`,
Kazaam will throw an error if *any* of the paths in the source JSON are not
present.

Finally, shift by default is destructive. For in-place operation, an optional `"inplace"`
field may be set.

### Concat

The concat transform allows the combination of fields and literal strings into a single string value.

```javascript
{
    "operation": "concat",
    "spec": {
        "sources": [{
            "value": "TEST"
        }, {
            "path": "a.timestamp"
        }],
        "targetPath": "a.timestamp",
        "delim": ","
    }
}
```

executed on a JSON message with format

```javascript
{
    "a": {
        "timestamp": 1481305274
    }
}
```

would result in

```javascript
{
    "a": {
        "timestamp": "TEST,1481305274"
    }
}
```

Notes:

- *sources*: list of items to combine (in the order listed)
  - literal values are specified via `value`
  - field values are specified via `path` (supports the same addressing as `shift`)
- *targetPath*: where to place the resulting string
  - if this an existing path, the result will replace current value.
- *delim*: Optional delimiter

The concat transform also supports a `"require"` field. When set to `true`,
Kazaam will throw an error if *any* of the paths in the source JSON are not
present.

### Coalesce

A coalesce transform provides the ability to check multiple possible keys to find a desired value. The first matching key found of those provided is returned.

```javascript
{
  "operation": "coalesce",
  "spec": {
    "firstObjectId": ["doc.guidObjects[0].uid", "doc.guidObjects[0].id"]
  }
}
```

executed on a json message with format

```javascript
{
  "doc": {
    "uid": 12345,
    "guid": ["guid0", "guid2", "guid4"],
    "guidObjects": [{"id": "guid0"}, {"id": "guid2"}, {"id": "guid4"}]
  }
}
```

would result in

```javascript
{
  "doc": {
    "uid": 12345,
    "guid": ["guid0", "guid2", "guid4"],
    "guidObjects": [{"id": "guid0"}, {"id": "guid2"}, {"id": "guid4"}]
  },
  "firstObjectId": "guid0"
}
```

Coalesce also supports an `ignore` array in the spec. If an otherwise matching key has a value in `ignore`, it is not considered a match.
This is useful e.g. for empty strings

```javascript
{
  "operation": "coalesce",
  "spec": {
    "ignore": [""],
    "firstObjectId": ["doc.guidObjects[0].uid", "doc.guidObjects[0].id"]
  }
}
```

### Extract

An `extract` transform provides the ability to select a sub-object and have kazaam return that sub-object as the top-level object. For example

```javascript
{
  "operation": "extract",
  "spec": {
    "path": "doc.guidObjects[0].path.to.subobject"
  }
}
```

executed on a json message with format

```javascript
{
  "doc": {
    "uid": 12345,
    "guid": ["guid0", "guid2", "guid4"],
    "guidObjects": [{"path": {"to": {"subobject": {"name": "the.subobject", "field", "field.in.subobject"}}}}, {"id": "guid2"}, {"id": "guid4"}]
  }
}
```

would result in

```javascript
{
  "name": "the.subobject",
  "field": "field.in.subobject"
}
```

### Timestamp

A `timestamp` transform parses and formats time strings using the golang
syntax. **Note**: this operation is done in-place. If you want to preserve the
original string(s), pair the transform with `shift`. This transform also
supports the `$now` operator for `inputFormat`, which will set the current
timestamp at the specified path, formatted according to the `outputFormat`.
`$unix` is supported for both input and output formats as a Unix time, the
number of seconds elapsed since January 1, 1970 UTC as an integer string.

```javascript
{
  "operation": "timestamp",
  "timestamp[0]": {
    "inputFormat": "Mon Jan _2 15:04:05 -0700 2006",
    "outputFormat": "2006-01-02T15:04:05-0700"
  },
  "nowTimestamp": {
    "inputFormat": "$now",
    "outputFormat": "2006-01-02T15:04:05-0700"
  },
  "epochTimestamp": {
    "inputFormat": "2006-01-02T15:04:05-0700",
    "outputFormat": "$unix"
  }
}

```

executed on a json message with format

```javascript
{
  "timestamp": [
    "Sat Jul 22 08:15:27 +0000 2017",
    "Sun Jul 23 08:15:27 +0000 2017",
    "Mon Jul 24 08:15:27 +0000 2017"
  ]
}
```

would result in

```javascript
{
  "timestamp": [
    "2017-07-22T08:15:27+0000",
    "Sun Jul 23 08:15:27 +0000 2017",
    "Mon Jul 24 08:15:27 +0000 2017"
  ]
  "nowTimestamp": "2017-09-08T19:15:27+0000"
}
```

### UUID

A `uuid` transform generates a UUID based on the spec. Currently supports UUIDv3, UUIDv4, UUIDv5.

For version 4 is a very simple spec

```javascript
{
    "operation": "uuid",
    "spec": {
        "doc.uuid": {
            "version": 4, //required
        }
    }
}
```

executed on a json message with format

```javascript
{
  "doc": {
    "author_id": 11122112,
    "document_id": 223323,
    "meta": {
      "id": 23
    }
  }
}
```

would result in

```javascript
{
  "doc": {
    "author_id": 11122112,
    "document_id": 223323,
    "meta": {
      "id": 23
    }
    "uuid": "f03bacc1-f4e0-4371-a5c5-e8160d3d6c0c"
  }
}
```

For UUIDv3 & UUIDV5 are a bit more complex. These require a Name Space which is a valid UUID already, and a set of paths, which generate UUID's based on the value of that path. If that path doesn't exist in the incoming document, a default field will be used instead. **Note** both of these fields must be strings.
**Additionally** you can use the 4 predefined namespaces such as `DNS`, `URL`, `OID`, & `X500` in the name space field otherwise pass your own UUID.

```javascript
{
   "operation":"uuid",
   "spec":{
      "doc.uuid":{
         "version":5,
         "namespace":"DNS",
         "names":[
            {"path":"doc.author_name", "default":"some string"},
            {"path":"doc.type", "default":"another string"},
         ]
      }
   }
}
```

executed on a json message with format

```javascript
{
  "doc": {
    "author_name": "jason",
    "type": "secret-document"
    "document_id": 223323,
    "meta": {
      "id": 23
    }
  }
}
```

would result in

```javascript
{
  "doc": {
    "author_name": "jason",
    "type": "secret-document",
    "document_id": 223323,
    "meta": {
      "id": 23
    },
    "uuid": "f03bacc1-f4e0-4371-a7c5-e8160d3d6c0c"
  }
}
```

### Default

A default transform provides the ability to set a key's value explicitly. For example

```javascript
{
  "operation": "default",
  "spec": {
    "type": "message"
  }
}
```

would ensure that the output JSON message includes `{"type": "message"}`.

### Delete

A delete transform provides the ability to delete keys in place.

```javascript
{
  "operation": "delete",
  "spec": {
    "paths": ["doc.uid", "doc.guidObjects[1]"]
  }
}
```

executed on a json message with format

```javascript
{
  "doc": {
    "uid": 12345,
    "guid": ["guid0", "guid2", "guid4"],
    "guidObjects": [{"id": "guid0"}, {"id": "guid2"}, {"id": "guid4"}]
  }
}
```

would result in

```javascript
{
  "doc": {
    "guid": ["guid0", "guid2", "guid4"],
    "guidObjects": [{"id": "guid0"}, {"id": "guid4"}]
  }
}
```

### Pass

A pass transform, as the name implies, passes the input data unchanged to the output. This is used internally
when a null transform spec is specified, but may also be useful for testing.

## Usage

To start, go get the versioned repository:

```sh
go get gopkg.in/qntfy/kazaam.v3
```

### Using as an executable program

If you want to create an executable binary from this project, follow
these steps (you'll need `go` installed and `$GOPATH` set):

``` shell
go get gopkg.in/qntfy/kazaam.v3
cd $GOPATH/src/gopkg.in/qntfy/kazaam.v3/kazaam
go install
```

This will create an executable in `$GOPATH/bin` like you
would expect from the normal `go` build behavior.

### Examples

See [godoc examples](https://godoc.org/pkg/gopkg.in/qntfy/kazaam.v3/#pkg-examples).


kazaam

Optimized JSON for Go is a high performance parser with a variety of additional JSON tools including JSONPath

# [![{}j](assets/ojg_comet.svg)](https://github.com/ohler55/ojg)

[![Build Status](https://github.com/ohler55/ojg/actions/workflows/CI.yml/badge.svg)](https://github.com/ohler55/ojg/actions)
[![Go Report Card](https://goreportcard.com/badge/github.com/ohler55/ojg)](https://goreportcard.com/report/github.com/ohler55/ojg)
![](assets/coverage-badge.svg)

Optimized JSON for Go is a high performance parser with a variety of
additional JSON tools. OjG is optimized to processing huge data sets
where data does not necessarily conform to a fixed structure.

## Features

 - Fast JSON parser. Check out the cmd/benchmarks app in this repo.
 - Full JSONPath implemenation that operates on simple types as well as structs.
 - Generic types. Not the proposed golang generics but type safe JSON elements.
 - Fast JSON validator (7 times faster with io.Reader).
 - Fast JSON writer with a sort option (4 times faster).
 - JSON builder from JSON sources using a simple assembly plan.
 - Simple data builders using a push and pop approach.
 - Object encoding and decoding using an approach similar to that used with Oj for Ruby.
 - [Simple Encoding Notation](sen.md), a lazy way to write JSON omitting commas and quotes.
 - [JSON and SEN Discovery](discover.md) as a package or option to the **oj** application.

## Using

A basic Parse:

```golang
    obj, err := oj.ParseString(`{
        "a":[
            {"x":1,"y":2,"z":3},
            {"x":2,"y":4,"z":6}
        ]
    }`)
```

Using JSONPath expressions:

```golang
    x, err := jp.ParseString("a[?(@.x > 1)].y")
    ys := x.Get(obj)
    // returns [4]
```

The **oj** command (cmd/oj) uses JSON path for filtering and
extracting JSON elements. It also includes sorting, reformatting,
discovery of JSON in documents, and colorizing options.

```
$ oj -m "(@.name == 'Pete')" myfile.json

```

More complete examples are available in the go docs for most
functions. The example for [Unmarshalling
interfaces](oj/example_interface_test.go) demonstrates a feature that
allows interfaces to be marshalled and unmarshalled.

## Installation
```
go get github.com/ohler55/ojg
go get github.com/ohler55/ojg/cmd/oj

```

or just import in your `.go` files.

```
import (
    "github.com/ohler55/ojg/alt"
    "github.com/ohler55/ojg/asm"
    "github.com/ohler55/ojg/gen"
    "github.com/ohler55/ojg/jp"
    "github.com/ohler55/ojg/oj"
    "github.com/ohler55/ojg/sen"
    "github.com/ohler55/ojg/discover"
)
```

To build and install the `oj` application:

```
go install ./...
```

The `oj` application can be installed with brew.

```
brew install oj
```

## Benchmarks

Higher numbers (longer bars) are better.

```
Parse string/[]byte
       json.Unmarshal           55916 ns/op    17776 B/op    334 allocs/op
         oj.Parse               39570 ns/op    18488 B/op    429 allocs/op
   oj-reuse.Parse               17881 ns/op     5691 B/op    364 allocs/op

   oj-reuse.Parse        █████████████████████▉ 3.13
         oj.Parse        █████████▉ 1.41
       json.Unmarshal    ▓▓▓▓▓▓▓ 1.00

Parse io.Reader
       json.Decode              63029 ns/op    32449 B/op    344 allocs/op
         oj.ParseReader         34289 ns/op    22583 B/op    430 allocs/op
   oj-reuse.ParseReader         25094 ns/op     9788 B/op    365 allocs/op
         oj.TokenizeLoad        13610 ns/op     6072 B/op    157 allocs/op

         oj.TokenizeLoad ████████████████████████████████▍ 4.63
   oj-reuse.ParseReader  █████████████████▌ 2.51
         oj.ParseReader  ████████████▊ 1.84
       json.Decode       ▓▓▓▓▓▓▓ 1.00

to JSON with indentation
       json.Marshal             78762 ns/op    26978 B/op    352 allocs/op
         oj.JSON                 7662 ns/op        0 B/op      0 allocs/op
        sen.Bytes                9053 ns/op        0 B/op      0 allocs/op

         oj.JSON         ███████████████████████████████████████████████████████████████████████▉ 10.28
        sen.Bytes        ████████████████████████████████████████████████████████████▉ 8.70
       json.Marshal      ▓▓▓▓▓▓▓ 1.00
```

See [all benchmarks](benchmarks.md)

[Compare Go JSON parsers](https://github.com/ohler55/compare-go-json)

## Releases

See [CHANGELOG.md](CHANGELOG.md)

## Links

- *Documentation*: [https://pkg.go.dev/github.com/ohler55/ojg](https://pkg.go.dev/github.com/ohler55/ojg)

- *GitHub* *repo*: https://github.com/ohler55/ojg

- *JSONPath* draft specification: https://datatracker.ietf.org/doc/draft-ietf-jsonpath-base

- *JSONPath Comparisons*: https://cburgmer.github.io/json-path-comparison

- *Go Report Card*: https://goreportcard.com/report/github.com/ohler55/ojg

#### Links of Interest

 - *Oj, a Ruby JSON parser*: http://www.ohler.com/oj/doc/index.html also at https://github.com/ohler55/oj

 - *OjC, a C JSON parser*: http://www.ohler.com/ojc/doc/index.html also at https://github.com/ohler55/ojc

 - *Fast XML parser and marshaller on GitHub*: https://github.com/ohler55/ox

 - *Agoo, a high performance Ruby web server supporting GraphQL on GitHub*: https://github.com/ohler55/agoo

 - *Agoo-C, a high performance C web server supporting GraphQL on GitHub*: https://github.com/ohler55/agoo-c

#### Contributing

+ Provide a Pull Request off the `develop` branch.
+ Report a bug
+ Suggest an idea


Go package for validating JSON objects with declaring a JSON schema with fluent API

# vjson
[![codecov](https://codecov.io/gh/miladibra10/vjson/branch/main/graph/badge.svg)](#)
[![Go Report Card](https://goreportcard.com/badge/github.com/miladibra10/vjson)](https://goreportcard.com/report/github.com/miladibra10/vjson)
[![<miladibra10>](https://circleci.com/gh/miladibra10/vjson.svg?style=svg)](#)
[![Go Reference](https://pkg.go.dev/badge/github.com/miladibra10/vjson.svg)](https://pkg.go.dev/github.com/miladibra10/vjson)

**vjson**  is a Go package that helps to validate JSON objects in a declarative way.

# Getting Started

## Installing

For installing vjson, use command below:

```
go get -u github.com/miladibra10/vjson
```

# Concepts

There are two main concepts in `vjson` that are:

+ Schema
+ Field

## Schema

A schema is the holder of JSON object specifications. It contains the way of validation of a JSON object. a schema
consists of an array of fields.

## Field

A field contains characteristics of a specific field of a json object. multiple field types are supported by `vjson`.
list of supported types are:

+ `integer`
+ `float`
+ `string`
+ `boolean`
+ `array`
+ `object`
+ `null`
+ `or`

# How to create a Schema

There are two ways to create a schema.

+ Schema could be declared in code in a declarative manner.
+ Schema could be parsed from a file or string.

## Schema in code

Schema could be declared in code like this:

```go
package main

import "github.com/miladibra10/vjson"

func main() {
	schema := vjson.NewSchema(
		vjson.String("name").Required(),
	)

	jsonString := `
	{
		"name": "James"
	}
	`

	err := schema.ValidateString(jsonString)
	if err != nil {
		panic(err)
	}
}
```

`schema` object contains a string field, named `name`. This code validates `jsonString`.

## Parse Schema
Schema could be parsed from a file or a string. These methods help to parse schema.

+ [ReadFromString(input string)](#parse-schema): receives characteristics of a schema in a string format and returns a schema object and an error.
+ [ReadFromBytes(input []byte)](#parse-schema): receives characteristics of a schema in a byte array format and returns a schema object and an error.
+ [ReadFromFile(filePath string)](#parse-schema): receives file path of json file which contains characteristics of a schema, and returns a schema object and an error.

Format of schema for parsing should be a json like this:
```json
{
  "fields": [
    ...
  ]
}
```
`fields` should contain [field specifications](#fields). 

This code parses a schema from string:

```go
package main

import "github.com/miladibra10/vjson"

func main() {
	schemaStr := `
	{
		"fields": [
			{
				"name": "name",
				"type": "string"
				"required": true
			}
		]
	}
	`
	schema, err := vjson.ReadFromString(schemaStr)
	if err != nil {
		panic(err)
	}

	jsonString := `
	{
		"name": "James"
	}
	`

	err = schema.ValidateString(jsonString)
	if err != nil {
		panic(err)
	}
}
```

`schemaStr` describes the schema and `vjson.ReadFromString(schemaStr)` parses the string and returns a schema object.

`schema` object contains a string field, named `name`. This code validates `jsonString`.

> **Note**: You could Marshal your schema as a json object for backup usages with `json.Marshal` function.

# Fields

## Integer
An integer field could be created in code like this:
```go
vjson.Integer("foo")
```
some validation characteristics could be added to an integer field with chaining some functions:

+ [Required()](#integer) sets the field as a required field. validation will return an error if a required field is not present in json object.
+ [Min(min int)](#integer) forces the integer field to be greater than `min` in validating json object.
+ [Max(max int)](#integer) forces the integer field to be lower than `max` in validating json object.
+ [Positive()](#integer) checks if the value of field is positive.
+ [Negative()](#integer) checks if the value of field is negative.
+ [Range(start, end int)](#integer) adds a range for integer field. the value of json field should be within this range.

integer field could be described by a json for schema parsing.
+ **`name`**: the name of the field
+ **`type`**: type value for integer field must be `integer`
+ `required`: whether the field is required or not
+ `min`: minimum value of field
+ `max`: maximum value of field
+ `positive`: a boolean that describes that a field is positive or negative (`true` for positive and `false` for negative)
+ `ranges`: an array of ranges to be checked in field validation.

### Example
an integer field, named `foo` which is required, minimum value should be 2, maximum value should be 10, should be positive and be within range [3,5] or [6,8] ,could be declared like this:

#### Code
```go
vjson.Integer("foo").Required().Min(2).Max(10).Positive().Range(3,5).Range(6,8)
```

#### File
```json
{
  "name": "foo",
  "type": "integer",
  "required": true,
  "min": 2,
  "max": 10,
  "positive": true,
  "ranges": [
    {
      "start": 3,
      "end": 5
    },
    {
      "start": 6,
      "end": 8
    }
  ]
}
```

## Float
A float field could be created in code like this:
```go
vjson.Float("foo")
```
some validation characteristics could be added to a float field with chaining some functions:

+ [Required()](#float) sets the field as a required field. validation will return an error if a required field is not present in json object.
+ [Min(min float64)](#float) forces the float field to be greater than `min` in validating json object.
+ [Max(max float64)](#float) forces the float field to be lower than `max` in validating json object.
+ [Positive()](#float) checks if the value of field is positive.
+ [Negative()](#float) checks if the value of field is negative.
+ [Range(start, end float64)](#float) adds a range for float field. the value of json field should be within this range.

float field could be described by a json for schema parsing.
+ **`name`**: the name of the field
+ **`type`**: type value for float field must be `float`
+ `required`: whether the field is required or not
+ `min`: minimum value of field
+ `max`: maximum value of field
+ `positive`: a boolean that describes that a field is positive or negative (`true` for positive and `false` for negative)
+ `ranges`: an array of ranges to be checked in field validation.

### Example
a float field, named `foo` which is required, minimum value should be 2.5, maximum value should be 10.5, should be positive and be within range [3,5] or [6,8] ,could be declared like this:

#### Code
```go
vjson.Float("foo").Required().Min(2.5).Max(10.5).Positive().Range(3,5).Range(6,8)
```

#### File
```json
{
  "name": "foo",
  "type": "float",
  "required": true,
  "min": 2.5,
  "max": 10.5,
  "positive": true,
  "ranges": [
    {
      "start": 3,
      "end": 5
    },
    {
      "start": 6,
      "end": 8
    }
  ]
}
```

## String
A string field could be created in code like this:
```go
vjson.String("foo")
```
some validation characteristics could be added to a string field with chaining some functions:

+ [Required()](#string) sets the field as a required field. validation will return an error if a required field is not present in json object.
+ [MinLength(min int)](#string) forces the length of string field to be greater than `min` in validating json object.
+ [MaxLength(max int)](#string) forces the length of string field to be lower than `max` in validating json object.
+ [Format(format string)](#string) gets a `regex` format and checks if value of json object matches the format.
+ [Choices(choice ...string)](#string) checks if the value of string field is equal to one of choices.

float field could be described by a json for schema parsing.
+ **`name`**: the name of the field
+ **`type`**: type value for string field must be `string`
+ `required`: whether the field is required or not
+ `min_length`: minimum length of string value of field
+ `max_length`: maximum length of string value of field
+ `format`: a `regex` format and checks if value of json object matches the format.
+ `choices`: a list of strings that value of field should be equal to one of them.

### Example
a string field, named `foo` which is required, minimum length value should be 2, maximum length value should be 10, should be Equal to one of these values: `first`, `second` could be declared like this:

#### Code
```go
vjson.String("foo").Required().MinLength(2).MaxLength(10).Choices("first", "second")
```

#### File
```json
{
  "name": "foo",
  "type": "string",
  "required": true,
  "min_length": 2,
  "max_length": 10,
  "choices": [
    "first",
    "second"
  ]
}
```

## Boolean
A boolean field could be created in code like this:
```go
vjson.Boolean("foo")
```
some validation characteristics could be added to a boolean field with chaining some functions:

+ [Required()](#boolean) sets the field as a required field. validation will return an error if a required field is not present in json object.
+ [ShouldBe(value bool)](#boolean) forces the value of field be equal to `value`

boolean field could be described by a json for schema parsing.
+ **`name`**: the name of the field
+ **`type`**: type value for boolean field must be `boolean`
+ `required`: whether the field is required or not
+ `value`: a boolean (same sa `ShouldBe` in code) that describes that the value of json field.

### Example
a boolean field, named `foo` which is required, and always should be false, could be declared like this:

#### Code
```go
vjson.Boolean("foo").Required().ShouldBe(false)
```

#### File
```json
{
  "name": "foo",
  "type": "boolean",
  "required": true,
  "value": false
}
```

## Array
An array field could be created in code like this:
```go
vjson.Array("foo", vjson.String("item"))
```
the first argument is the name of array field, and the second one is the field characteristics of each item of array.


some validation characteristics could be added to an array field with chaining some functions:

+ [Required()](#array) sets the field as a required field. validation will return an error if a required field is not present in json object.
+ [MinLength(min int)](#array) forces the length of array field to be greater than `min` in validating json object.
+ [MaxLength(max int)](#array) forces the length of array field to be lower than `max` in validating json object.

array field could be described by a json for schema parsing.
+ **`name`**: the name of the field
+ **`type`**: type value for array field must be `array`
+ `required`: whether the field is required or not
+ `min_length`: minimum length of array
+ `max_length`: maximum length of array
+ `items`: specifications of item fields. could be any field.

### Example
an array field, named `foo` with integer items between [0,20] range, which is required, and its length should be at least 2 and at last 10, could be declared like this:

#### Code
```go
vjson.Array("foo", vjson.Integer("item").Range(0,20)).Required().MinLength(2).MaxLength(10)
```

#### File
```json
{
  "name": "foo",
  "type": "array",
  "required": true,
  "min_length": 2,
  "max_length": 10,
  "items": {
    "name": "item",
    "type": "integer",
    "ranges": [
      {
        "start": 0,
        "end": 20
      }
    ]
  }
}
```

## Object
An object field could be created in code like this:
```go
vjson.Object("foo", vjson.NewSchema(
        /// Fields	
	))
```
the first argument is the name of object field, and the second one is the schema of object value. this feature helps validation of nested json objects


some validation characteristics could be added to an array field with chaining some functions:

+ [Required()](#object) sets the field as a required field. validation will return an error if a required field is not present in json object.

object field could be described by a json for schema parsing.
+ **`name`**: the name of the field
+ **`type`**: type value for object field must be `object`
+ `required`: whether the field is required or not
+ `schema`: schema of object value.

### Example
a required object field, named `foo` which its valid value is an object with `name` and `last_name` required strings, could be declared like this:

#### Code
```go
vjson.Object("foo", vjson.NewSchema(
	vjson.String("name").Required(),
	vjson.String("last_name").Required(),
	)).Required()
```

#### File
```json
{
  "name": "foo",
  "type": "object",
  "required": true,
  "schema": {
    "fields": [
      {
        "name": "name",
        "type": "string",
        "required": true
      },
      {
        "name": "last_name",
        "type": "string",
        "required": true
      }
    ]
  }
}
```

## Null
A null field (a field that its value should be null!) could be created in code like this:
```go
vjson.Null("foo")
```

null field could be described by a json for schema parsing.
+ **`name`**: the name of the field
+ **`type`**: type value for null field must be `null`

### Example
a null field, named `foo`, could be declared like this:

#### Code
```go
vjson.Null("foo")
```

#### File
```json
{
  "name": "foo",
  "type": "null"
}
```

## Or
An Or field could be created in code like this:
```go
vjson.Or("foo", vjson.String("bar"), vjson.Boolean("baz"))
```
The Or field validates if a value matches at least one of the provided field types.

You can provide the field types directly in the constructor, or add them later using the WithFields method.

some validation characteristics could be added to an Or field with chaining some functions:

+ [Required()](#or) sets the field as a required field. validation will return an error if a required field is not present in json object.
+ [WithFields(fields ...Field)](#or) replaces field types to check. The value will be valid if it matches at least one of these field types.

Or field could be described by a json for schema parsing.
+ **`name`**: the name of the field
+ **`type`**: type value for Or field must be `or`
+ `required`: whether the field is required or not

### Example
an Or field, named `foo` which is required, and accepts either a string or a boolean, could be declared like this:

#### Code
```go
vjson.Or("foo", vjson.String("bar"), vjson.Boolean("baz")).Required()
```

Alternatively, you can add fields using the WithFields method:

```go
vjson.Or("foo").Required().WithFields(vjson.String("bar"), vjson.Boolean("baz"))
```

#### File
```json
{
  "name": "foo",
  "type": "or",
  "required": true,
  "fields": [
    {
      "name": "foo",
      "type": "null"
    },
    {
      "name": "foo",
      "type": "string",
      "required": true
    }
  ]
}
```

# Validation
After creating a schema, you can validate your json objects with these methods:

+ [ValidateBytes(input []byte)](#validation): receives a byte array as a json input and validates it. this method returns an error. it would be `nil` if the object is valid, and it will return an error if the input object is not valid.
+ [ValidateString(input string)](#validation): acts like `ValidateBytes` but its argument is string.

# Example
This code validates an object that should have `name` and `age` fields.
```go
package main

import "github.com/miladibra10/vjson"

func main() {
	schema := vjson.NewSchema(
		vjson.String("name").Required(),
		vjson.Integer("age").Positive(),
	)

	jsonString := `
	{
		
  "required": true,
  "value": false"name": "James"
	}
	`

	err := schema.ValidateString(jsonString)
	if err != nil {
		panic(err) // Will not panic
	}

	jsonString = `
	{
		"name": "James",
        "age": 10
	}
	`

	err = schema.ValidateString(jsonString)
	if err != nil {
		panic(err) // Will not panic
	}

	jsonString = `
	{
        "age": 10
	}
	`

	err = schema.ValidateString(jsonString)
	if err != nil {
		panic(err) // Will panic because name field is missing in jsonString
	}

}
```

# Benchmarks

Results of benchmarking validation functions highly depends on types and number of fields.

two simple benchmarks (exists in `schema_test.go` file) with using all features of `vjson` gives this result:

```
goos: linux
goarch: amd64
pkg: github.com/miladibra10/vjson
BenchmarkSchema_ValidateString-8          416664              2792 ns/op
BenchmarkSchema_ValidateBytes-8           431734              2858 ns/op
PASS
ok      github.com/miladibra10/vjson    2.461s
```


vjson

Client-customizable JSON formats for dynamic APIs

# dynjson [![PkgGoDev](https://pkg.go.dev/badge/github.com/cocoonspace/dynjson)](https://pkg.go.dev/github.com/cocoonspace/dynjson) [![Build Status](https://app.travis-ci.com/cocoonspace/dynjson.svg?branch=master)](https://app.travis-ci.com/github/cocoonspace/dynjson) [![Coverage Status](https://coveralls.io/repos/github/cocoonspace/dynjson/badge.svg?branch=master)](https://coveralls.io/github/cocoonspace/dynjson?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/cocoonspace/dynjson)](https://goreportcard.com/report/github.com/cocoonspace/dynjson)

Client-customizable JSON formats for dynamic APIs.

## Introduction

dynjson allow APIs to return only fields selected by the API client:

```
GET https://api.example.com/v1/foos
[{"id":1,foo":1,"bar":2,"baz":3}]

GET https://api.example.com/v1/foos?select=foo
[{"foo":1}]

GET https://api.example.com/v1/foos/1?select=foo
{"foo":1}
```

dynjson mimicks the original struct using the original types and json tags.
The field order is the same as the select parameters.

## Installation

go get github.com/cocoonspace/dynjson

## Examples

```go
type APIResult struct {
    Foo int     `json:"foo"`
    Bar string  `json:"bar"`
}

f := dynjson.NewFormatter()

res := &APIResult{Foo:1, Bar:"bar"}
o, err := f.Format(res, dynjson.FieldsFromRequest(r))
if err != nil {
    // handle error
}
err = json.NewEncoder(w).Encode(o) // {"foo": 1}
```

With struct fields:


```go
type APIResult struct {
    Foo int          `json:"foo"`
    Bar APIIncluded  `json:"bar"`
}

type APIIncluded struct {
    BarFoo int    `json:"barfoo"`
    BarBar string `json:"barbar"`
}

f := dynjson.NewFormatter()

res := &APIResult{Foo: 1, Bar: APIIncluded{BarFoo:1, BarBar: "bar"}}
o, err := f.Format(res, []string{"foo", "bar.barfoo"})
if err != nil {
    // handle error
}
err = json.NewEncoder(w).Encode(o) // {"foo": 1, "bar":{"barfoo": 1}}
```

With slices:

```go
type APIResult struct {
    Foo int     `json:"foo"`
    Bar string  `json:"bar"`
}

f := dynjson.NewFormatter()

res := []APIResult{{Foo: 1, Bar: "bar"}}
o, err := f.Format(res, []string{"foo"})
if err != nil {
    // handle error
}
err = json.NewEncoder(w).Encode(o) // [{"foo": 1}]
```


```go
type APIResult struct {
    Foo int        `json:"foo"`
    Bar []APIItem  `json:"bar"`
}

type APIItem struct {
    BarFoo int    `json:"barfoo"`
    BarBar string `json:"barbar"`
}

f := dynjson.NewFormatter()

res := &APIResult{Foo: 1, Bar: []APIItem{{BarFoo: 1, BarBar: "bar"}}}
o, err := f.Format(res, []string{"foo", "bar.barfoo"})
if err != nil {
    // handle error
}
err = json.NewEncoder(w).Encode(o) // {"foo": 1, "bar":[{"barfoo": 1}]}
```

## Limitations

* Anonymous fields without a json tag (embedded by the Go JSON encoder in the enclosing struct) are not supported,
* Maps are copied as is, you cannot filter map contents using `map_field_name.map_key`.

## Performance impact

```
BenchmarkFormat_Fields
BenchmarkFormat_Fields-8     	 2466639	       480 ns/op	     184 B/op	       7 allocs/op
BenchmarkFormat_NoFields
BenchmarkFormat_NoFields-8   	 5255031	       232 ns/op	      32 B/op	       1 allocs/op
BenchmarkRawJSON
BenchmarkRawJSON-8           	 5351313	       223 ns/op	      32 B/op	       1 allocs/op
```

## Contribution guidelines

Contributions are welcome, as long as:
* unit tests & comments are included,
* no external package is used.

## License

MIT - See LICENSE

dynjson

Contains primitives for marshaling/unmarshalling Unix timestamp/epoch to/from build-in time.Time type in JSON

[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct-single.svg)](https://vshymanskyy.github.io/StandWithUkraine)

# epoch

[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
[![Godoc Reference][godoc-img]][godoc-url] [![build][build-img]][build-url] 
[![codecov][codecov-img]][codecov-url] [![goreportcard][goreportcard-img]][goreportcard-url]

Contains primitives for marshaling/unmarshaling Unix timestamp/epoch to/from built-in time.Time type in JSON.

## Seconds
Seconds since the Epoch(Unix time), e.g.:
```json
  {"timestamp":1136239445}
```
Inherits built-in time.Time type, thus has all it methods, but has custom serializer and
deserializer(converts integer into built-in time.Time and vice versa).

#### Usage Example

```go
package main

import (
	"encoding/json"
	"fmt"

	"github.com/vtopc/epoch"
)

type Request struct {
	Timestamp epoch.Seconds `json:"timestamp"`
}

func main() {
	var v Request
	err := json.Unmarshal([]byte(`{"timestamp":1136239445}`), &v)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%+v\n", v)
	// Output: {Timestamp:2006-01-03 00:04:05 +0200 EET}

	// Also as epoch.Seconds inherits all time.Time's methods one can do next:
	fmt.Println(v.Timestamp.Year())
	// Output: 2006
	fmt.Println(v.Timestamp.UTC().String())
	// Output: 2006-01-02 22:04:05 +0000 UTC
}
```

## Milliseconds
Same as epoch.Seconds, but for Epoch(Unix time) in milliseconds, e.g.:
```json
  {"timestamp":1136239445999}
```

## StrSeconds
Same as epoch.Seconds, but for strings, e.g.:
```json
  {"timestamp":"1136239445"}
```

## StrMilliseconds
Same as epoch.Milliseconds, but for strings, e.g.:
```json
  {"timestamp":"1136239445999"}
```

## FloatMS
Integer part of timestamp represents seconds and fractional - milliseconds since the Epoch(Unix time), 
e.g.:
```json
  {"timestamp":1136239445.999}
```

## Installation
```shell
go get github.com/vtopc/epoch@latest
```
This will update yours go.mod file.

## Additional terms of use for users from russia and Belarus

By using the code provided in these repositories you agree with the following:
* russia has [illegally annexed Crimea in 2014](https://en.wikipedia.org/wiki/Annexation_of_Crimea_by_the_Russian_Federation) and [brought the war in Donbas](https://en.wikipedia.org/wiki/War_in_Donbas) followed by [full-scale invasion of Ukraine in 2022](https://en.wikipedia.org/wiki/2022_Russian_invasion_of_Ukraine).
* russia has brought sorrow and devastations to millions of Ukrainians, killed hundreds of innocent people, damaged thousands of buildings, and forced several million people to flee.
* [Putin khuylo!](https://en.wikipedia.org/wiki/Putin_khuylo!)

Glory to Ukraine! 🇺🇦

[godoc-img]: https://godoc.org/github.com/vtopc/epoch?status.svg
[godoc-url]: https://godoc.org/github.com/vtopc/epoch

[build-img]: https://github.com/vtopc/epoch/workflows/build/badge.svg
[build-url]: https://github.com/vtopc/epoch/actions?query=workflow%3A%22build%22

[codecov-img]: https://codecov.io/gh/vtopc/epoch/branch/master/graph/badge.svg
[codecov-url]: https://codecov.io/gh/vtopc/epoch

[goreportcard-img]: https://goreportcard.com/badge/github.com/vtopc/epoch
[goreportcard-url]: https://goreportcard.com/report/github.com/vtopc/epoch


epoch

For parsing, creating and editing unknown or dynamic JSON in Go

![Gabs](gabs_logo.png "Gabs")

[![pkg.go for Jeffail/gabs][godoc-badge]][godoc-url]

Gabs is a small utility for dealing with dynamic or unknown JSON structures in Go. It's pretty much just a helpful wrapper for navigating hierarchies of `map[string]interface{}` objects provided by the `encoding/json` package. It does nothing spectacular apart from being fabulous.

If you're migrating from version 1 check out [`migration.md`][migration-doc] for guidance.

## Use

### Import

Using modules:

```go
import (
	"github.com/Jeffail/gabs/v2"
)
```

Without modules:

```go
import (
	"github.com/Jeffail/gabs"
)
```

### Parsing and searching JSON

```go
jsonParsed, err := gabs.ParseJSON([]byte(`{
	"outer":{
		"inner":{
			"value1":10,
			"value2":22
		},
		"alsoInner":{
			"value1":20,
			"array1":[
				30, 40
			]
		}
	}
}`))
if err != nil {
	panic(err)
}

var value float64
var ok bool

value, ok = jsonParsed.Path("outer.inner.value1").Data().(float64)
// value == 10.0, ok == true

value, ok = jsonParsed.Search("outer", "inner", "value1").Data().(float64)
// value == 10.0, ok == true

value, ok = jsonParsed.Search("outer", "alsoInner", "array1", "1").Data().(float64)
// value == 40.0, ok == true

gObj, err := jsonParsed.JSONPointer("/outer/alsoInner/array1/1")
if err != nil {
	panic(err)
}
value, ok = gObj.Data().(float64)
// value == 40.0, ok == true

value, ok = jsonParsed.Path("does.not.exist").Data().(float64)
// value == 0.0, ok == false

exists := jsonParsed.Exists("outer", "inner", "value1")
// exists == true

exists = jsonParsed.ExistsP("does.not.exist")
// exists == false
```

### Iterating objects

```go
jsonParsed, err := gabs.ParseJSON([]byte(`{"object":{"first":1,"second":2,"third":3}}`))
if err != nil {
	panic(err)
}

// S is shorthand for Search
for key, child := range jsonParsed.S("object").ChildrenMap() {
	fmt.Printf("key: %v, value: %v\n", key, child.Data().(float64))
}
```

### Iterating arrays

```go
jsonParsed, err := gabs.ParseJSON([]byte(`{"array":["first","second","third"]}`))
if err != nil {
	panic(err)
}

for _, child := range jsonParsed.S("array").Children() {
	fmt.Println(child.Data().(string))
}
```

Will print:

```
first
second
third
```

Children() will return all children of an array in order. This also works on objects, however, the children will be returned in a random order.

### Searching through arrays

If your structure contains arrays you must target an index in your search.

```go
jsonParsed, err := gabs.ParseJSON([]byte(`{"array":[{"value":1},{"value":2},{"value":3}]}`))
if err != nil {
	panic(err)
}
fmt.Println(jsonParsed.Path("array.1.value").String())
```

Will print `2`.

### Generating JSON

```go
jsonObj := gabs.New()
// or gabs.Wrap(jsonObject) to work on an existing map[string]interface{}

jsonObj.Set(10, "outer", "inner", "value")
jsonObj.SetP(20, "outer.inner.value2")
jsonObj.Set(30, "outer", "inner2", "value3")

fmt.Println(jsonObj.String())
```

Will print:

```
{"outer":{"inner":{"value":10,"value2":20},"inner2":{"value3":30}}}
```

To pretty-print:

```go
fmt.Println(jsonObj.StringIndent("", "  "))
```

Will print:

```
{
  "outer": {
    "inner": {
      "value": 10,
      "value2": 20
    },
    "inner2": {
      "value3": 30
    }
  }
}
```

### Generating Arrays

```go
jsonObj := gabs.New()

jsonObj.Array("foo", "array")
// Or .ArrayP("foo.array")

jsonObj.ArrayAppend(10, "foo", "array")
jsonObj.ArrayAppend(20, "foo", "array")
jsonObj.ArrayAppend(30, "foo", "array")

fmt.Println(jsonObj.String())
```

Will print:

```
{"foo":{"array":[10,20,30]}}
```

Working with arrays by index:

```go
jsonObj := gabs.New()

// Create an array with the length of 3
jsonObj.ArrayOfSize(3, "foo")

jsonObj.S("foo").SetIndex("test1", 0)
jsonObj.S("foo").SetIndex("test2", 1)

// Create an embedded array with the length of 3
jsonObj.S("foo").ArrayOfSizeI(3, 2)

jsonObj.S("foo").Index(2).SetIndex(1, 0)
jsonObj.S("foo").Index(2).SetIndex(2, 1)
jsonObj.S("foo").Index(2).SetIndex(3, 2)

fmt.Println(jsonObj.String())
```

Will print:

```
{"foo":["test1","test2",[1,2,3]]}
```

### Converting back to JSON

This is the easiest part:

```go
jsonParsedObj, _ := gabs.ParseJSON([]byte(`{
	"outer":{
		"values":{
			"first":10,
			"second":11
		}
	},
	"outer2":"hello world"
}`))

jsonOutput := jsonParsedObj.String()
// Becomes `{"outer":{"values":{"first":10,"second":11}},"outer2":"hello world"}`
```

And to serialize a specific segment is as simple as:

```go
jsonParsedObj := gabs.ParseJSON([]byte(`{
	"outer":{
		"values":{
			"first":10,
			"second":11
		}
	},
	"outer2":"hello world"
}`))

jsonOutput := jsonParsedObj.Search("outer").String()
// Becomes `{"values":{"first":10,"second":11}}`
```

### Merge two containers

You can merge a JSON structure into an existing one, where collisions will be converted into a JSON array.

```go
jsonParsed1, _ := ParseJSON([]byte(`{"outer":{"value1":"one"}}`))
jsonParsed2, _ := ParseJSON([]byte(`{"outer":{"inner":{"value3":"three"}},"outer2":{"value2":"two"}}`))

jsonParsed1.Merge(jsonParsed2)
// Becomes `{"outer":{"inner":{"value3":"three"},"value1":"one"},"outer2":{"value2":"two"}}`
```

Arrays are merged:

```go
jsonParsed1, _ := ParseJSON([]byte(`{"array":["one"]}`))
jsonParsed2, _ := ParseJSON([]byte(`{"array":["two"]}`))

jsonParsed1.Merge(jsonParsed2)
// Becomes `{"array":["one", "two"]}`
```

### Parsing Numbers

Gabs uses the `json` package under the bonnet, which by default will parse all number values into `float64`. If you need to parse `Int` values then you should use a [`json.Decoder`](https://golang.org/pkg/encoding/json/#Decoder):

```go
sample := []byte(`{"test":{"int":10,"float":6.66}}`)
dec := json.NewDecoder(bytes.NewReader(sample))
dec.UseNumber()

val, err := gabs.ParseJSONDecoder(dec)
if err != nil {
    t.Errorf("Failed to parse: %v", err)
    return
}

intValue, err := val.Path("test.int").Data().(json.Number).Int64()
```

[godoc-badge]: https://godoc.org/github.com/Jeffail/gabs?status.svg
[godoc-url]: https://pkg.go.dev/github.com/Jeffail/gabs/v2
[migration-doc]: ./migration.md


gabs

<p align="center">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="/.github/images/logo-dark.png">
  <source media="(prefers-color-scheme: light)" srcset="/.github/images/logo-light.png">
  <img src="/.github/images/logo-light.png" width="240" alt="GJSON" >
</picture>
<br>
<a href="https://godoc.org/github.com/tidwall/gjson"><img src="https://img.shields.io/badge/api-reference-blue.svg?style=flat-square" alt="GoDoc"></a>
<a href="https://tidwall.com/gjson-play"><img src="https://img.shields.io/badge/%F0%9F%8F%90-playground-9900cc.svg?style=flat-square" alt="GJSON Playground"></a>
<a href="SYNTAX.md"><img src="https://img.shields.io/badge/{}-syntax-33aa33.svg?style=flat-square" alt="GJSON Syntax"></a>
	
</p>

<p align="center">get json values quickly</a></p>

GJSON is a Go package that provides a [fast](#performance) and [simple](#get-a-value) way to get values from a json document.
It has features such as [one line retrieval](#get-a-value), [dot notation paths](#path-syntax), [iteration](#iterate-through-an-object-or-array), and [parsing json lines](#json-lines).

Also check out [SJSON](https://github.com/tidwall/sjson) for modifying json, and the [JJ](https://github.com/tidwall/jj) command line tool.

This README is a quick overview of how to use GJSON, for more information check out [GJSON Syntax](SYNTAX.md).

GJSON is also available for [Python](https://github.com/volans-/gjson-py) and [Rust](https://github.com/tidwall/gjson.rs)

Getting Started
===============

## Installing

To start using GJSON, install Go and run `go get`:

```sh
$ go get -u github.com/tidwall/gjson
```

This will retrieve the library.

## Get a value
Get searches json for the specified path. A path is in dot syntax, such as "name.last" or "age". When the value is found it's returned immediately. 

```go
package main

import "github.com/tidwall/gjson"

const json = `{"name":{"first":"Janet","last":"Prichard"},"age":47}`

func main() {
	value := gjson.Get(json, "name.last")
	println(value.String())
}
```

This will print:

```
Prichard
```
*There's also [GetBytes](#working-with-bytes) for working with JSON byte slices.*

## Path Syntax

Below is a quick overview of the path syntax, for more complete information please
check out [GJSON Syntax](SYNTAX.md).

A path is a series of keys separated by a dot.
A key may contain special wildcard characters '\*' and '?'.
To access an array value use the index as the key.
To get the number of elements in an array or to access a child path, use the '#' character.
The dot and wildcard characters can be escaped with '\\'.

```json
{
  "name": {"first": "Tom", "last": "Anderson"},
  "age":37,
  "children": ["Sara","Alex","Jack"],
  "fav.movie": "Deer Hunter",
  "friends": [
    {"first": "Dale", "last": "Murphy", "age": 44, "nets": ["ig", "fb", "tw"]},
    {"first": "Roger", "last": "Craig", "age": 68, "nets": ["fb", "tw"]},
    {"first": "Jane", "last": "Murphy", "age": 47, "nets": ["ig", "tw"]}
  ]
}
```
```
"name.last"          >> "Anderson"
"age"                >> 37
"children"           >> ["Sara","Alex","Jack"]
"children.#"         >> 3
"children.1"         >> "Alex"
"child*.2"           >> "Jack"
"c?ildren.0"         >> "Sara"
"fav\.movie"         >> "Deer Hunter"
"friends.#.first"    >> ["Dale","Roger","Jane"]
"friends.1.last"     >> "Craig"
```

You can also query an array for the first match by using `#(...)`, or find all 
matches with `#(...)#`. Queries support the `==`, `!=`, `<`, `<=`, `>`, `>=` 
comparison operators and the simple pattern matching `%` (like) and `!%` 
(not like) operators.

```
friends.#(last=="Murphy").first    >> "Dale"
friends.#(last=="Murphy")#.first   >> ["Dale","Jane"]
friends.#(age>45)#.last            >> ["Craig","Murphy"]
friends.#(first%"D*").last         >> "Murphy"
friends.#(first!%"D*").last        >> "Craig"
friends.#(nets.#(=="fb"))#.first   >> ["Dale","Roger"]
```

*Please note that prior to v1.3.0, queries used the `#[...]` brackets. This was
changed in v1.3.0 as to avoid confusion with the new
[multipath](SYNTAX.md#multipaths) syntax. For backwards compatibility, 
`#[...]` will continue to work until the next major release.*

## Result Type

GJSON supports the json types `string`, `number`, `bool`, and `null`. 
Arrays and Objects are returned as their raw json types. 

The `Result` type holds one of these:

```
bool, for JSON booleans
float64, for JSON numbers
string, for JSON string literals
nil, for JSON null
```

To directly access the value:

```go
result.Type           // can be String, Number, True, False, Null, or JSON
result.Str            // holds the string
result.Num            // holds the float64 number
result.Raw            // holds the raw json
result.Index          // index of raw value in original json, zero means index unknown
result.Indexes        // indexes of all the elements that match on a path containing the '#' query character.
```

There are a variety of handy functions that work on a result:

```go
result.Exists() bool
result.Value() interface{}
result.Int() int64
result.Uint() uint64
result.Float() float64
result.String() string
result.Bool() bool
result.Time() time.Time
result.Array() []gjson.Result
result.Map() map[string]gjson.Result
result.Get(path string) Result
result.ForEach(iterator func(key, value Result) bool)
result.Less(token Result, caseSensitive bool) bool
```

The `result.Value()` function returns an `interface{}` which requires type assertion and is one of the following Go types:

```go
boolean >> bool
number  >> float64
string  >> string
null    >> nil
array   >> []interface{}
object  >> map[string]interface{}
```

The `result.Array()` function returns back an array of values.
If the result represents a non-existent value, then an empty array will be returned.
If the result is not a JSON array, the return value will be an array containing one result.

### 64-bit integers

The `result.Int()` and `result.Uint()` calls are capable of reading all 64 bits, allowing for large JSON integers.

```go
result.Int() int64    // -9223372036854775808 to 9223372036854775807
result.Uint() uint64   // 0 to 18446744073709551615
```

## Modifiers and path chaining 

New in version 1.2 is support for modifier functions and path chaining.

A modifier is a path component that performs custom processing on the 
json.

Multiple paths can be "chained" together using the pipe character. 
This is useful for getting results from a modified query.

For example, using the built-in `@reverse` modifier on the above json document,
we'll get `children` array and reverse the order:

```
"children|@reverse"           >> ["Jack","Alex","Sara"]
"children|@reverse|0"         >> "Jack"
```

There are currently the following built-in modifiers:

- `@reverse`: Reverse an array or the members of an object.
- `@ugly`: Remove all whitespace from a json document.
- `@pretty`: Make the json document more human readable.
- `@this`: Returns the current element. It can be used to retrieve the root element.
- `@valid`: Ensure the json document is valid.
- `@flatten`: Flattens an array.
- `@join`: Joins multiple objects into a single object.
- `@keys`: Returns an array of keys for an object.
- `@values`: Returns an array of values for an object.
- `@tostr`: Converts json to a string. Wraps a json string.
- `@fromstr`: Converts a string from json. Unwraps a json string.
- `@group`: Groups arrays of objects. See [e4fc67c](https://github.com/tidwall/gjson/commit/e4fc67c92aeebf2089fabc7872f010e340d105db).
- `@dig`: Search for a value without providing its entire path. See [e8e87f2](https://github.com/tidwall/gjson/commit/e8e87f2a00dc41f3aba5631094e21f59a8cf8cbf).

### Modifier arguments

A modifier may accept an optional argument. The argument can be a valid JSON 
document or just characters.

For example, the `@pretty` modifier takes a json object as its argument. 

```
@pretty:{"sortKeys":true} 
```

Which makes the json pretty and orders all of its keys.

```json
{
  "age":37,
  "children": ["Sara","Alex","Jack"],
  "fav.movie": "Deer Hunter",
  "friends": [
    {"age": 44, "first": "Dale", "last": "Murphy"},
    {"age": 68, "first": "Roger", "last": "Craig"},
    {"age": 47, "first": "Jane", "last": "Murphy"}
  ],
  "name": {"first": "Tom", "last": "Anderson"}
}
```

*The full list of `@pretty` options are `sortKeys`, `indent`, `prefix`, and `width`. 
Please see [Pretty Options](https://github.com/tidwall/pretty#customized-output) for more information.*

### Custom modifiers

You can also add custom modifiers.

For example, here we create a modifier that makes the entire json document upper
or lower case.

```go
gjson.AddModifier("case", func(json, arg string) string {
  if arg == "upper" {
    return strings.ToUpper(json)
  }
  if arg == "lower" {
    return strings.ToLower(json)
  }
  return json
})
```

```
"children|@case:upper"           >> ["SARA","ALEX","JACK"]
"children|@case:lower|@reverse"  >> ["jack","alex","sara"]
```

## JSON Lines

There's support for [JSON Lines](http://jsonlines.org/) using the `..` prefix, which treats a multilined document as an array. 

For example:

```
{"name": "Gilbert", "age": 61}
{"name": "Alexa", "age": 34}
{"name": "May", "age": 57}
{"name": "Deloise", "age": 44}
```

```
..#                   >> 4
..1                   >> {"name": "Alexa", "age": 34}
..3                   >> {"name": "Deloise", "age": 44}
..#.name              >> ["Gilbert","Alexa","May","Deloise"]
..#(name="May").age   >> 57
```

The `ForEachLines` function will iterate through JSON lines.

```go
gjson.ForEachLine(json, func(line gjson.Result) bool{
    println(line.String())
    return true
})
```

## Get nested array values

Suppose you want all the last names from the following json:

```json
{
  "programmers": [
    {
      "firstName": "Janet", 
      "lastName": "McLaughlin", 
    }, {
      "firstName": "Elliotte", 
      "lastName": "Hunter", 
    }, {
      "firstName": "Jason", 
      "lastName": "Harold", 
    }
  ]
}
```

You would use the path "programmers.#.lastName" like such:

```go
result := gjson.Get(json, "programmers.#.lastName")
for _, name := range result.Array() {
	println(name.String())
}
```

You can also query an object inside an array:

```go
name := gjson.Get(json, `programmers.#(lastName="Hunter").firstName`)
println(name.String())  // prints "Elliotte"
```

## Iterate through an object or array

The `ForEach` function allows for quickly iterating through an object or array. 
The key and value are passed to the iterator function for objects.
Only the value is passed for arrays.
Returning `false` from an iterator will stop iteration.

```go
result := gjson.Get(json, "programmers")
result.ForEach(func(key, value gjson.Result) bool {
	println(value.String()) 
	return true // keep iterating
})
```

## Simple Parse and Get

There's a `Parse(json)` function that will do a simple parse, and `result.Get(path)` that will search a result.

For example, all of these will return the same result:

```go
gjson.Parse(json).Get("name").Get("last")
gjson.Get(json, "name").Get("last")
gjson.Get(json, "name.last")
```

## Check for the existence of a value

Sometimes you just want to know if a value exists. 

```go
value := gjson.Get(json, "name.last")
if !value.Exists() {
	println("no last name")
} else {
	println(value.String())
}

// Or as one step
if gjson.Get(json, "name.last").Exists() {
	println("has a last name")
}
```

## Validate JSON

The `Get*` and `Parse*` functions expects that the json is well-formed. Bad json will not panic, but it may return back unexpected results.

If you are consuming JSON from an unpredictable source then you may want to validate prior to using GJSON.

```go
if !gjson.Valid(json) {
	return errors.New("invalid json")
}
value := gjson.Get(json, "name.last")
```

## Unmarshal to a map

To unmarshal to a `map[string]interface{}`:

```go
m, ok := gjson.Parse(json).Value().(map[string]interface{})
if !ok {
	// not a map
}
```

## Working with Bytes

If your JSON is contained in a `[]byte` slice, there's the [GetBytes](https://godoc.org/github.com/tidwall/gjson#GetBytes) function. This is preferred over `Get(string(data), path)`.

```go
var json []byte = ...
result := gjson.GetBytes(json, path)
```

If you are using the `gjson.GetBytes(json, path)` function and you want to avoid converting `result.Raw` to a `[]byte`, then you can use this pattern:

```go
var json []byte = ...
result := gjson.GetBytes(json, path)
var raw []byte
if result.Index > 0 {
    raw = json[result.Index:result.Index+len(result.Raw)]
} else {
    raw = []byte(result.Raw)
}
```

This is a best-effort no allocation sub slice of the original json. This method utilizes the `result.Index` field, which is the position of the raw data in the original json. It's possible that the value of `result.Index` equals zero, in which case the `result.Raw` is converted to a `[]byte`.

## Performance

Benchmarks of GJSON alongside [encoding/json](https://golang.org/pkg/encoding/json/), 
[ffjson](https://github.com/pquerna/ffjson), 
[EasyJSON](https://github.com/mailru/easyjson),
[jsonparser](https://github.com/buger/jsonparser),
and [json-iterator](https://github.com/json-iterator/go)

```
BenchmarkGJSONGet-10             17893731    202.1 ns/op      0 B/op     0 allocs/op
BenchmarkGJSONUnmarshalMap-10     1663548   2157 ns/op     1920 B/op    26 allocs/op
BenchmarkJSONUnmarshalMap-10       832236   4279 ns/op     2920 B/op    68 allocs/op
BenchmarkJSONUnmarshalStruct-10   1076475   3219 ns/op      920 B/op    12 allocs/op
BenchmarkJSONDecoder-10            585729   6126 ns/op     3845 B/op   160 allocs/op
BenchmarkFFJSONLexer-10           2508573   1391 ns/op      880 B/op     8 allocs/op
BenchmarkEasyJSONLexer-10         3000000    537.9 ns/op    501 B/op     5 allocs/op
BenchmarkJSONParserGet-10        13707510    263.9 ns/op     21 B/op     0 allocs/op
BenchmarkJSONIterator-10          3000000    561.2 ns/op    693 B/op    14 allocs/op
```

JSON document used:

```json
{
  "widget": {
    "debug": "on",
    "window": {
      "title": "Sample Konfabulator Widget",
      "name": "main_window",
      "width": 500,
      "height": 500
    },
    "image": { 
      "src": "Images/Sun.png",
      "hOffset": 250,
      "vOffset": 250,
      "alignment": "center"
    },
    "text": {
      "data": "Click Here",
      "size": 36,
      "style": "bold",
      "vOffset": 100,
      "alignment": "center",
      "onMouseUp": "sun1.opacity = (sun1.opacity / 100) * 90;"
    }
  }
}    
```

Each operation was rotated through one of the following search paths:

```
widget.window.name
widget.image.hOffset
widget.text.onMouseUp
```

**

*These benchmarks were run on a MacBook Pro M1 Max using Go 1.22 and can be found [here](https://github.com/tidwall/gjson-benchmarks).*


GJSON

# JayDiff

[![Go Report Card](https://goreportcard.com/badge/github.com/yazgazan/jaydiff)](https://goreportcard.com/report/github.com/yazgazan/jaydiff)
[![GoDoc](https://godoc.org/github.com/yazgazan/jaydiff?status.svg)](https://godoc.org/github.com/yazgazan/jaydiff)
[![Build Status](https://travis-ci.org/yazgazan/jaydiff.svg?branch=master)](https://travis-ci.org/yazgazan/jaydiff)
[![Coverage Status](https://coveralls.io/repos/github/yazgazan/jaydiff/badge.svg?branch=master)](https://coveralls.io/github/yazgazan/jaydiff?branch=master)
[![Maintainability](https://api.codeclimate.com/v1/badges/c6114df1683db0db4fe4/maintainability)](https://codeclimate.com/github/yazgazan/jaydiff/maintainability)

A JSON diff utility.

## Install

### Downloading the compiled binary

- Download the latest version of the binary: [releases](https://github.com/yazgazan/jaydiff/releases)
- extract the archive and place the `jaydiff` binary in your `$PATH`

### From source

- Have go 1.11 or greater installed: [golang.org](https://golang.org/doc/install)
- run `go get -u github.com/yazgazan/jaydiff`

## Usage

```text
Usage:
  jaydiff [OPTIONS] FILE_1 FILE_2

Application Options:
  -i, --ignore=               paths to ignore (glob)
      --indent=               indent string (default: "\t")
  -t, --show-types            show types
      --json                  json-style output
      --ignore-excess         ignore excess keys and array elements
      --ignore-values         ignore scalar's values (only type is compared)
  -r, --report                output report format
      --slice-myers           use myers algorithm for slices
      --stream                treat FILE_1 and FILE_2 as JSON streams
      --stream-lines          read JSON stream line by line (expecting 1 JSON value per line)
      --stream-ignore-excess  ignore excess values in JSON stream
      --stream-validate       compare FILE_2 JSON stream against FILE_1 single value
  -v, --version               print release version

Help Options:
  -h, --help                  Show this help message
```

### Examples

Getting a full diff of two json files:

```diff
$ jaydiff --show-types old.json new.json

 map[string]interface {} map[
     a: float64 42
     b: []interface {} [
         float64 1
-        float64 3
+        float64 5
+        float64 4
     ]
     c: map[string]interface {} map[
-        a: string toto
+        a: string titi
-        b: float64 23
+        b: string 23
     ]
-    e: []interface {} []
-    f: float64 42
     g: []interface {} [1 2 3]
+    h: float64 42
 ]
```

Ignoring fields:

```diff
$ jaydiff --show-types \
    --ignore='.b\[\]' --ignore='.d' --ignore='.c.[ac]' \
      old.json new.json

 map[string]interface {} map[
     a: float64 42
     b: []interface {} [1 3]
     c: map[string]interface {} map[
-        b: float64 23
+        b: string 23
     ]
-    e: []interface {} []
-    f: float64 42
     g: []interface {} [1 2 3]
+    h: float64 42
 ]
```

Report format:

```diff
$ jaydiff --report --show-types old.json new.json

- .b[1]: float64 3
+ .b[1]: float64 5
+ .b[2]: float64 4
- .c.a: string toto
+ .c.a: string titi
- .c.b: float64 23
+ .c.b: string 23
- .e: []interface {} []
- .f: float64 42
+ .h: float64 42
```

JSON-like format:

```diff
$ jaydiff --json old.json new.json

 {
     "a": 42,
     "b": [
         1,
-        3,
+        5,
+        4
     ],
     "c": {
-        "a": "toto",
+        "a": "titi",
-        "b": 23,
+        "b": "23"
     },
-    "e": [],
-    "f": 42,
     "g": [1,2,3],
+    "h": 42
 }
```

Ignore Excess values (useful when checking for backward compatibility):

```diff
$ jaydiff --report --show-types --ignore-excess old.json new.json

- .b[1]: float64 3
+ .b[1]: float64 5
- .c.a: string toto
+ .c.a: string titi
- .c.b: float64 23
+ .c.b: string 23
- .e: []interface {} []
- .f: float64 42
```

Ignore values (type must still match):

```diff
$ jaydiff --report --show-types --ignore-excess --ignore-values old.json new.json

- .c.b: float64 23
+ .c.b: string 23
- .e: []interface {} []
- .f: float64 42
```

JSON streams:

```diff
$ jaydiff --stream --json old.json new.json

 [
      {"foo":"bar"},
     [
         2,
         3,
         4,
         {
+            "v": "some"
         }
     ],
+    {"some":"thing"}
 ]
```

Validating JSON stream types:

```diff
$ jaydiff --ignore-excess --ignore-values --stream-validate --report --show-types base.json stream.json

- [1].bar: float64 4.2
+ [1].bar: string !
```

## Ideas

- JayPatch

Sponsored by [Datumprikker.nl](https://datumprikker.nl)


JayDiff

<h1 align="center">Jettison</h1>
<p align="center"><img src="images/logo.png" height="275px" width="auto" alt="GoCaptain"></p><p align="center">Jettison is a fast and flexible <strong>JSON</strong> encoder for the Go programming language, inspired by <a href="https://github.com/bet365/jingo">bet365/jingo</a>, with a richer features set, aiming at <strong>100%</strong> compatibility with the standard library.</p>
<p align="center">
    <a href="https://pkg.go.dev/github.com/wI2L/jettison?tab=doc"><img src="https://img.shields.io/static/v1?label=godev&message=reference&color=00add8&logo=go"></a>
    <a href="https://goreportcard.com/report/wI2L/jettison"><img src="https://goreportcard.com/badge/github.com/wI2L/fizz"></a>
    <a href="https://travis-ci.org/wI2L/jettison"><img src="https://travis-ci.org/wI2L/jettison.svg?branch=master"></a>
    <a href="https://github.com/wI2L/jettison/actions"><img src="https://github.com/wI2L/jettison/workflows/CI/badge.svg"></a>
    <a href="https://codecov.io/gh/wI2L/jettison"><img src="https://codecov.io/gh/wI2L/jettison/branch/master/graph/badge.svg"/></a>
    <a href="https://github.com/wI2L/jettison/releases"><img src="https://img.shields.io/github/v/tag/wI2L/jettison?color=blueviolet&label=version&sort=semver"></a>
    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
    <a href="https://github.com/avelino/awesome-go"><img src="https://awesome.re/mentioned-badge.svg"></a>
<br>
</p>

---

## Installation

Jettison uses [Go modules](https://github.com/golang/go/wiki/Modules). Releases are tagged according to the _SemVer_ format, prefixed with a `v`, starting from *0.2.0*. You can get the latest release using the following command.

```console
$ go get github.com/wI2L/jettison@latest
```

:warning: From version `v0.7.4`, the package requires [Go 1.17+](https://golang.org/doc/install) to build, due to the usage of the [new build constraints](https://go.googlesource.com/proposal/+/master/design/draft-gobuild.md).

## Key features

- Fast, see [benchmarks](#benchmarks)
- No dynamic memory allocations in hot paths
- Behavior identical to the standard library by default
- No code generation required
- Clear and concise API
- Configurable with opt-in functional options
- Native support for many standard library types, see [improvements](#improvements)
- Custom `AppendMarshaler` interface to avoid allocations
- Extensive testsuite that compares its output against `encoding/json`

## Overview

The goal of Jettision is to take up the idea introduced by the **bet365/jingo** package and build a fully-featured JSON encoder around it, that comply with the behavior of the [encoding/json](https://golang.org/pkg/encoding/json/) package. Unlike the latter, Jettison does not use reflection during marshaling, but only once to create the instruction set for a given type ahead of time. The drawback to this approach requires to instantiate an instruction-set once for each type that needs to be marshaled, but that is overcomed with a package cache.

The package aims to have a behavior similar to that of the standard library for all types encoding and struct tags, meaning that the documentation of the `json.Marshal` [function](https://golang.org/pkg/encoding/json/#Marshal) is applicable for Jettison, with a few exceptions described in this [section](#differences-with-encodingjson). As such, most of the tests compare their output against it to guarantee that.

### Implementation details

The main concept of Jettison consists of using pre-build instructions-set to reduce the cost of using the `reflect` package at runtime. When marshaling a value, a set of _instructions_ is recursively generated for its type, which defines how to iteratively encode it. An _instruction_ is a function or a closure, that have all the information required to read the data from memory using _unsafe_ operations (pointer type conversion, arithmetic...) during the instruction set execution.

### Differences with `encoding/json`

All notable differences with the standard library behavior are listed below. Please note that these might evolve with future versions of the package.

#### Improvements

- The `time.Time` and `time.Duration` types are handled natively. For time values, the encoder doesn't invoke `MarshalJSON` or `MarshalText`, but use the `time.AppendFormat` [function](https://golang.org/pkg/time/#Time.AppendFormat) instead, and write the result to the stream. Similarly, for durations, it isn't necessary to implements the `json.Marshaler` or `encoding.TextMarshaler` interfaces on a custom wrapper type, the encoder uses the result of one of the methods `Minutes`, `Seconds`, `Nanoseconds` or `String`, based on the duration [format](https://godoc.org/github.com/wI2L/jettison#DurationFmt) configured.

- The `sync.Map` type is handled natively. The marshaling behavior is similar to the one of a standard Go `map`. The option `UnsortedMap` can also be used in cunjunction with this type to disable the default keys sort.

- The `omitnil` field tag's option can be used to specify that a field with a nil pointer should be omitted from the encoding. This option has precedence over the `omitempty` option. Note that struct fields that implement the `json.Marshaler` interface will be omitted too, if they return the literal JSON `null` value.

#### Bugs

##### Go1.13 and backward

- Nil map keys values implementing the `encoding.TextMarshaler` interface are encoded as empty strings, while the `encoding/json` package currently panic because of that. See this [issue](https://github.com/golang/go/issues/33675) for more details.<sup>[1]</sup>

- Nil struct fields implementing the `encoding.TextMarshaler` interface are encoded as `null`, while the `encoding/json` package currently panic because of that. See this [issue](https://github.com/golang/go/issues/34235) for more details.<sup>[1]</sup>

<sup>1: The issues mentioned above have had their associated CL merged, and was released with Go 1.14.</sup>

## Usage

### Basic

As stated above, the library behave similarly to the `encoding/json` package. You can simply replace the `json.Marshal` function with `jettison.Marshal`, and expect the same output with better performances.

```go
type X struct {
   A string `json:"a"`
   B int64  `json:"b"`
}
b, err := jettison.Marshal(X{
   A: "Loreum",
   B: 42,
})
if err != nil {
   log.Fatal(err)
}
os.Stdout.Write(b)
```
###### Result
```json
{"a":"Loreum","b":42}
```

### Advanced

If more control over the encoding behavior is required, use the `MarshalOpts` function instead. The second parameter is variadic and accept a list of functional opt-in [options](https://godoc.org/github.com/wI2L/jettison#Option) described below:

|           name           | description                                                                                                                                                                        |
|:------------------------:| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|     **`TimeLayout`**     | Defines the layout used to encode `time.Time` values. The layout must be compatible with the [AppendFormat](https://golang.org/pkg/time/#Time.AppendFormat) method.                |
|   **`DurationFormat`**   | Defines the format used to encode `time.Duration` values. See the documentation of the `DurationFmt` type for the complete list of formats available.                              |
|      **`UnixTime`**      | Encode `time.Time` values as JSON numbers representing Unix timestamps, the number of seconds elapsed since *January 1, 1970 UTC*. This option has precedence over `TimeLayout`.   |
|    **`UnsortedMap`**     | Disables map keys sort.                                                                                                                                                            |
| **`ByteArrayAsString`**  | Encodes byte arrays as JSON strings rather than JSON arrays. The output is subject to the same escaping rules used for JSON strings, unless the option `NoStringEscaping` is used. |
|    **`RawByteSlice`**    | Disables the *base64* default encoding used for byte slices.                                                                                                                       |
|    **`NilMapEmpty`**     | Encodes nil Go maps as empty JSON objects rather than `null`.                                                                                                                      |
|   **`NilSliceEmpty`**    | Encodes nil Go slices as empty JSON arrays rather than `null`.                                                                                                                     |
|  **`NoStringEscaping`**  | Disables string escaping. `NoHTMLEscaping` and `NoUTF8Coercion` are ignored when this option is used.                                                                              |
|   **`NoHTMLEscaping`**   | Disables the escaping of special HTML characters such as `&`, `<` and `>` in JSON strings. This is similar to `json.Encoder.SetEscapeHTML(false)`.                                 |
|   **`NoUTF8Coercion`**   | Disables the replacement of invalid bytes with the Unicode replacement rune in JSON strings.                                                                                       |
|     **`AllowList`**      | Sets a whitelist that represents which fields are to be encoded when marshaling a Go struct.                                                                                       |
|      **`DenyList`**      | Sets a blacklist that represents which fields are ignored during the marshaling of a Go struct.                                                                                    |
|     **`NoCompact`**      | Disables the compaction of JSON output produced by `MarshalJSON` method, and `json.RawMessage` values.                                                                             |
| **`NoNumberValidation`** | Disables the validation of `json.Number` values.                                                                                                                                   |
|    **`WithContext`**     | Sets the `context.Context` to be passed to invocations of `AppendJSONContext` methods.                                                                                             |

Take a look at the [examples](example_test.go) to see these options in action.

## Benchmarks

If you'd like to run the benchmarks yourself, use the following command.

```shell
go get github.com/cespare/prettybench
go test -bench=. | prettybench
```

### Results `-short`

These benchmarks were run 10x (statistics computed with [benchstat](https://godoc.org/golang.org/x/perf/cmd/benchstat)) on a MacBook Pro 15", with the following specs:
```
OS:  macOS Catalina (10.15.7)
CPU: 2.6 GHz Intel Core i7
Mem: 16GB
Go:  go version go1.17 darwin/amd64
Tag: v0.7.2
```

<details><summary>Stats</summary><br><pre>
name                    time/op
Simple/standard-8          573ns ± 1%
Simple/jsoniter-8          547ns ± 0%
Simple/segmentj-8          262ns ± 1%
Simple/jettison-8          408ns ± 1%
Complex/standard-8        11.7µs ± 0%
Complex/jsoniter-8        11.6µs ± 1%
Complex/segmentj-8        7.96µs ± 0%
Complex/jettison-8        5.90µs ± 1%
CodeMarshal/standard-8    6.71ms ± 0%
CodeMarshal/jsoniter-8    6.35ms ± 1%
CodeMarshal/segmentj-8    4.38ms ± 1%
CodeMarshal/jettison-8    5.56ms ± 1%
Map/standard-8            1.83µs ± 1%
Map/jsoniter-8            1.65µs ± 0%
Map/segmentj-8            1.61µs ± 0%
Map/jettison-8             772ns ± 1%
Map/jettison-nosort-8      507ns ± 1%

name                    speed
Simple/standard-8        236MB/s ± 1%
Simple/jsoniter-8        247MB/s ± 0%
Simple/segmentj-8        516MB/s ± 1%
Simple/jettison-8        331MB/s ± 1%
Complex/standard-8      72.9MB/s ± 0%
Complex/jsoniter-8      70.6MB/s ± 0%
Complex/segmentj-8       108MB/s ± 0%
Complex/jettison-8       144MB/s ± 1%
CodeMarshal/standard-8   289MB/s ± 0%
CodeMarshal/jsoniter-8   306MB/s ± 1%
CodeMarshal/segmentj-8   443MB/s ± 1%
CodeMarshal/jettison-8   349MB/s ± 1%
Map/standard-8          46.6MB/s ± 1%
Map/jsoniter-8          51.5MB/s ± 0%
Map/segmentj-8          52.8MB/s ± 0%
Map/jettison-8           110MB/s ± 1%
Map/jettison-nosort-8    168MB/s ± 1%

name                    alloc/op
Simple/standard-8           144B ± 0%
Simple/jsoniter-8           152B ± 0%
Simple/segmentj-8           144B ± 0%
Simple/jettison-8           144B ± 0%
Complex/standard-8        4.05kB ± 0%
Complex/jsoniter-8        3.95kB ± 0%
Complex/segmentj-8        2.56kB ± 0%
Complex/jettison-8          935B ± 0%
CodeMarshal/standard-8    1.97MB ± 0%
CodeMarshal/jsoniter-8    2.00MB ± 0%
CodeMarshal/segmentj-8    1.98MB ± 2%
CodeMarshal/jettison-8    1.98MB ± 2%
Map/standard-8              888B ± 0%
Map/jsoniter-8              884B ± 0%
Map/segmentj-8              576B ± 0%
Map/jettison-8             96.0B ± 0%
Map/jettison-nosort-8       160B ± 0%

name                    allocs/op
Simple/standard-8           1.00 ± 0%
Simple/jsoniter-8           2.00 ± 0%
Simple/segmentj-8           1.00 ± 0%
Simple/jettison-8           1.00 ± 0%
Complex/standard-8          79.0 ± 0%
Complex/jsoniter-8          71.0 ± 0%
Complex/segmentj-8          52.0 ± 0%
Complex/jettison-8          8.00 ± 0%
CodeMarshal/standard-8      1.00 ± 0%
CodeMarshal/jsoniter-8      2.00 ± 0%
CodeMarshal/segmentj-8      1.00 ± 0%
CodeMarshal/jettison-8      1.00 ± 0%
Map/standard-8              19.0 ± 0%
Map/jsoniter-8              14.0 ± 0%
Map/segmentj-8              18.0 ± 0%
Map/jettison-8              1.00 ± 0%
Map/jettison-nosort-8       2.00 ± 0%
</pre></details>

#### Simple [[source](https://github.com/wI2L/jettison/blob/master/bench_test.go#L50)]

Basic payload with fields of type `string`, `int` and `bool`.

![Simple Benchmark Graph](./images/benchmarks/simple.svg)

#### Complex [[source](https://github.com/wI2L/jettison/blob/master/bench_test.go#L65)]

Large payload with a variety of composite Go types, such as `struct`, `map`, `interface`, multi-dimensions `array` and `slice`, with pointer and non-pointer value types.

Please note that this test is somewhat positively influenced by the performances of map marshaling.

![Complex Benchmark Graph](./images/benchmarks/complex.svg)

#### CodeMarshal [[source](https://github.com/wI2L/jettison/blob/master/bench_test.go#L69)]

Borrowed from the `encoding/json` tests. See [testdata/code.json.gz](testdata/code.json.gz).

![CodeMarshal Benchmark Graph](./images/benchmarks/code-marshal.svg)

#### Map [[source](https://github.com/wI2L/jettison/blob/master/bench_test.go#L75)]

Simple `map[string]int` with 6 keys.

![Map Graph](./images/benchmarks/map.svg)

## Credits

This library and its design has been inspired by the work of others at **@bet365** and **@segmentio**.
See the following projects for reference:
- [bet365/jingo](https://github.com/bet365/jingo)
- [segmentio/encoding](https://github.com/segmentio/encoding)

## License

Jettison is licensed under the **MIT** license. See the [LICENSE](LICENSE) file.

This package also uses some portions of code from the Go **encoding/json** package. The associated license can be found in [LICENSE.golang](LICENSE.golang).


jettison

Go bindings based on the JSON API errors reference

# jsonapi-errors [![GoDoc](https://godoc.org/github.com/golang/gddo?status.svg)](http://godoc.org/github.com/AmuzaTkts/jsonapi-errors) [![Build Status](https://travis-ci.org/AmuzaTkts/jsonapi-errors.svg?branch=master)](https://travis-ci.org/AmuzaTkts/jsonapi-errors) [![Coverage Status](https://coveralls.io/repos/github/AmuzaTkts/jsonapi-errors/badge.svg?branch=master)](https://coveralls.io/github/AmuzaTkts/jsonapi-errors?branch=master) [![Go ReportCard](https://goreportcard.com/badge/github.com/AmuzaTkts/jsonapi-errors)](https://goreportcard.com/report/github.com/AmuzaTkts/jsonapi-errors)

This package provides error bindings based on the [JSON API](http://jsonapi.org/format/#errors)
reference.

The package provides two main structs that you can use on your application, the
`Error` and `Bag` structs. When returning errors from your API you should return
a `Bag` containing one or more errors.

```Go
bag := NewBagWithError(502, "Oops =(")
jsonStr, _ := json.Marshal(bag)
```

The above code will return the following JSON structure:

```JSON
{
  "errors": [
    {
      "detail": "Oops =(",
      "status": "502"
    }
  ],
  "status": "502"
}
```

## Multiple errors
This package adds the possibility to add multiple errors with different status
codes. The package will check for the range of the errors and will set the main
status key to the lower bound of the error class.

Eg: If add an error `501` and `502`, the main status key will be `500`.

```Go
bag := NewBag()
bag.AddError(501, "Server Error 1")
bag.AddError(502, "Server Error 2")

jsonStr, _ := json.Marshal(bag)
```

Will return:
```JSON
{
    "errors": [
        {
            "detail": "Server Error 1",
            "status": "501"
        },
        {
            "detail": "Server Error 2",
            "status": "502"
        }
    ],
    "status": "500"
}
```

It's also possible to have errors of different classes(`400` and `500` for example),
in this case the package will silently return `400` as the main status.

```Go
bag := NewBag()
bag.AddError(401, "Client Error 1")
bag.AddError(502, "Server Error 1")

jsonStr, _ := json.Marshal(bag)
```

```JSON
{
    "errors": [
        {
            "detail": "Client Error 1",
            "status": "401"
        },
        {
            "detail": "Server Error 1",
            "status": "502"
        }
    ],
    "status": "400"
}
```


jsonapi-errors

JSON library to expose simple handlers that lets you easily read and write json from various sources

<h1 align="center">JsonHandlers</h1>

<div align="center" id="top"> 
  <img src="https://res.cloudinary.com/dahkenlmo/image/upload/v1678346700/jsonhandlers_hjca2i.png" alt="Json Handlers" />
  &#xa0;
</div>


<p align="center">JSON library to expose simple handlers that lets you easily read and write json from various sources.</p>


[![Build Status](https://github.com/abusomani/jsonhandlers/workflows/build/badge.svg)](https://github.com/abusomani/jsonhandlers/actions)
[![Github top language](https://img.shields.io/github/languages/top/abusomani/jsonhandlers)](https://img.shields.io/github/languages/top/abusomani/jsonhandlers)
[![Github language count](https://img.shields.io/github/languages/count/abusomani/jsonhandlers)](https://img.shields.io/github/languages/count/abusomani/jsonhandlers)
[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/abusomani/jsonhandlers/blob/main/LICENSE)
[![Go Report Card](https://goreportcard.com/badge/github.com/abusomani/jsonhandlers)](https://goreportcard.com/report/github.com/abusomani/jsonhandlers)
[![Go Reference](https://pkg.go.dev/badge/github.com/abusomani/jsonhandlers.svg)](https://pkg.go.dev/github.com/abusomani/jsonhandlers)
[![Repo size](https://img.shields.io/github/repo-size/abusomani/jsonhandlers)](https://shields.io/github/repo-size/abusomani/jsonhandlers)
[![Coverage Status](https://coveralls.io/repos/github/abusomani/jsonhandlers/badge.svg?branch=main)](https://coveralls.io/github/abusomani/jsonhandlers?branch=main)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go#json)


## Prerequisites

A go module where you want to integrate jsonhandlers. To create one, follow this [guide](https://go.dev/doc/tutorial/create-module).

## Installation

```
go get github.com/abusomani/jsonhandlers
```


## Usage

A very useful feature of Go’s import statement are aliases. A common use case for import aliases is to provide a shorter alternative to a library’s package name.

In this example, we save ourselves having to type `jsonhandlers` everytime we want to call one of the library’s functions, we just use `jh` instead.

```
import (
    jh "github.com/abusomani/jsonhandlers"
)
```

## Options

Jsonhandlers package exposes multiple options while creating a new `jsonhandler` to be able to read/write json from sources like Files, Http Requests or Http responses. 


### WithFileHandler

You can use the `WithFileHandler` option to read/write Json from/to a file. For this, you need to create a new jsonhandler with the file handler option.

[Example](./example/operations/file_handling.go) to understand `WithFileHandler` in more detail.

**Sample Code**
```go
package operations

import (
	"fmt"

	"github.com/abusomani/jsonhandlers"
)


func handleFile() {
	jh := jsonhandlers.New(jsonhandlers.WithFileHandler(testFilePath))

	var sch school
	err := jh.Unmarshal(&sch)
}

```

### WithHTTPRequestHandler

You can use the `WithHTTPRequestHandler` option to read Json from a Http Request and to write Json to a Http ResponseWriter. For this, you need to create a new jsonhandler with the Http request handler option.

[Example](./example/operations/http_request_handling.go) to understand `WithHTTPRequestHandler` in more detail.

**Sample Code**
```go
package operations

import (
	"net/http"

	"github.com/abusomani/jsonhandlers"
)

type studentSearchRequest struct {
	Name string
}

type studentSearchResponse struct {
	Info student
}

func HandleHTTPRequest(students []student) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		
    	jh := jsonhandlers.New(jsonhandlers.WithHTTPRequestHandler(w, r))

		var reqBody studentSearchRequest
		_ := jh.Unmarshal(&reqBody)
		

		for _, student := range students {
			// student found
			if student.Name == reqBody.Name {
				
				// write the response using jh.Marshal
				jh.Marshal(studentSearchResponse{
					Info: student,
				})
				return
			}
		}
	})
}

/*
  Sample request to be hit on the localhost server to test WithHTTPRequestHandler functionality.
  curl http://localhost:8080/search -d '{"Name": "Abhishek Somani"}'
*/
```

### WithHTTPResponseHandler

You can use the `WithHTTPResponseHandler` option to read/write Json from/to a Http Response. For this, you need to create a new jsonhandler with the Http response handler option.

[Example](./example/operations/http_response_handling.go) to understand `WithHTTPResponseHandler` in more detail.

**Sample Code**

```go
package operations

import (
	"fmt"
	"log"
	"net/http"

	"github.com/abusomani/jsonhandlers"
)

type user struct {
	Id        int
	FirstName string
	LastName  string
}

type getUsersResponse struct {
	Users []user
}

func HandleHTTPResponse() {
	resp, _ := http.Get("https://dummyjson.com/users")
	jh := jsonhandlers.New(jsonhandlers.WithHTTPResponseHandler(resp))

	var userResp getUsersResponse
	jh.Unmarshal(&userResp)
}

```

## Run examples
To run the examples present in the [example](./example/) folder you need to first checkout this package by doing a `git clone`. Once you have checked out this package, then you can run the [main.go](./example/main.go) using the following command to see all the examples in action:

```
go run example/main.go
```


## License
Licensed under [MIT](./LICENSE)

jsonhandlers

Utilities to handle and query JSON without defining structs in a type safe manner

# JSONIC

[![GoDoc](https://godoc.org/github.com/sinhashubham95/jsonic?status.svg)](https://pkg.go.dev/github.com/sinhashubham95/jsonic)
[![Release](https://img.shields.io/github/v/release/sinhashubham95/jsonic?sort=semver)](https://github.com/sinhashubham95/jsonic/releases)
[![Report](https://goreportcard.com/badge/github.com/sinhashubham95/jsonic)](https://goreportcard.com/report/github.com/sinhashubham95/jsonic)
[![Coverage Status](https://coveralls.io/repos/github/sinhashubham95/jsonic/badge.svg?branch=master)](https://coveralls.io/github/sinhashubham95/jsonic?branch=master)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#json)

`Jsonic` is the complete set of utilities to handle json data. There's no need to define structs anymore. It's completely safe to perform nested queries in the JSON. The strong typed methods part of this library will help you have the desired result without writing any extra code.

## Installation

```shell
go get github.com/sinhashubham95/jsonic
```

## Understanding the query path

`Jsonic` uses a unique and simple way to query the elements in a json. It's easy but unique, so you need to understand the same for using `Jsonic`.

Consider the following json.

```json
{
  "a": {
    "x": "p",
    "arr": [
      {
        "a": "b",
        "c.d": {
          "e": "f"
        }
      }
    ]
  },
  "c": "d",
  "a.x": {
    "y": "q"
  },
  "a.x.y": {
    "z": "r"
  }
}
```

Though, practically such a JSON won't exist, but still `Jsonic` is intelligent enough to handle even this. Go through the below table carefully and it will help you understand the path schema.

|      Path      |                         Result                         | Comments                                                                  |
| :------------: | :----------------------------------------------------: | ------------------------------------------------------------------------- |
| {EMPTY_STRING} |                      entire json                       | empty string returns the entire json if no empty string exists in the key |
|       .        |                      entire json                       | dot returns the entire json if no dot exists in the key                   |
|       a        | {"x": "p", "arr": [{ "a": "b", "c.d": { "e": "f" } }]} | it returns the entire json tree of a                                      |
|      a.x       |                           p                            | multiple options here, but the first preference goes to the tree of a     |
|     a.x.y      |                           q                            | multiple options here, the first preference will be given to a.x          |
|    a.x.y.z     |                           r                            | there is only a single possibility here                                   |
|     a.arr      |          [{ "a": "b", "c.d": { "e": "f" } }]           | it returns the entire array denoting the json tree of a.arr               |
|    a.arr[0]    |           { "a": "b", "c.d": { "e": "f" } }            | it returns the first element of the array                                 |
|   a.arr[0].a   |                           b                            | it returns the element for key a of the first element of array            |
| a.arr[0].c.d.e |                           f                            |                                                                           |

As you would have understood, if there are multiple JSON trees satisfying the path, and the path looks something like this `a.b.c.d`, then the preferences will be in the following order - `a` > `a.b` > `a.b.c` > `a.b.c.d`.

Consider another json.

```json
{
  "": "a",
  ".": "b"
}
```
Here the paths resolve in a different manner.

|      Path      | Result | Comments                                                                  |
| :------------: | :----: | ------------------------------------------------------------------------- |
| {EMPTY_STRING} |   a    | empty string returns the entire json if no empty string exists in the key |
|       .        |   b    | empty string returns the entire json if no empty string exists in the key |

## How to Use?

`Jsonic` allows you to process the JSON bytes. You can create a new instance of `Jsonic` for every JSON you have and you can get the child JSON trees using the set of utilities it provides.

### Create a New Instance

This will create a new instance using the JSON bytes provided as it's data to be used on.

```go
import (
  "github.com/sinhashubham95/jsonic"
)

func New() {
  json := "{\"naruto\": \"rocks\"}"
  j, err := jsonic.New([]byte(json))
  // perform any sort of operations on the json using the instance created
}
```

### Create a child instance

On the `Jsonic` created, you can provide a child path and get a new instance with the child JSON tree satisfying the path provided as it's data.

```go
import (
  "github.com/sinhashubham95/jsonic"
)

func Child() {
  json := "{\"naruto\": \"rocks\"}"
  j, err := jsonic.New([]byte(json))
  if err != nil {
    return
  }
  
  // create a child
  child, err := jsonic.Child("naruto")
  // now if you want to query on the child then use this child instance
}
```

### Get the data at the path

On the `Jsonic` created, you can get the data at the path specified.

```go
import (
  "github.com/sinhashubham95/jsonic"
)

func Get() {
  json := "{\"naruto\": \"rocks\"}"
  j, err := jsonic.New([]byte(json))
  if err != nil {
    return
  }
  
  // get the data
  data, err := jsonic.Get("naruto")
  // this data will have type interface{} with value "rocks"
}
```

### Get typed data at the path

Though using structs is not required with the wonderful set of utilities `Jsonic` provides, but even if you like to use that, it is very simple to get your result cast into the struct you want.

```go
import (
  "github.com/sinhashubham95/jsonic"
)

type Detail struct {
  Name string `json:"name"`
}

func GetTyped() {
  json := "{\"characters\": [{\"name\": \"naruto\"}, {\"name\": \"boruto\"}]}"
  j, err := jsonic.New([]byte(json))
  if err != nil {
    return
  }
  
  // get the data
  var data []Detail
  err := jsonic.GetTyped("characters", &data)
  // this data will contain 2 elements with names as naruto and boruto
}
```

### Other Typed Utilities

Apart from the generic query methods mentioned above, `Jsonic` contains a bunch of others.

```go
import (
  "github.com/sinhashubham95/jsonic"
)

func OtherGetters(j *Jsonic, path string) {
  // primitives
  i, err := j.GetInt(path)                    // int
  i64, err := j.GetInt64(path)                // int64
  f, err := j.GetFloat(path)                  // float32
  f64, err := j.GetFloat64(path)              // float64
  b, err := j.GetBool(path)                   // bool
  s, err := j.GetString(path)                 // string

  // arrays
  a, err := j.GetArray(path)                  // []interface{}
  iArr, err := j.GetIntArray(path)            // []int
  i64Arr, err := j.GetInt64Array(path)        // []int64
  fArr, err := j.GetFloatArray(path)          // []float32
  f64Arr, err := j.GetFloat64Array(path)      // []float64
  bArr, err := j.GetBoolArray(path)           // []bool
  sArr, err := j.GetStringArray(path)         // []string

  // maps
  m, err := j.GetMap(path)                    // map[string]interface{}
  iMap, err := j.GetIntMap(path)              // map[string]int
  i64Map, err := j.GetInt64Map(path)          // map[string]int64
  fMap, err := j.GetFloatMap(path)            // map[string]float32
  f64Map, err := j.GetFloat64Map(path)        // map[string]float64
  bMap, err := j.GetBoolMap(path)             // map[string]bool
  sMap, err := j.GetStringMap(path)           // map[string]string
}
```


jsonic

Performant JSON unmarshalling for flexible use cases

# Marshmallow

![Marshmallow Campfire](https://raw.githubusercontent.com/PerimeterX/marshmallow/assets/campfire.png)

[![CodeQL Status](https://img.shields.io/github/actions/workflow/status/perimeterx/marshmallow/codeql.yml?branch=main&logo=github&label=CodeQL)](https://github.com/PerimeterX/marshmallow/actions/workflows/codeql.yml?query=branch%3Amain++)
[![Run Tests](https://img.shields.io/github/actions/workflow/status/perimeterx/marshmallow/go.yml?branch=main&logo=github&label=Run%20Tests)](https://github.com/PerimeterX/marshmallow/actions/workflows/go.yml?query=branch%3Amain)
[![Dependency Review](https://img.shields.io/github/actions/workflow/status/perimeterx/marshmallow/dependency-review.yml?logo=github&label=Dependency%20Review)](https://github.com/PerimeterX/marshmallow/actions/workflows/dependency-review.yml?query=branch%3Amain)
[![Go Report Card](https://goreportcard.com/badge/github.com/perimeterx/marshmallow)](https://goreportcard.com/report/github.com/perimeterx/marshmallow)
![Manual Code Coverage](https://img.shields.io/badge/coverage-92.6%25-green)
[![Go Reference](https://pkg.go.dev/badge/github.com/perimeterx/marshmallow.svg)](https://pkg.go.dev/github.com/perimeterx/marshmallow)
[![Licence](https://img.shields.io/github/license/perimeterx/marshmallow)](LICENSE)
[![Latest Release](https://img.shields.io/github/v/release/perimeterx/marshmallow)](https://github.com/PerimeterX/marshmallow/releases)
![Top Languages](https://img.shields.io/github/languages/top/perimeterx/marshmallow)
[![Issues](https://img.shields.io/github/issues-closed/perimeterx/marshmallow?color=%238250df&logo=github)](https://github.com/PerimeterX/marshmallow/issues)
[![Pull Requests](https://img.shields.io/github/issues-pr-closed-raw/perimeterx/marshmallow?color=%238250df&label=merged%20pull%20requests&logo=github)](https://github.com/PerimeterX/marshmallow/pulls)
[![Commits](https://img.shields.io/github/last-commit/perimeterx/marshmallow)](https://github.com/PerimeterX/marshmallow/commits/main)
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)

<img align="right" width="200" alt="marshmallow-gopher" src="https://raw.githubusercontent.com/PerimeterX/marshmallow/assets/sticker7.png">

Marshmallow package provides a simple API to perform flexible and performant JSON unmarshalling in Go.

Marshmallow specializes in dealing with **unstructured struct** - when some fields are known and some aren't,
with zero performance overhead nor extra coding needed.
While unmarshalling, marshmallow allows fully retaining the original data and access
it via a typed struct and a dynamic map.

## Contents

- [Install](#install)
- [Usage](#usage)
- [Performance Benchmark And Alternatives](#performance-benchmark-and-alternatives)
- [When Should I Use Marshmallow](#when-should-i-use-marshmallow)
- [API](#api)

## Install

```sh
go get -u github.com/perimeterx/marshmallow
```

## Usage

```go
package main

import (
	"fmt"
	"github.com/perimeterx/marshmallow"
)

func main() {
	v := struct {
		Foo string `json:"foo"`
		Boo []int  `json:"boo"`
	}{}
	result, err := marshmallow.Unmarshal([]byte(`{"foo":"bar","boo":[1,2,3],"goo":12.6}`), &v)
	fmt.Printf("v=%+v, result=%+v, err=%v", v, result, err)
	// Output: v={Foo:bar Boo:[1 2 3]}, result=map[boo:[1 2 3] foo:bar goo:12.6], err=<nil>
}
```

**Examples can be found [here](example_test.go)**

## Performance Benchmark And Alternatives

Marshmallow performs best when dealing with mixed data - when some fields are known and some are unknown.
More info [below](#when-should-i-use-marshmallow).
Other solutions are available for this kind of use case, each solution is explained and documented in the link below.
The full benchmark test can be found
[here](https://github.com/PerimeterX/marshmallow/blob/8c5bba9e6dc0033f4324eca554737089a99f6e5e/benchmark_test.go).

|Benchmark|Iterations|Time/Iteration|Bytes Allocated|Allocations|
|--|--|--|--|--|
|[unmarshall twice](https://github.com/PerimeterX/marshmallow/blob/8c5bba9e6dc0033f4324eca554737089a99f6e5e/benchmark_test.go#L40)|228693|5164 ns/op|1640 B/op|51 allocs/op|
|[raw map](https://github.com/PerimeterX/marshmallow/blob/8c5bba9e6dc0033f4324eca554737089a99f6e5e/benchmark_test.go#L66)|232236|5116 ns/op|2296 B/op|53 allocs/op|
|[go codec](https://github.com/PerimeterX/marshmallow/blob/8c5bba9e6dc0033f4324eca554737089a99f6e5e/benchmark_test.go#L121)|388442|3077 ns/op|2512 B/op|37 allocs/op|
|[marshmallow](https://github.com/PerimeterX/marshmallow/blob/8c5bba9e6dc0033f4324eca554737089a99f6e5e/benchmark_test.go#L16)|626168|1853 ns/op|608 B/op|18 allocs/op|
|[marshmallow without populating struct](https://github.com/PerimeterX/marshmallow/blob/8c5bba9e6dc0033f4324eca554737089a99f6e5e/benchmark_test.go#L162)|678616|1751 ns/op|608 B/op|18 allocs/op|

![marshmallow performance comparison](https://raw.githubusercontent.com/PerimeterX/marshmallow/e45088ca20d4ea5be4143d418d12da63a68d6dfd/performance-chart.svg)

**Marshmallow provides the best performance (up to X3 faster) while not requiring any extra coding.**
In fact, marshmallow performs as fast as normal `json.Unmarshal` call, however, such a call causes loss of data for all
the fields that did not match the given struct. With marshmallow you never lose any data.

|Benchmark|Iterations|Time/Iteration|Bytes Allocated|Allocations|
|--|--|--|--|--|
|[marshmallow](https://github.com/PerimeterX/marshmallow/blob/8c5bba9e6dc0033f4324eca554737089a99f6e5e/benchmark_test.go#L16)|626168|1853 ns/op|608 B/op|18 allocs/op|
|[native library](https://github.com/PerimeterX/marshmallow/blob/8c5bba9e6dc0033f4324eca554737089a99f6e5e/benchmark_test.go#L143)|652106|1845 ns/op|304 B/op|11 allocs/op|
|[marshmallow without populating struct](https://github.com/PerimeterX/marshmallow/blob/8c5bba9e6dc0033f4324eca554737089a99f6e5e/benchmark_test.go#L162)|678616|1751 ns/op|608 B/op|18 allocs/op|

## When Should I Use Marshmallow

Marshmallow is best suited for use cases where you are interested in all the input data, but you have predetermined
information only about a subset of it. For instance, if you plan to reference two specific fields from the data, then
iterate all the data and apply some generic logic. How does it look with the native library:

```go
func isAllowedToDrive(data []byte) (bool, error) {
	result := make(map[string]interface{})
	err := json.Unmarshal(data, &result)
	if err != nil {
		return false, err
	}

	age, ok := result["age"]
	if !ok {
		return false, nil
	}
	a, ok := age.(float64)
	if !ok {
		return false, nil
	}
	if a < 17 {
		return false, nil
	}

	hasDriversLicense, ok := result["has_drivers_license"]
	if !ok {
		return false, nil
	}
	h, ok := hasDriversLicense.(bool)
	if !ok {
		return false, nil
	}
	if !h {
		return false, nil
	}

	for key := range result {
		if strings.Contains(key, "prior_conviction") {
			return false, nil
		}
	}

	return true, nil
}
```

And with marshmallow:

```go
func isAllowedToDrive(data []byte) (bool, error) {
	v := struct {
		Age               int  `json:"age"`
		HasDriversLicense bool `json:"has_drivers_license"`
	}{}
	result, err := marshmallow.Unmarshal(data, &v)
	if err != nil {
		return false, err
	}

	if v.Age < 17 || !v.HasDriversLicense {
		return false, nil
	}

	for key := range result {
		if strings.Contains(key, "prior_conviction") {
			return false, nil
		}
	}

	return true, nil
}
```

## API

Marshmallow exposes two main API functions -
[Unmarshal](https://github.com/PerimeterX/marshmallow/blob/0e0218ab860be8a4b5f57f5ff239f281c250c5da/unmarshal.go#L27)
and
[UnmarshalFromJSONMap](https://github.com/PerimeterX/marshmallow/blob/0e0218ab860be8a4b5f57f5ff239f281c250c5da/unmarshal_from_json_map.go#L37).
While unmarshalling, marshmallow supports the following optional options:

* Setting the mode for handling invalid data using the [WithMode](https://github.com/PerimeterX/marshmallow/blob/0e0218ab860be8a4b5f57f5ff239f281c250c5da/options.go#L30) function.
* Excluding known fields from the result map using the [WithExcludeKnownFieldsFromMap](https://github.com/PerimeterX/marshmallow/blob/457669ae9973895584f2636eabfc104140d3b700/options.go#L50) function. 
* Skipping struct population to boost performance using the [WithSkipPopulateStruct](https://github.com/PerimeterX/marshmallow/blob/0e0218ab860be8a4b5f57f5ff239f281c250c5da/options.go#L41) function.

In order to capture unknown nested fields, structs must implement [JSONDataErrorHandler](https://github.com/PerimeterX/marshmallow/blob/195c994aa6e3e0852601ad9cf65bcddef0dd7479/options.go#L76).
More info [here](https://github.com/PerimeterX/marshmallow/issues/15). 

Marshmallow also supports caching of refection information using 
[EnableCache](https://github.com/PerimeterX/marshmallow/blob/d3500aa5b0f330942b178b155da933c035dd3906/cache.go#L40)
and
[EnableCustomCache](https://github.com/PerimeterX/marshmallow/blob/d3500aa5b0f330942b178b155da933c035dd3906/cache.go#L35).

## Contact and Contribute

Reporting issues and requesting features may be done in our [GitHub issues page](https://github.com/PerimeterX/marshmallow/issues).
Discussions may be conducted in our [GitHub discussions page](https://github.com/PerimeterX/marshmallow/discussions).
For any further questions or comments you can reach us out at [open-source@humansecurity.com](mailto:open-source@humansecurity.com).

Any type of contribution is warmly welcome and appreciated ❤️
Please read our [contribution](CONTRIBUTING.md) guide for more info.

If you're looking for something to get started with, tou can always follow our [issues page](https://github.com/PerimeterX/marshmallow/issues) and look for
[good first issue](https://github.com/PerimeterX/marshmallow/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) and
[help wanted](https://github.com/PerimeterX/marshmallow/issues?q=is%3Aissue+label%3A%22help+wanted%22+is%3Aopen) labels.

## Marshmallow Logo

Marshmallow logo and assets by [Adva Rom](https://www.linkedin.com/in/adva-rom-7a6738127/) are licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />

![Marshmallow Logo](https://raw.githubusercontent.com/PerimeterX/marshmallow/assets/marshmallow.png)


marshmallow

<p align="center">
<img 
    src="logo.png" 
    width="240" height="78" border="0" alt="SJSON">
<br>
<a href="https://godoc.org/github.com/tidwall/sjson"><img src="https://img.shields.io/badge/api-reference-blue.svg?style=flat-square" alt="GoDoc"></a>
</p>

<p align="center">set a json value quickly</p>

SJSON is a Go package that provides a [very fast](#performance) and simple way to set a value in a json document.
For quickly retrieving json values check out [GJSON](https://github.com/tidwall/gjson).

For a command line interface check out [JJ](https://github.com/tidwall/jj).

Getting Started
===============

Installing
----------

To start using SJSON, install Go and run `go get`:

```sh
$ go get -u github.com/tidwall/sjson
```

This will retrieve the library.

Set a value
-----------
Set sets the value for the specified path. 
A path is in dot syntax, such as "name.last" or "age". 
This function expects that the json is well-formed and validated. 
Invalid json will not panic, but it may return back unexpected results.
Invalid paths may return an error.

```go
package main

import "github.com/tidwall/sjson"

const json = `{"name":{"first":"Janet","last":"Prichard"},"age":47}`

func main() {
	value, _ := sjson.Set(json, "name.last", "Anderson")
	println(value)
}
```

This will print:

```json
{"name":{"first":"Janet","last":"Anderson"},"age":47}
```

Path syntax
-----------

A path is a series of keys separated by a dot.
The dot and colon characters can be escaped with ``\``.

```json
{
  "name": {"first": "Tom", "last": "Anderson"},
  "age":37,
  "children": ["Sara","Alex","Jack"],
  "fav.movie": "Deer Hunter",
  "friends": [
	{"first": "James", "last": "Murphy"},
	{"first": "Roger", "last": "Craig"}
  ]
}
```
```
"name.last"          >> "Anderson"
"age"                >> 37
"children.1"         >> "Alex"
"friends.1.last"     >> "Craig"
```

The `-1` key can be used to append a value to an existing array:

```
"children.-1"  >> appends a new value to the end of the children array
```

Normally number keys are used to modify arrays, but it's possible to force a numeric object key by using the colon character:

```json
{
  "users":{
    "2313":{"name":"Sara"},
    "7839":{"name":"Andy"}
  }
}
```

A colon path would look like:

```
"users.:2313.name"    >> "Sara"
```

Supported types
---------------

Pretty much any type is supported:

```go
sjson.Set(`{"key":true}`, "key", nil)
sjson.Set(`{"key":true}`, "key", false)
sjson.Set(`{"key":true}`, "key", 1)
sjson.Set(`{"key":true}`, "key", 10.5)
sjson.Set(`{"key":true}`, "key", "hello")
sjson.Set(`{"key":true}`, "key", []string{"hello", "world"})
sjson.Set(`{"key":true}`, "key", map[string]interface{}{"hello":"world"})
```

When a type is not recognized, SJSON will fallback to the `encoding/json` Marshaller.


Examples
--------

Set a value from empty document:
```go
value, _ := sjson.Set("", "name", "Tom")
println(value)

// Output:
// {"name":"Tom"}
```

Set a nested value from empty document:
```go
value, _ := sjson.Set("", "name.last", "Anderson")
println(value)

// Output:
// {"name":{"last":"Anderson"}}
```

Set a new value:
```go
value, _ := sjson.Set(`{"name":{"last":"Anderson"}}`, "name.first", "Sara")
println(value)

// Output:
// {"name":{"first":"Sara","last":"Anderson"}}
```

Update an existing value:
```go
value, _ := sjson.Set(`{"name":{"last":"Anderson"}}`, "name.last", "Smith")
println(value)

// Output:
// {"name":{"last":"Smith"}}
```

Set a new array value:
```go
value, _ := sjson.Set(`{"friends":["Andy","Carol"]}`, "friends.2", "Sara")
println(value)

// Output:
// {"friends":["Andy","Carol","Sara"]
```

Append an array value by using the `-1` key in a path:
```go
value, _ := sjson.Set(`{"friends":["Andy","Carol"]}`, "friends.-1", "Sara")
println(value)

// Output:
// {"friends":["Andy","Carol","Sara"]
```

Append an array value that is past the end:
```go
value, _ := sjson.Set(`{"friends":["Andy","Carol"]}`, "friends.4", "Sara")
println(value)

// Output:
// {"friends":["Andy","Carol",null,null,"Sara"]
```

Delete a value:
```go
value, _ := sjson.Delete(`{"name":{"first":"Sara","last":"Anderson"}}`, "name.first")
println(value)

// Output:
// {"name":{"last":"Anderson"}}
```

Delete an array value:
```go
value, _ := sjson.Delete(`{"friends":["Andy","Carol"]}`, "friends.1")
println(value)

// Output:
// {"friends":["Andy"]}
```

Delete the last array value:
```go
value, _ := sjson.Delete(`{"friends":["Andy","Carol"]}`, "friends.-1")
println(value)

// Output:
// {"friends":["Andy"]}
```

## Performance

Benchmarks of SJSON alongside [encoding/json](https://golang.org/pkg/encoding/json/), 
[ffjson](https://github.com/pquerna/ffjson), 
[EasyJSON](https://github.com/mailru/easyjson),
and [Gabs](https://github.com/Jeffail/gabs)

```
Benchmark_SJSON-8                  	 3000000	       805 ns/op	    1077 B/op	       3 allocs/op
Benchmark_SJSON_ReplaceInPlace-8   	 3000000	       449 ns/op	       0 B/op	       0 allocs/op
Benchmark_JSON_Map-8               	  300000	     21236 ns/op	    6392 B/op	     150 allocs/op
Benchmark_JSON_Struct-8            	  300000	     14691 ns/op	    1789 B/op	      24 allocs/op
Benchmark_Gabs-8                   	  300000	     21311 ns/op	    6752 B/op	     150 allocs/op
Benchmark_FFJSON-8                 	  300000	     17673 ns/op	    3589 B/op	      47 allocs/op
Benchmark_EasyJSON-8               	 1500000	      3119 ns/op	    1061 B/op	      13 allocs/op
```

JSON document used:

```json
{
  "widget": {
    "debug": "on",
    "window": {
      "title": "Sample Konfabulator Widget",
      "name": "main_window",
      "width": 500,
      "height": 500
    },
    "image": { 
      "src": "Images/Sun.png",
      "hOffset": 250,
      "vOffset": 250,
      "alignment": "center"
    },
    "text": {
      "data": "Click Here",
      "size": 36,
      "style": "bold",
      "vOffset": 100,
      "alignment": "center",
      "onMouseUp": "sun1.opacity = (sun1.opacity / 100) * 90;"
    }
  }
}    
```

Each operation was rotated though one of the following search paths:

```
widget.window.name
widget.image.hOffset
widget.text.onMouseUp
```

*These benchmarks were run on a MacBook Pro 15" 2.8 GHz Intel Core i7 using Go 1.7 and can be be found [here](https://github.com/tidwall/sjson-benchmarks)*.

## Contact
Josh Baker [@tidwall](http://twitter.com/tidwall)

## License

SJSON source code is available under the MIT [License](/LICENSE).


SJSON

Write and read JSON from different sources succinctly

Advanced JSON to Go struct conversion. Provides package that can parse multiple JSON documents and create struct to fit them all

# json2go ![Build](https://github.com/m-zajac/json2go/workflows/Build/badge.svg) [![Go Report Card](https://goreportcard.com/badge/github.com/m-zajac/json2go)](https://goreportcard.com/report/github.com/m-zajac/json2go) [![GoDoc](https://godoc.org/github.com/m-zajac/json2go?status.svg)](http://godoc.org/github.com/m-zajac/json2go) [![Coverage](https://img.shields.io/badge/coverage-gocover.io-blue)](https://gocover.io/github.com/m-zajac/json2go) [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

Package json2go provides utilities for creating go type representation from json inputs.

Json2go can be used in various ways:

- CLI tool
- Web page with conversion tool: [https://m-zajac.github.io/json2go](https://m-zajac.github.io/json2go)
- Go package
- VSCode extension: [vsc-json2go](https://marketplace.visualstudio.com/items?itemName=m-zajac.vsc-json2go)

## Why another conversion tool?

There are few tools for converting json to go types available already. But all of which I tried worked correctly with only basic documents. 

The goal of this project is to create types, that are guaranteed to properly unmarshal input data. There are multiple test cases that check marshaling/unmarshaling both ways to ensure generated type is accurate.

Here's the micro acid test if you want to check this or other conversion tools:

```json
[{"date":"2020-10-03T15:04:05Z","text":"txt1","doc":{"x":"x"}},{"date":"2020-10-03T15:05:02Z","_doc":false,"arr":[[1,null,1.23]]},{"bool":true,"doc":{"y":123}}]
```

And correct output with some comments:

```go
type Document []struct {
	Arr  [][]*float64 `json:"arr,omitempty"` // Should be doubly nested array; should be a pointer type because there's null in values.
	Bool *bool        `json:"bool,omitempty"` // Shouldn't be `bool` because when key is missing you'll get false information.
	Date *time.Time   `json:"date,omitempty"` // Could be also `string` or `*string`.
	Doc  *Doc         `json:"doc,omitempty"`  // Should be pointer, because key is not present in all documents in array.
	Doc2 *bool        `json:"_doc,omitempty"` // Attribute for "_doc" key (other that for "doc"!). Type - the same as `Bool` attribute.
	Text *string      `json:"text,omitempty"` // Could be also `string`.
}

type Doc struct {
	X *string `json:"x,omitempty"` // Should be pointer, because key is not present in all documents.
	Y *int    `json:"y,omitempty"` // Should be pointer, because key is not present in all documents.
}
```

## CLI Installation

    go install github.com/m-zajac/json2go/cmd/json2go@latest

## Usage

Json2go can be used as cli tool or as package.

CLI tools can be used directly to create go type from stdin data (see examples).

Package provides Parser, which can consume multiple jsons and outputs go type fitting all inputs (see examples and [documentation](https://godoc.org/github.com/m-zajac/json2go)). Example usage: read documents from document-oriented database and feed them too parser for go struct.

### CLI usage examples

    echo '{"x":1,"y":2}' | json2go

---

    curl -s https://api.punkapi.com/v2/beers?page=1&per_page=5 | json2go

Check this one :)

---

    cat data.json | json2go

### Package usage examples

```go
inputs := []string{
	`{"x": 123, "y": "test", "z": false}`,
	`{"a": 123, "x": 12.3, "y": true}`,
}

parser := json2go.NewJSONParser("Document")
for _, in := range inputs {
	parser.FeedBytes([]byte(in))
}

res := parser.String()
fmt.Println(res)
```

## Example outputs

```json
{
    "line": {
        "point1": {
            "x": 12.1,
            "y": 2
        },
        "point2": {
            "x": 12.1,
            "y": 2
        }
    }
}
```
```go
type Document struct {
	Line Line `json:"line"`
}

type Point struct {
	X float64 `json:"x"`
	Y int     `json:"y"`
}

type Line struct {
	Point1 Point `json:"point1"`
	Point2 Point `json:"point2"`
}
```

---

```json
[
    {
        "name": "water",
        "type": "liquid",
        "boiling_point": {
            "units": "C",
            "value": 100
        }
    },
    {
        "name": "oxygen",
        "type": "gas",
        "density": {
            "units": "g/L",
            "value": 1.429
        }
    },
    {
        "name": "carbon monoxide",
        "type": "gas",
        "dangerous": true,
        "boiling_point": {
            "units": "C",
            "value": -191.5
        },
        "density": {
            "units": "kg/m3",
            "value": 789
        }
    }
]
```
```go
type Document []struct {
	BoilingPoint *UnitsValue `json:"boiling_point,omitempty"`
	Dangerous    *bool       `json:"dangerous,omitempty"`
	Density      *UnitsValue `json:"density,omitempty"`
	Name         string      `json:"name"`
	Type         string      `json:"type"`
}

type UnitsValue struct {
	Units string  `json:"units"`
	Value float64 `json:"value"`
}
```

## Contribution

I'd love your input! Especially reporting bugs and proposing new features.


json2go

# gjo

[![GitHub Actions status](https://github.com/skanehira/gjo/workflows/Go/badge.svg)](https://github.com/skanehira/gjo/actions)
[![CircleCI](https://img.shields.io/circleci/project/github/skanehira/gjo/master.svg)](https://circleci.com/gh/skanehira/gjo/tree/master)
[![Go Report Card](https://goreportcard.com/badge/github.com/skanehira/gjo)](https://goreportcard.com/report/github.com/skanehira/gjo)

Small utility to create JSON objects.  
This was inspired by [jpmens/jo](https://github.com/jpmens/jo).

![sreenshot](./screenshot.png)

## Support OS
- Mac
- Linux
- Windows

## Requirements
- Go 1.1.14~
- Git

## Installtion
### Build
```sh
$ git clone https://github.com/skanehira/gjo.git
$ cd gjo
$ GO111MODULE=on go install
```

### Binary
Please download from [releases](https://github.com/skanehira/gjo/releases)

## Usage
### Mac and Linux
```sh
$ gjo -p status=$(gjo name=gorilla age=26 lang=$(gjo -a Go Java PHP))
{
    "status": {
        "age": 26,
        "lang": [
            "Go",
            "Java",
            "PHP"
        ],
        "name": "gorilla"
    }
}
$ gjo -h
Usage of gjo:
  -a    creates an array of words
  -p    pretty-prints
  -v    show version
```

### Windows
If you want to use `$()` on the Windows, please install [shellwrap](https://github.com/mattn/shellwrap).

```sh
shellwrap gjo -p status=$(gjo name=gorilla age=26)
```

## Author
gorilla0513


Go-JsonError is meant to allow us to easily create json response errors that follow the JsonApi spec

# Go-JsonError
[![Go Report Card](https://goreportcard.com/badge/github.com/ddymko/go-jsonerror)](https://goreportcard.com/report/github.com/ddymko/go-jsonerror) [![Build Status](https://travis-ci.org/ddymko/go-jsonerror.svg?branch=master)](https://travis-ci.org/ddymko/go-jsonerror) [![Coveragestatus](https://codecov.io/gh/ddymko/go-jsonerror/branch/master/graph/badge.svg)](https://codecov.io/github/ddymko/go-jsonerror?branch=master)
[![GoDoc](https://godoc.org/github.com/ddymko/go-jsonerror?status.svg)](https://godoc.org/github.com/ddymko/go-jsonerror)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)  

Go-JsonError is meant to allow us to easily create json response errors that follow the JsonApi spec.

[Json API Spec](https://jsonapi.org/format/#errors)

## Usuage

In order to use jsonError you will need to initliaze the ErrorJson struct. Then when you would like to add an error you must pass in a ErrorComp struct to the AddError().

This follows the jsonapi spec where the error response must return an array.

Here is a basic example

``` go
	var err ErrorJSON

	errorComposition := ErrorComp{
		Detail: "this is a error message",
		Code:   "This is the code",
		Source: Source{
			Pointer: "/unit/tests",
		},
		Title:  "Title Test",
		Status: 200,
	}

	err.AddError(errorComposition)

	err.Error()
	err.ErrorByte()
```



## Running the tests

This package is just using the standard test packge included with go. You can run the test cases with

``` sh
go test ./...
```


## Contributing

Please feel free to submit any pull requests.

## Versioning

We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/ddymko/go-jsonerror/tags).

## Authors

* **David Dymko**


## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details



go-jsonerror

# gojq
JSON query in Golang.

## Install
`go get -u github.com/elgs/gojq`

This library serves three purposes:

* makes parsing JSON configuration file much easier
* enables JSON expression evaluation
* reduces the pain of type assertion parsing JSON 


## Query from JSON Object
```go
package main

import (
	"fmt"

	"github.com/elgs/gojq"
)

var jsonObj = `
{
  "name": "sam",
  "gender": "m",
  "pet": null,
  "skills": [
    "Eating",
    "Sleeping",
    "Crawling"
  ],
  "hello.world":true
}
`

func main() {
	parser, err := gojq.NewStringQuery(jsonObj)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(parser.Query("name"))          // sam <nil>
	fmt.Println(parser.Query("gender"))        // m <nil>
	fmt.Println(parser.Query("skills.[1]"))    // Sleeping <nil>
	fmt.Println(parser.Query("hello"))         // <nil> hello does not exist.
	fmt.Println(parser.Query("pet"))           // <nil> <nil>
	fmt.Println(parser.Query("."))             // map[name:sam gender:m pet:<nil> skills:[Eating Sleeping Crawling] hello.world:true] <nil>
	fmt.Println(parser.Query("'hello.world'")) // true <nil>
}

```

## Query from JSON Array
```go
package main

import (
	"fmt"
	"github.com/elgs/gojq"
)

var jsonArray = `
[
  {
    "name": "elgs",
    "gender": "m",
    "skills": [
      "Golang",
      "Java",
      "C"
    ]
  },
  {
    "name": "enny",
    "gender": "f",
    "skills": [
      "IC",
      "Electric design",
      "Verification"
    ]
  },
  {
    "name": "sam",
    "gender": "m",
	"pet": null,
    "skills": [
      "Eating",
      "Sleeping",
      "Crawling"
    ]
  }
]
`

func main() {
	parser, err := gojq.NewStringQuery(jsonArray)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(parser.Query("[0].name"))       // elgs <nil>
	fmt.Println(parser.Query("[1].gender"))     // f <nil>
	fmt.Println(parser.Query("[2].skills.[1]")) // Sleeping <nil>
	fmt.Println(parser.Query("[2].hello"))      // <nil> hello does not exist.
	fmt.Println(parser.Query("[2].pet"))        // <nil> <nil>
}
```
## Nested Query
```go
package main

import (
	"fmt"
	"github.com/elgs/gojq"
)

var jsonArray = `
[
  {
    "name": "elgs",
    "gender": "m",
    "skills": [
      "Golang",
      "Java",
      "C"
    ]
  },
  {
    "name": "enny",
    "gender": "f",
    "skills": [
      "IC",
      "Electric design",
      "Verification"
    ]
  },
  {
    "name": "sam",
    "gender": "m",
	"pet": null,
    "skills": [
      "Eating",
      "Sleeping",
      "Crawling"
    ]
  }
]
`

func main() {
	parser, err := gojq.NewStringQuery(jsonArray)
	if err != nil {
		fmt.Println(err)
		return
	}
	samSkills, err := parser.Query("[2].skills")
	fmt.Println(samSkills, err) //[Eating Sleeping Crawling] <nil>
	samSkillParser := gojq.NewQuery(samSkills)
	fmt.Println(samSkillParser.Query("[1]")) //Sleeping <nil>
}
```


gojq

## 🫐 htmljson: rich rendering of JSON as HTML in Go

<p align="center">
  ✨ Sponsored by <a href="https://apps.apple.com/app/id6738306589">NDX AI Shopping Assistant</a>
</p>

[![codecov](https://codecov.io/gh/nikolaydubina/htmljson/branch/master/graph/badge.svg?token=yXmNdIDn8O)](https://codecov.io/gh/nikolaydubina/htmljson)
[![Go Report Card](https://goreportcard.com/badge/github.com/nikolaydubina/htmljson)](https://goreportcard.com/report/github.com/nikolaydubina/htmljson)
[![Go Reference](https://pkg.go.dev/badge/github.com/nikolaydubina/htmljson.svg)](https://pkg.go.dev/github.com/nikolaydubina/htmljson)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/nikolaydubina/htmljson/badge)](https://securityscorecards.dev/viewer/?uri=github.com/nikolaydubina/htmljson)

* pure Go
* no Javascript
* no dependencies
* no `reflect`
* no `fmt`
* 300 LOC
* customizable rendering
* JSON Path for elements access

![](./doc/example-color.png)

```go
// JSON has to be any
var v any
json.Unmarshal(exampleJSON, &v)

htmlPage := htmljson.DefaultPageMarshalerm.Marshal(v)
```

```go
// JSON has to be any
var v any
json.Unmarshal(exampleJSON, &v)

// customize how to render HTML elements
s := htmljson.Marshaler{
    Null:   htmljson.NullHTML,
    Bool:   htmljson.BoolHTML,
    String: htmljson.StringHTML,
    Number: func(k string, v float64, s string) string {
        if k == "$.cakes.strawberry-cake.size" {
            return `<div class="json-value json-number" style="color:red;">` + s + `</div>`
        }
        if v > 10 {
            return `<div class="json-value json-number" style="color:blue;">` + s + `</div>`
        }
        return `<div class="json-value json-number">` + s + `</div>`
    },
    Array: htmljson.DefaultArrayHTML,
    Map:   htmljson.DefaultMapHTML,
    Row:   htmljson.DefaultRowHTML{Padding: 4}.Marshal,
}

m := htmljson.DefaultPageMarshaler
m.Marshaler = &s

// write HTML page
htmlPage := m.Marshal(v)
```

## Related Work

- https://github.com/alecthomas/chroma can render many languages into HTML with syntax highligting


htmljson

High performance zero-allocation JSON iterator

<a href="https://pkg.go.dev/github.com/romshark/jscan/v2">
    <img src="https://godoc.org/github.com/romshark/jscan/v2?status.svg" alt="GoDoc">
</a>
<a href="https://goreportcard.com/report/github.com/romshark/jscan/v2">
    <img src="https://goreportcard.com/badge/github.com/romshark/jscan/v2" alt="GoReportCard">
</a>
<a href='https://coveralls.io/github/romshark/jscan?branch=main'>
    <img src='https://coveralls.io/repos/github/romshark/jscan/badge.svg?branch=main' alt='Coverage Status' />
</a>


# jscan
jscan provides high-performance zero-allocation JSON iterator and validator for Go. This module doesn't provide `Marshal`/`Unmarshal` capabilities *yet*, instead it focuses on highly efficient iteration over JSON data with on-the-fly validation.

An [experimental decoder](https://github.com/romshark/jscan-experimental-decoder) with backward compatibility to [encoding/json](https://pkg.go.dev/encoding/json) is WiP 🧪 and is expected to be introduced together with jscan v3.

jscan is tested against https://github.com/nst/JSONTestSuite, a comprehensive test suite for [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259) compliant JSON parsers.

See [jscan-benchmark](https://github.com/romshark/jscan-benchmark) for benchmark results 🏎️ 🏁.

## Example
https://go.dev/play/p/moP3l9EkebF

```go
package main

import (
	"fmt"

	"github.com/romshark/jscan/v2"
)

func main() {
	j := `{
		"s": "value",
		"t": true,
		"f": false,
		"0": null,
		"n": -9.123e3,
		"o0": {},
		"a0": [],
		"o": {
			"k": "\"v\"",
			"a": [
				true,
				null,
				"item",
				-67.02e9,
				["foo"]
			]
		},
		"a3": [
			0,
			{
				"a3.a3":8
			}
		]
	}`

	err := jscan.Scan(j, func(i *jscan.Iterator[string]) (err bool) {
		fmt.Printf("%q:\n", i.Pointer())
		fmt.Printf("├─ valueType:  %s\n", i.ValueType().String())
		if k := i.Key(); k != "" {
			fmt.Printf("├─ key:        %q\n", k[1:len(k)-1])
		}
		if ai := i.ArrayIndex(); ai != -1 {
			fmt.Printf("├─ arrayIndex: %d\n", ai)
		}
		if v := i.Value(); v != "" {
			fmt.Printf("├─ value:      %q\n", v)
		}
		fmt.Printf("└─ level:      %d\n", i.Level())
		return false // Resume scanning
	})

	if err.IsErr() {
		fmt.Printf("ERR: %s\n", err)
		return
	}
}
```


jscan

Fluent API to make it easier to create Json objects

Jsongo
===================

**Fluent API** to make it easier **to create Json** objects.

[![travis-ci](https://travis-ci.org/ricardolonga/jsongo.svg)](https://travis-ci.org/ricardolonga/jsongo) 
[![codecov](https://codecov.io/gh/ricardolonga/jsongo/branch/master/graph/badge.svg)](https://codecov.io/gh/ricardolonga/jsongo)
[![goreportcard](https://goreportcard.com/badge/github.com/ricardolonga/jsongo)](http://gocover.io/github.com/ricardolonga/jsongo)

Install
-------------
```
go get github.com/ricardolonga/jsongo
```

Usage
-------------
To create this:  
```
{  
    "name":"Ricardo Longa",
    "idade":28,
    "owner":true,
    "skills":[  
        "Golang",
        "Android"
    ]
}
```  
Do this:  
```
import (
    j "github.com/ricardolonga/jsongo"
)

json := j.Object().Put("name", "Ricardo Longa").
				   Put("idade", 28).
				   Put("owner", true).
				   Put("skills", j.Array().Put("Golang").
									       Put("Android"))

log.Println(json.Indent())
log.Println(json.String())
```
##### Convert object/array to indented String:
```
json.Indent()
```
##### Convert object/array to String:
```
json.String()
```
##### To remove a field of the object:
```
json.Remove("skills")
```
##### To get a field of the object:
```
json.Get("skills") // Return is interface{}.
```
##### To range over a array:
```
results := Array().Put("Golang").Put("Android").Put("Java")

for i, result := range results.Array() {
}
```
##### To get Array size:
```
array := j.Array().Put("Android").
                   Put("Golang").
                   Put("Java")
                   
array.Size() // Result is 3.
```

Copyright
-------------
Copyright (c) 2015 Ricardo Longa.  
Jsongo is licensed under the **Apache License Version 2.0**. See the LICENSE file for more information.


jsongo

A fast and convenient library for unstructured JSON data, replacing `encoding/json`

# Jsonvalue - A Fast and Convenient Alternation of Go map[string]interface{}

[![Workflow](https://github.com/Andrew-M-C/go.jsonvalue/actions/workflows/go_test_general.yml/badge.svg)](https://github.com/Andrew-M-C/go.jsonvalue/actions/workflows/go_test_general.yml)
[![codecov](https://codecov.io/gh/Andrew-M-C/go.jsonvalue/branch/dev/github_workflow/graph/badge.svg?token=REDI4YDLPR&date=221104)](https://codecov.io/gh/Andrew-M-C/go.jsonvalue)
[![Go report](https://goreportcard.com/badge/github.com/Andrew-M-C/go.jsonvalue?date=221104)](https://goreportcard.com/report/github.com/Andrew-M-C/go.jsonvalue)

[![GoDoc](https://godoc.org/github.com/Andrew-M-C/go.jsonvalue?status.svg&date=221104)](https://pkg.go.dev/github.com/Andrew-M-C/go.jsonvalue@v1.4.3)
[![Latest](https://img.shields.io/badge/latest-v1.4.3-blue.svg?date=221104)](https://github.com/Andrew-M-C/go.jsonvalue/tree/v1.4.3)
[![License](https://img.shields.io/badge/license-MIT-blue.svg?date=221104)](https://opensource.org/license/MIT)

[![Author](https://img.shields.io/badge/Author-Andrew.M.C-blue.svg?date=221104)](https://andrewmc.io/post/)
![GitHub personal stars](https://img.shields.io/github/stars/Andrew-M-C)

- [Wiki](./docs/en/README.md)
- [中文](./docs/zh-cn/README.md)
- [日本語](./docs/ja/README.md)

Package **jsonvalue** is for handling unstructured JSON data or customizing JSON marshaling. It is far more faster and convenient than using `interface{}` with `encoding/json`.

Please refer to [pkg site](https://pkg.go.dev/github.com/Andrew-M-C/go.jsonvalue) or [wiki](./docs/en/README.md) for detailed usage and examples.

Especially, please check for jsonvalue's [programming scenarios](./docs/en/10_scenarios.md).

## Import

Use following statements to import jsonvalue:

```go
import (
	jsonvalue "github.com/Andrew-M-C/go.jsonvalue"
)
```

## Quick Start

Sometimes we want to create a complex JSON object like:

```json
{
  "someObject": {
    "someObject": {
      "someObject": {
        "message": "Hello, JSON!"
      }
    }
  }
}
```

With `jsonvalue`, It is quite simple to implement this:

```go
	v := jsonvalue.NewObject()
	v.MustSet("Hello, JSON").At("someObject", "someObject", "someObject", "message")
	fmt.Println(v.MustMarshalString())
	// Output:
	// {"someObject":{"someObject":{"someObject":{"message":"Hello, JSON!"}}}
```

Similarly, it is quite easy to create sub-arrays like:

```json
[
  {
    "someArray": [
      "Hello, JSON!"
    ]
  }
]
```

```go
	v := jsonvalue.NewArray()
	v.MustSet("Hello, JSON").At(0, "someObject", 0)
	fmt.Println(v.MustMarshalString())
	// Output:
	// [{"someObject":["Hello, JSON"]}]
```

In opposite, to parse and read the first JSON above, you can use jsonvalue like this:

```go
	const raw = `{"someObject": {"someObject": {"someObject": {"message": "Hello, JSON!"}}}}`
	s := jsonvalue.MustUnmarshalString(s).GetString("someObject", "someObject", "someObject", "message")
	fmt.Println(s)
	// Output:
	// Hello, JSON!
```

However, it is quite complex and annoying in automatically creating array. I strongly suggest using `SetArray()` to create the array first, then use `Append()` or `Insert()` to set array elements. Please refer go [godoc](https://godoc.org/github.com/Andrew-M-C/go.jsonvalue) or [Wiki](./docs/en/README.md).


jsonvalue

Go MapSlice for ordered marshal/ unmarshal of maps in JSON

[![GoDoc](https://godoc.org/github.com/ake-persson/mapslice-json?status.svg)](https://godoc.org/github.com/ake-persson/mapslice-json)
[![Go Report Card](https://goreportcard.com/badge/github.com/ake-persson/mapslice-json)](https://goreportcard.com/report/github.com/ake-persson/mapslice-json)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/ake-persson/mapslice-json/blob/master/LICENSE)
[![Coverage Status](https://coveralls.io/repos/github/ake-persson/mapslice-json/badge.svg?branch=master)](https://coveralls.io/github/ake-persson/mapslice-json?branch=master)
[![Build Status](https://travis-ci.org/ake-persson/mapslice-json.svg?branch=master)](https://travis-ci.org/ake-persson/mapslice-json)

# mapslice-json

Go MapSlice for ordered marshal/ unmarshal of maps in JSON

# Example

```go
package main

import (
	"encoding/json"
	"fmt"
	"log"

	"github.com/ake-persson/mapslice-json"
)

func main() {
	ms := mapslice.MapSlice{
		mapslice.MapItem{Key: "abc", Value: 123},
		mapslice.MapItem{Key: "def", Value: 456},
		mapslice.MapItem{Key: "ghi", Value: 789},
	}

	b, err := json.Marshal(ms)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(b))

	ms = mapslice.MapSlice{}
	if err := json.Unmarshal(b, &ms); err != nil {
		log.Fatal(err)
	}

	fmt.Println(ms)
}
```


mapslice-json

Simple cli email parser. It currently takes stdin and outputs JSON

mp - mail parser [![Build Status](https://travis-ci.org/sanbornm/mp.svg?branch=master)](https://travis-ci.org/sanbornm/mp)
==

mp is a simple cli email parser.  It currently takes stdin and outputs JSON.

Example:

```
cat fixtures/test.eml | mp
```

```
{
  "Text": "Hello world!",
  "Html": "\u003cb\u003eHello world!\u003c/b\u003e",
  "Headers": {
    "Content-Type": "multipart/mixed; boundary=\"----mailcomposer-?=_1-1402581589619\"",
    "From": "\"Me\" \u003cme@domain.com\u003e",
    "Mime-Version": "1.0",
    "To": "\"First Receiver\" \u003cfirst@domain.com\u003e, second@domain.com",
    "X-Mailer": "Nodemailer 1.0"
  },
  "From": [
    {
      "Name": "Me",
      "Address": "me@domain.com"
    }
  ],
  "To": [
    {
      "Name": "First Receiver",
      "Address": "first@domain.com"
    },
    {
      "Name": "",
      "Address": "second@domain.com"
    }
  ],
  "Cc": null,
  "Priority": "normal",
  "Attachments": [
    {
      "ContentType": "text/plain",
      "Filename": "dummyFile.txt",
      "Disposition": "attachment"
    }
  ]
}
```


Simple JSON parser with validation by condition via golang struct fields tags

# omg.jsonParser

[![Go](https://github.com/dedalqq/omg.jsonparser/actions/workflows/go.yml/badge.svg)](https://github.com/dedalqq/omg.jsonparser/actions/workflows/go.yml)
[![Go Reference](https://pkg.go.dev/badge/github.com/dedalqq/omg.jsonparser.svg)](https://pkg.go.dev/github.com/dedalqq/omg.jsonparser)
[![Coverage Status](https://coveralls.io/repos/github/dedalqq/omg.jsonparser/badge.svg?branch=master)](https://coveralls.io/github/dedalqq/omg.jsonparser?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/dedalqq/omg.jsonparser)](https://goreportcard.com/report/github.com/dedalqq/omg.jsonparser)

omg.jsonParser is a simple JSON parser with a simple condition validation. It's a wrapper on standard go JSON lib. With it help you can add the validation condition via golang structure fields tags.

## Example

```go
package main

import (
	"fmt"

	"github.com/dedalqq/omg.jsonparser"
)

func main() {
	jsonData := `{"name": ""}`

	st := struct {
		Name string `json:"name,notEmpty"` // added notEmpty for enable validation for it field
	}{}

	err := jsonparser.Unmarshal([]byte(jsonData), &st)
	if err != nil {
		fmt.Println(err.Error()) // print: value [name] must be not empty
	}
}

```

## Tag struct

```
json:"[name][,option]..."
```

### Tag examples

Here are some the tag examples:

```go
package main

type data struct {
    F1 string   `json:"f1,notEmpty"`          // the field must be not empty but can be "null" or may not exist
    F2 string   `json:"f2,notEmpty,required"` // the field is required and must be not empty but may be the "null" value
    F3 string   `json:"f3,notEmpty,notNull"`  // the field must be not empty and not "null" but may not exist
    F4 []string `json:"f4,notNull,min:3"`     // the field must be not "null" and contains 3 or more items but may not exist
}
```

## Available tags options

| Name        | Types    | Description                                                                            |
| ----------- | -------- | -------------------------------------------------------------------------------------- |
| `required`  | any      | The field must be exist with any value or `null`                                       |
| `notEmpty`  | any      | The field can be not exist but if exist value must be not zero value but can be `null` |
| `notEmpty`  | slice    | The field must have one element or more but may be `null` or not exist                 |
| `notNull`   | any      | The field should not be null, but may not exist                                        |
| `uniq`      | []string | The strings slice must contains only unique strings                                    |
| `min:n`     | slice    | The slice must have `n` items or more                                                  |
| `max:n`     | slice    | The slice must have `n` items or less                                                  |
| `min:n`     | string   | The string must have `n` runes or more                                                 |
| `max:n`     | string   | The string must have `n` runes or less                                                 |
| `min:n`     | int/uint | The value must be equals `n` or more                                                   |
| `max:n`     | int/uint | The value must be equals `n` or less                                                   |


omg.jsonparser

Fast and minimal JSON parser and transformer that works on unstructured JSON

# µjson

[![GoDoc](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](https://pkg.go.dev/github.com/olvrng/ujson)
[![License](http://img.shields.io/badge/license-mit-blue.svg?style=flat-square)](https://raw.githubusercontent.com/olvrng/ujson/master/LICENSE)
[![Go Report Card](https://goreportcard.com/badge/github.com/olvrng/ujson?style=flat-square)](https://goreportcard.com/report/github.com/olvrng/ujson)
[![Github code coverage](https://img.shields.io/badge/code%20coverage-97%25-brightgreen?style=flat-square)](https://gocover.io/github.com/olvrng/ujson)

---

👉 _Checkout the new library for iterating unstructured JSON with [Go1.23 iterator](https://pkg.go.dev/iter#hdr-Iterators) syntax_ 👈

## [ezpkg.io/iter.json](https://ezpkg.io/iter.json) &middot; A Powerful and Efficient Way to Iterate and Manipulate Unstructured JSON in Go

<a href="https://pkg.go.dev/ezpkg.io/iter.json" target="_blank"> <img alt="godoc" src="https://pkg.go.dev/badge/ezpkg.io/iter.json" style="height: 28px"></a>
<a href="https://github.com/ezpkg/iter.json" target="_blank"> <img alt="source" src="https://img.shields.io/badge/GitHub-100000?style=for-the-badge&amp;logo=github&amp;logoColor=white"> </a>

Read more about [iter.json](https://ezpkg.io/iter.json) on [the introduction article](https://olivernguyen.io/w/iter.json/).

Example usage:

```go
package main

import "ezpkg.io/iter.json"

func main() {
    data := `{"id": 12345, "name": "foo", "numbers": ["one", "two"]}`
    // 👇 iterate over the JSON with Go1.23 iterator syntax
    for item, err := range iterjson.Parse([]byte(data)) {
        if err != nil { panic(err) }
        println(item.GetPathString(), item.Key, item.Token, item.Level)
    }
}
```

---

## µjson

_(is now deprecated and replaced by [iter.json](https://ezpkg.io/iter.json))_

A fast and minimal JSON parser and transformer that works on unstructured JSON.
It works by parsing input and calling the given callback function when
encountering each item.

Read more on [the introduction article](https://hackernoon.com/json-a-minimal-json-parser-and-transformer-in-go-8eo34lp).

## Motivation

Sometimes we just want to make some minimal changes to a JSON document, or do
some generic transformations without fully unmarshalling it. For example,
removing [blacklist fields](https://pkg.go.dev/github.com/olvrng/ujson#example-Walk-RemoveBlacklistFields2)
from response JSON. Why spend all the cost on unmarshalling into a `map[string]interface{}`
just to immediate marshal it again.

The following code is taken from [StackOverflow](https://stackoverflow.com/questions/35441254/making-minimal-modification-to-json-data-without-a-structure-in-golang?ref=hackernoon.com):

```json
{
  "responseHeader": {
    "status": 0,
    "QTime": 0,
    "params": {
      "q": "solo",
      "wt": "json"
    }
  },
  "response": {
    "numFound": 2,
    "start": 0,
    "docs": [
      { "name": "foo" },
      { "name": "bar" }
    ]
  }
}
```

With µjson, we can quickly write [a simple
transformation](https://pkg.go.dev/github.com/olvrng/ujson#example-Walk-RemoveBlacklistFields2)
to remove "responseHeader" completely from all responses, once and forever:

```go
func removeBlacklistFields(input []byte) []byte {
blacklistFields := [][]byte{
[]byte(`"responseHeader"`), // note the quotes
}
b := make([]byte, 0, 1024)
err := ujson.Walk(input, func(_ int, key, value []byte) bool {
if len(key) != 0 {
for _, blacklist := range blacklistFields {
if bytes.Equal(key, blacklist) {
// remove the key and value from the output
return false
}
}
}
// write to output
if len(b) != 0 && ujson.ShouldAddComma(value, b[len(b)-1]) {
b = append(b, ',')
}
if len(key) > 0 {
b = append(b, key...)
b = append(b, ':')
}
b = append(b, value...)
return true
})
if err != nil {
panic(err)
}
return b
}
```

The original scenario that leads me to write the package is because of
***int64***. When working in Go and PostgreSQL, I use ***int64*** (instead of
***string***) for ***ids*** because it’s more effective and has enormous space
for randomly generated ids. It’s not as big as UUID, 128 bits, but still big
enough for production use. In PostgreSQL, those ids can be stored as
***bigint*** and being effectively indexed. But for JavaScript, it can only
process integer up to 53 bits (JavaScript has BigInt but that’s a different
story, and using it will make things even more complicated).

So we need to wrap those int64s into strings before sending them to JavaScript.
In Go and PostgreSQL, the JSON is `{"order_id": 12345678}` but JavaScript will
see it as `{"order_id": "12345678"}` (note that the value is quoted). In Go, we
can define a custom type and implement the
[`json.Marshaler`](https://golang.org/pkg/encoding/json/#Marshaler) interface. But
in PostgreSQL, that’s just not possible or too complicated. I wrote a service
that receives JSON from PostgreSQL and converts it to be consumable by
JavaScript. The service also removes some blacklisted keys or does some other
transformations (for example, change `orderId` to `order_id`).

### Example use cases:

1. Walk through unstructured JSON:
    - [Print all keys and values](https://pkg.go.dev/github.com/olvrng/ujson#example-Walk)
    - Extract some values

2. Transform unstructured JSON:
    - [Remove all spaces](https://pkg.go.dev/github.com/olvrng/ujson#example-Walk-Reconstruct)
    - [Reformat](https://pkg.go.dev/github.com/olvrng/ujson#example-Walk-Reformat)
    - [Remove blacklist fields](https://pkg.go.dev/github.com/olvrng/ujson#example-Walk-RemoveBlacklistFields2)
    - [Wrap int64 in string for processing by JavaScript](https://pkg.go.dev/github.com/olvrng/ujson#example-Walk-WrapInt64InString)

without fully unmarshalling it into a `map[string]interface{}`.

See usage and examples on
[pkg.go.dev](https://pkg.go.dev/github.com/olvrng/ujson).

**Important**: *Behaviour is undefined on invalid JSON. Use on trusted input
only. For untrusted input, you may want to run it through
[`json.Valid()`](https://golang.org/pkg/encoding/json/#Valid) first.*

## Usage

The single most important function is [`Walk(input,
callback)`](https://pkg.go.dev/github.com/olvrng/ujson#Walk), which parses the
`input` JSON and call `callback` function for each key/value pair processed.

The callback function is called when an object key/value or an array key is
encountered. It receives 3 params in order: `level`, `key` and `value`.

- `level` is the indentation level of the JSON, if you format it properly. It
  starts from 0. It increases after entering an object or array and decreases
  after leaving.

- `key` is the raw key of the current object or empty otherwise. It can be a
  double-quoted string or empty.

- `value` is the raw value of the current item or a bracket. It can be a string,
  number, boolean, null, or one of the following brackets: `{ } [ ]`.

It’s important to note that `key` and `value` are provided as raw. Strings are
always double-quoted. It’s there for keeping the library fast and ignoring
unnecessary operations. For example, when you only want to reformat the output
JSON properly; you don’t want to unquote those strings and then immediately
quote them again; you just need to output them unmodified. And there are
[`ujson.Unquote()`](https://pkg.go.dev/github.com/olvrng/ujson#Unquote) and
[`ujson.AppendQuote()`](https://pkg.go.dev/github.com/olvrng/ujson#AppendQuote)
when you need to get the original strings.

For valid JSON, values will never be empty. We can test the first byte of value
(`value[0]`) to get its type:

- `n`: Null (`null`)
- `f`, `t`: Boolean (`false`, `true`)
- `0`-`9`, `-`: Number
- `"`: String, see [`Unquote()`](https://pkg.go.dev/github.com/olvrng/ujson#Unquote)
- `[`, `]`: Array
- `{`, `}`: Object

When processing arrays and objects, first the open bracket (`[`, `{`) will be
provided as `value`, followed by its children, and finally the close bracket
(`]`, `}`). When encountering open brackets, You can make the callback function
return `false` to skip the array/object entirely.

## Examples

### 1. Print all keys and values in order

This example gives a quick idea about how *µjson* works.

```go 
 input := []byte(`{  
     "id": 12345,    
     "name": "foo",  
     "numbers": ["one", "two"],  
     "tags": {"color": "red", "priority": "high"},   
     "active": true  
 }`)
ujson.Walk(input, func(level int, key, value []byte) bool {
fmt.Printf("%2v% 12s : %s\n", level, key, value)
return true
})
```

```json
{
  "id": 12345,
  "name": "foo",
  "numbers": ["one", "two"],
  "tags": {"color": "red", "priority": "high"},
  "active": true
}
```

Calling `Walk()` with the above input will produce:

| level | key        | value   |
|:-----:|:----------:|:-------:|
|`0`    |            |`{`      |
|`1`    |`"id"`      |`12345`  |
|`1`    |`"name"`    |`"foo"`  |
|`1`    |`"numbers"` |`[`      |
|`2`    |            |`"one"`  |
|`2`    |            |`"two"`  |
|`1`    |            |`]`      |
|`1`    |`"tags"`    |`{`      |
|`2`    |`"color"`   |`"red"`  |
|`2`    |`"priority"`|`"high"` |
|`1`    |            |`}`      |
|`1`    |`"active"`  |`true`   |
|`0`    |            |`}`      |

### 0. The simplest examples

To easily get an idea on `level`, `key` and `value`, here are the simplest
examples:

```go
 input0 := []byte(`true`)
ujson.Walk(input0, func(level int, key, value []byte) bool {
fmt.Printf("level=%v key=%s value=%s\n", level, key, value)
return true
})
// output:
//   level=0 key= value=true

input1 := []byte(`{ "key": 42 }`)
ujson.Walk(input1, func(level int, key, value []byte) bool {
fmt.Printf("level=%v key=%s value=%s\n", level, key, value)
return true
})
// output:
//   level=0 key= value={
//   level=1 key="key" value=42
//   level=0 key= value=}

input2 := []byte(`[ true ]`)
ujson.Walk(input2, func(level int, key, value []byte) bool {
fmt.Printf("level=%v key=%s value=%s\n", level, key, value)
return true
})
// output:
//   level=0 key= value=[
//   level=1 key= value=true
//   level=0 key= value=]
```

In the first example, there is only a single boolean value. The callback
function is called once with `level=0`, `key` is empty and `value=true`.

In the second example, the callback function is called 3 times. Two times for
open and close brackets with `level=0`, `key` is empty and `value` is the
bracketed character. The other time for the only key with `level=1`, `key` is
`"key"` and `value=42`. Note that the key is quoted and you need to call
[`ujson.Unquote()`](https://pkg.go.dev/github.com/olvrng/ujson#Unquote) to
retrieve the unquoted string.

The last example is like the second, but with an array instead. Keys are always
empty inside arrays.

### 2. Reformat input

In this example, the input JSON is formatted with correct indentation. As
processing the input key by key, the callback function reconstructs the JSON. It
outputs each key/value pair in its own line, prefixed with spaces equal to the
param level. There is a catch, though. Valid JSON requires commas between values
in objects and arrays. So there is
[`ujson.ShouldAddComma()`](https://pkg.go.dev/github.com/olvrng/ujson#ShouldAddComma)
for checking whether a comma should be inserted.

```go
 input := []byte(`{"id":12345,"name":"foo","numbers":["one","two"],"tags":{"color":"red","priority":"high"},"active":true}`)

b := make([]byte, 0, 1024)
err := ujson.Walk(input, func(level int, key, value []byte) bool {
if len(b) != 0 && ujson.ShouldAddComma(value, b[len(b)-1]) {
b = append(b, ',')
}
b = append(b, '\n')
for i := 0; i < level; i++ {
b = append(b, '\t')
}
if len(key) > 0 {
b = append(b, key...)
b = append(b, `: `...)
}
b = append(b, value...)
return true
})
if err != nil {
panic(err)
}
fmt.Printf("%s\n", b)
```

#### Output:

```json
{
  "id": 12345,
  "name": "foo",
  "numbers": [
    "one",
    "two"
  ],
  "tags": {
    "color": "red",
    "priority": "high"
  },
  "active": true
}
```

There is a built-in method
[`ujson.Reconstruct()`](https://pkg.go.dev/github.com/olvrng/ujson?ref=hackernoon.com#Reconstruct)
when you want to remove all the whitespaces.

### 3. Remove blacklisted keys

This example demonstrates removing some keys from the input JSON. The key param
is compared with a pre-defined list. If there is a match, the blacklisted key
and its value are dropped. The callback function returns false for skipping the
entire value (which may be an object or array). Note that the list is quoted,
i.e. "numbers" and "active" instead of number and active. For more advanced
checking, you may want to run [`ujson.Unquote()`](https://pkg.go.dev/github.com/olvrng/ujson#Unquote) on the key.

```go
 input := []byte(`{
     "id": 12345,
     "name": "foo",
     "numbers": ["one", "two"],
     "tags": {"color": "red", "priority": "high"},
     "active": true
 }`)

blacklistFields := [][]byte{
[]byte(`"numbers"`), // note the quotes
[]byte(`"active"`),
}
b := make([]byte, 0, 1024)
err := ujson.Walk(input, func(_ int, key, value []byte) bool {
for _, blacklist := range blacklistFields {
if bytes.Equal(key, blacklist) {
// remove the key and value from the output
return false
}
}

// write to output
if len(b) != 0 && ujson.ShouldAddComma(value, b[len(b)-1]) {
b = append(b, ',')
}
if len(key) > 0 {
b = append(b, key...)
b = append(b, ':')
}
b = append(b, value...)
return true
})
if err != nil {
panic(err)
}
fmt.Printf("%s\n", b)
```

#### Output:

```json
{"id":12345,"name":"foo","tags":{"color":"red","priority":"high"}}
```

### 4. Wrap int64 in string

This is the original motivation behind µjson. The following example finds keys
ending with `_id"` (`"order_id"`, `"item_id"`, etc.) and converts their values
from numbers to strings, by simply wrapping them in double-quotes.

For valid JSON, values will never be empty. We can test the first byte of value
(`value[0]`) to get its type:

- `n`: Null (`null`)
- `f`, `t`: Boolean (`false`, `true`)
- `0`-`9`, `-`: Number
- `"`: String, see [`Unquote()`](https://pkg.go.dev/github.com/olvrng/ujson#Unquote)
- `[`, `]`: Array
- `{`, `}`: Object

In this case, we check `value[0]` within `0`…`9` to see whether it’s a number,
then insert double-quotes.

```go
 input := []byte(`{"order_id": 12345678901234, "number": 12, "item_id": 12345678905678, "counting": [1,"2",3]}`)

suffix := []byte(`_id"`) // note the ending quote "
b := make([]byte, 0, 256)
err := ujson.Walk(input, func(_ int, key, value []byte) bool {
// Test for keys with suffix _id" and value is an int64 number. For valid json,
// values will never be empty, so we can safely test only the first byte.
shouldWrap := bytes.HasSuffix(key, suffix) && value[0] > '0' && value[0] <= '9'

// transform the input, wrap values in double quotes
if len(b) != 0 && ujson.ShouldAddComma(value, b[len(b)-1]) {
b = append(b, ',')
}
if len(key) > 0 {
b = append(b, key...)
b = append(b, ':')
}
if shouldWrap {
b = append(b, '"')
}
b = append(b, value...)
if shouldWrap {
b = append(b, '"')
}
return true
})
if err != nil {
panic(err)
}
fmt.Printf("%s\n", b)
```

#### Output:

```json
{"order_id":"12345678901234","number":12,"item_id":"12345678905678","counting":[1,"2",3]}
```

After processing, the numbers in `"order_id"` and `"item_id"` are quoted as strings. And JavaScript should be happy now! 🎉 🎉

## Author

<a href="https://olivernguyen.io"><img alt="olivernguyen.io" src="https://olivernguyen.io/_/badge.png" height="28px"></a>

## License

MIT


The Best Go Libraries For JSON (38)