gabs

Documentation

Overview

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

Index

• Variables
• type Container
  • func Consume(root interface{}) (*Container, error)
  • func New() *Container
  • func ParseJSON(sample []byte) (*Container, error)
  • func ParseJSONBuffer(buffer io.Reader) (*Container, error)
  • func ParseJSONDecoder(decoder *json.Decoder) (*Container, error)
  • func ParseJSONFile(path string) (*Container, error)
  • func (g *Container) Array(path ...string) (*Container, error)
  • func (g *Container) ArrayAppend(value interface{}, path ...string) error
  • func (g *Container) ArrayAppendP(value interface{}, path string) error
  • func (g *Container) ArrayCount(path ...string) (int, error)
  • func (g *Container) ArrayCountP(path string) (int, error)
  • func (g *Container) ArrayElement(index int, path ...string) (*Container, error)
  • func (g *Container) ArrayElementP(index int, path string) (*Container, error)
  • func (g *Container) ArrayI(index int) (*Container, error)
  • func (g *Container) ArrayOfSize(size int, path ...string) (*Container, error)
  • func (g *Container) ArrayOfSizeI(size, index int) (*Container, error)
  • func (g *Container) ArrayOfSizeP(size int, path string) (*Container, error)
  • func (g *Container) ArrayP(path string) (*Container, error)
  • func (g *Container) ArrayRemove(index int, path ...string) error
  • func (g *Container) ArrayRemoveP(index int, path string) error
  • func (g *Container) Bytes() []byte
  • func (g *Container) BytesIndent(prefix string, indent string) []byte
  • func (g *Container) Children() ([]*Container, error)
  • func (g *Container) ChildrenMap() (map[string]*Container, error)
  • func (g *Container) Data() interface{}
  • func (g *Container) Delete(path ...string) error
  • func (g *Container) DeleteP(path string) error
  • func (g *Container) EncodeJSON(encodeOpts ...EncodeOpt) []byte
  • func (g *Container) Exists(hierarchy ...string) bool
  • func (g *Container) ExistsP(path string) bool
  • func (g *Container) Index(index int) *Container
  • func (g *Container) Merge(source *Container) error
  • func (g *Container) MergeFn(source *Container, ...) error
  • func (g *Container) Object(path ...string) (*Container, error)
  • func (g *Container) ObjectI(index int) (*Container, error)
  • func (g *Container) ObjectP(path string) (*Container, error)
  • func (g *Container) Path(path string) *Container
  • func (g *Container) S(hierarchy ...string) *Container
  • func (g *Container) Search(hierarchy ...string) *Container
  • func (g *Container) Set(value interface{}, path ...string) (*Container, error)
  • func (g *Container) SetIndex(value interface{}, index int) (*Container, error)
  • func (g *Container) SetP(value interface{}, path string) (*Container, error)
  • func (g *Container) String() string
  • func (g *Container) StringIndent(prefix string, indent string) string
• type EncodeOpt
  • func EncodeOptHTMLEscape(doEscape bool) EncodeOpt
  • func EncodeOptIndent(prefix string, indent string) EncodeOpt

Variables

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

	// 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")
)

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.

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

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

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

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.

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

type EncodeOpt func(e *json.Encoder)

EncodeOpt is a functional option for the EncodeJSON method.

func EncodeOptHTMLEscape

func EncodeOptHTMLEscape(doEscape bool) EncodeOpt

EncodeOptHTMLEscape sets the encoder to escape the JSON for html.

func EncodeOptIndent

func EncodeOptIndent(prefix string, indent string) EncodeOpt

EncodeOptIndent sets the encoder to indent the JSON output.