gabs

package module
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Feb 18, 2019 License: MIT Imports: 6 Imported by: 0

README

Gabs

Gabs is a small utility for dealing with dynamic or unknown JSON structures in golang. It's pretty much just a helpful wrapper around the golang json.Marshal/json.Unmarshal behaviour and map[string]interface{} objects. It does nothing spectacular except for being fabulous.

https://godoc.org/github.com/Jeffail/gabs

How to install:

go get github.com/Jeffail/gabs

How to use

Parsing and searching JSON

...

import "github.com/Jeffail/gabs"

jsonParsed, err := gabs.ParseJSON([]byte(`{
	"outter":{
		"inner":{
			"value1":10,
			"value2":22
		},
		"alsoInner":{
			"value1":20
		}
	}
}`))

var value float64
var ok bool

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

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

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

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

exists := jsonParsed.Exists("does", "not", "exist")
// exists == false

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

...

Iterating objects

...

jsonParsed, _ := gabs.ParseJSON([]byte(`{"object":{ "first": 1, "second": 2, "third": 3 }}`))

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

...

Iterating arrays

...

jsonParsed, _ := gabs.ParseJSON([]byte(`{"array":[ "first", "second", "third" ]}`))

// S is shorthand for Search
children, _ := jsonParsed.S("array").Children()
for _, child := range 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 JSON structure contains arrays you can still search the fields of the objects within the array, this returns a JSON array containing the results for each element.

...

jsonParsed, _ := gabs.ParseJSON([]byte(`{"array":[ {"value":1}, {"value":2}, {"value":3} ]}`))
fmt.Println(jsonParsed.Path("array.value").String())

...

Will print:

[1,2,3]

Generating JSON

...

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

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

fmt.Println(jsonObj.String())

...

Will print:

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

To pretty-print:

...

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

...

Will print:

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

Generating Arrays

...

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:

...

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:

...

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

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

...

And to serialize a specific segment is as simple as:

...

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

jsonOutput := jsonParsedObj.Search("outter").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.

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

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

Arrays are merged:

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):

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()

Documentation

Overview

Package gabs implements a simplified wrapper around creating and parsing JSON.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrOutOfBounds - Index out of bounds.
	ErrOutOfBounds = errors.New("out of bounds")

	// ErrNotObjOrArray - The target is not an object or array type.
	ErrNotObjOrArray = errors.New("not an object or array")

	// ErrNotObj - The target is not an object type.
	ErrNotObj = errors.New("not an object")

	// ErrNotArray - The target is not an array type.
	ErrNotArray = errors.New("not an array")

	// ErrPathCollision - Creating a path failed because an element collided with an existing value.
	ErrPathCollision = errors.New("encountered value collision whilst building path")

	// ErrInvalidInputObj - The input value was not a map[string]interface{}.
	ErrInvalidInputObj = errors.New("invalid input object")

	// ErrInvalidInputText - The input data could not be parsed.
	ErrInvalidInputText = errors.New("input text could not be parsed")

	// ErrInvalidPath - The filepath was not valid.
	ErrInvalidPath = errors.New("invalid file path")

	// ErrInvalidBuffer - The input buffer contained an invalid JSON string
	ErrInvalidBuffer = errors.New("input buffer contained invalid JSON")
)

Functions

This section is empty.

Types

type Container 

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

Container - an internal structure that holds a reference to the core interface map of the parsed json. Use this container to move context.

func Consume 

func Consume(root interface{}) (*Container, error)

Consume - Gobble up an already converted JSON object, or a fresh map[string]interface{} object.

func New 

func New() *Container

New - Create a new gabs JSON object.

func ParseJSON 

func ParseJSON(sample []byte) (*Container, error)

ParseJSON - Convert a string into a representation of the parsed JSON.

func ParseJSONBuffer 

func ParseJSONBuffer(buffer io.Reader) (*Container, error)

ParseJSONBuffer - Read the contents of a buffer into a representation of the parsed JSON.

func ParseJSONDecoder 

func ParseJSONDecoder(decoder *json.Decoder) (*Container, error)

ParseJSONDecoder - Convert a json.Decoder into a representation of the parsed JSON.

func ParseJSONFile 

func ParseJSONFile(path string) (*Container, error)

ParseJSONFile - Read a file and convert into a representation of the parsed JSON.

func (*Container) Array 

func (g *Container) Array(path ...string) (*Container, error)

Array - Create a new JSON array at a path. Returns an error if the path contains a collision with a non object type.

func (*Container) ArrayAppend 

func (g *Container) ArrayAppend(value interface{}, path ...string) error

ArrayAppend - Append a value onto a JSON array. If the target is not a JSON array then it will be converted into one, with its contents as the first element of the array.

func (*Container) ArrayAppendP 

func (g *Container) ArrayAppendP(value interface{}, path string) error

ArrayAppendP - Append a value onto a JSON array using a dot notation JSON path.

func (*Container) ArrayCount 

func (g *Container) ArrayCount(path ...string) (int, error)

ArrayCount - Count the number of elements in a JSON array.

func (*Container) ArrayCountP 

func (g *Container) ArrayCountP(path string) (int, error)

ArrayCountP - Count the number of elements in a JSON array using a dot notation JSON path.

func (*Container) ArrayElement 

func (g *Container) ArrayElement(index int, path ...string) (*Container, error)

ArrayElement - Access an element from a JSON array.

func (*Container) ArrayElementP 

func (g *Container) ArrayElementP(index int, path string) (*Container, error)

ArrayElementP - Access an element from a JSON array using a dot notation JSON path.

func (*Container) ArrayI 

func (g *Container) ArrayI(index int) (*Container, error)

ArrayI - Create a new JSON array at an array index. Returns an error if the object is not an array or the index is out of bounds.

func (*Container) ArrayOfSize 

func (g *Container) ArrayOfSize(size int, path ...string) (*Container, error)

ArrayOfSize - Create a new JSON array of a particular size at a path. Returns an error if the path contains a collision with a non object type.

func (*Container) ArrayOfSizeI 

func (g *Container) ArrayOfSizeI(size, index int) (*Container, error)

ArrayOfSizeI - Create a new JSON array of a particular size at an array index. Returns an error if the object is not an array or the index is out of bounds.

func (*Container) ArrayOfSizeP 

func (g *Container) ArrayOfSizeP(size int, path string) (*Container, error)

ArrayOfSizeP - Does the same as ArrayOfSize, but using a dot notation JSON path.

func (*Container) ArrayP 

func (g *Container) ArrayP(path string) (*Container, error)

ArrayP - Does the same as Array, but using a dot notation JSON path.

func (*Container) ArrayRemove 

func (g *Container) ArrayRemove(index int, path ...string) error

ArrayRemove - Remove an element from a JSON array.

func (*Container) ArrayRemoveP 

func (g *Container) ArrayRemoveP(index int, path string) error

ArrayRemoveP - Remove an element from a JSON array using a dot notation JSON path.

func (*Container) Bytes 

func (g *Container) Bytes() []byte

Bytes - Converts the contained object back to a JSON []byte blob.

func (*Container) BytesIndent 

func (g *Container) BytesIndent(prefix string, indent string) []byte

BytesIndent - Converts the contained object to a JSON []byte blob formatted with prefix, indent.

func (*Container) Children 

func (g *Container) Children() ([]*Container, error)

Children - Return a slice of all the children of the array. This also works for objects, however, the children returned for an object will NOT be in order and you lose the names of the returned objects this way.

func (*Container) ChildrenMap 

func (g *Container) ChildrenMap() (map[string]*Container, error)

ChildrenMap - Return a map of all the children of an object.

func (*Container) Data 

func (g *Container) Data() interface{}

Data - Return the contained data as an interface{}.

func (*Container) Delete 

func (g *Container) Delete(path ...string) error

Delete - Delete an element at a JSON path, an error is returned if the element does not exist.

func (*Container) DeleteP 

func (g *Container) DeleteP(path string) error

DeleteP - Does the same as Delete, but using a dot notation JSON path.

func (*Container) EncodeJSON added in v1.1.0 

func (g *Container) EncodeJSON(encodeOpts ...EncodeOpt) []byte

EncodeJSON - Encodes the contained object back to a JSON formatted []byte using a variant list of modifier functions for the encoder being used. Functions for modifying the output are prefixed with EncodeOpt, e.g. EncodeOptHTMLEscape.

func (*Container) Exists 

func (g *Container) Exists(hierarchy ...string) bool

Exists - Checks whether a path exists.

func (*Container) ExistsP 

func (g *Container) ExistsP(path string) bool

ExistsP - Checks whether a dot notation path exists.

func (*Container) Index 

func (g *Container) Index(index int) *Container

Index - Attempt to find and return an object within a JSON array by index.

func (*Container) Merge added in v1.1.0 

func (g *Container) Merge(source *Container) error

Merge a source object into an existing destination object. When a collision is found within the merged structures (both a source and destination object contain the same non-object keys) the result will be an array containing both values, where values that are already arrays will be expanded into the resulting array.

It is possible to merge structures will different collision behaviours with MergeFn.

func (*Container) MergeFn added in v1.2.0 

func (g *Container) MergeFn(source *Container, collisionFn func(destination, source interface{}) interface{}) error

MergeFn merges two objects using a provided function to resolve collisions.

The collision function receives two interface{} arguments, destination (the original object) and source (the object being merged into the destination). Which ever value is returned becomes the new value in the destination object at the location of the collision.

func (*Container) Object 

func (g *Container) Object(path ...string) (*Container, error)

Object - Create a new JSON object at a path. Returns an error if the path contains a collision with a non object type.

func (*Container) ObjectI 

func (g *Container) ObjectI(index int) (*Container, error)

ObjectI - Create a new JSON object at an array index. Returns an error if the object is not an array or the index is out of bounds.

func (*Container) ObjectP 

func (g *Container) ObjectP(path string) (*Container, error)

ObjectP - Does the same as Object, but using a dot notation JSON path.

func (*Container) Path 

func (g *Container) Path(path string) *Container

Path - Search for a value using dot notation.

func (*Container) S 

func (g *Container) S(hierarchy ...string) *Container

S - Shorthand method, does the same thing as Search.

func (*Container) Search 

func (g *Container) Search(hierarchy ...string) *Container

Search - Attempt to find and return an object within the JSON structure by specifying the hierarchy of field names to locate the target. If the search encounters an array and has not reached the end target then it will iterate each object of the array for the target and return all of the results in a JSON array.

func (*Container) Set 

func (g *Container) Set(value interface{}, path ...string) (*Container, error)

Set - Set the value of a field at a JSON path, any parts of the path that do not exist will be constructed, and if a collision occurs with a non object type whilst iterating the path an error is returned.

func (*Container) SetIndex 

func (g *Container) SetIndex(value interface{}, index int) (*Container, error)

SetIndex - Set a value of an array element based on the index.

func (*Container) SetP 

func (g *Container) SetP(value interface{}, path string) (*Container, error)

SetP - Does the same as Set, but using a dot notation JSON path.

func (*Container) String 

func (g *Container) String() string

String - Converts the contained object to a JSON formatted string.

func (*Container) StringIndent 

func (g *Container) StringIndent(prefix string, indent string) string

StringIndent - Converts the contained object back to a JSON formatted string with prefix, indent.

type EncodeOpt added in v1.1.0 

type EncodeOpt func(e *json.Encoder)

EncodeOpt is a functional option for the EncodeJSON method.

func EncodeOptHTMLEscape added in v1.1.0 

func EncodeOptHTMLEscape(doEscape bool) EncodeOpt

EncodeOptHTMLEscape sets the encoder to escape the JSON for html.

func EncodeOptIndent added in v1.1.0 

func EncodeOptIndent(prefix string, indent string) EncodeOpt

EncodeOptIndent sets the encoder to indent the JSON output.

Source Files

View all Source files

Jump to

Keyboard shortcuts

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