jsonvalue

README

go-json-value

A library providing Go interface to dynamically and flexibly manipulate JSON-structured values

Overview

The go-json-value package is a Go library that provides an interface for dynamically and flexibly manipulating JSON-structured data. It offers functionality for creating, modifying, and accessing JSON-structured data with interface in Go. Additionally, it includes features for working with keys, paths, and traversing JSON structures.

Usage

Installation

Use go get to install the package:

go get -u github.com/Jumpaku/go-json-value

Import

Import the jsonvalue package into your Go program:

import "github.com/Jumpaku/go-json-value"

Key API

Types for JSON values:

// Type represents type of JSON values.
type Type int

const (
	// TypeNull represents the type for the JSON null value.
	TypeNull Type = iota
	// TypeString represents the type for the JSON string values.
	TypeString
	// TypeNumber represents the type for the JSON number values.
	TypeNumber
	// TypeBoolean represents the type for the JSON boolean values.
	TypeBoolean
	// TypeArray represents the type for the JSON array values.
	TypeArray
	// TypeObject represents the type for the JSON object values.
	TypeObject
)

Interface modeling JSON-structured data.

// Value models a JSON-structured data.
type Value interface {
	json.Marshaler
	json.Unmarshaler
	// Type returns JSON type.
	Type() Type
	// Assign assigns a JSON value to this object.
	Assign(v Value)
	// Clone deeply copies itself.
	Clone() Value
	// NumberGet returns this JSON value as a number.
	NumberGet() json.Number
	// StringGet returns this JSON value as a string.
	StringGet() string
	// BooleanGet returns this JSON value as a boolean.
	BooleanGet() bool
	// ObjectKeys returns keys of this JSON value as a object.
	ObjectKeys() []string
	// ObjectHasElm returns whether this JSON value as a object has the key.
	ObjectHasElm(key string) bool
	// ObjectHasElm returns a JSON value associated the key.
	ObjectGetElm(key string) Value
	// ObjectHasElm associates a JSON value by the key.
	ObjectSetElm(key string, v Value)
	// ObjectDelElm deletes the key and the associated JSON value.
	ObjectDelElm(key string)
	// ObjectLen returns the number of keys.
	ObjectLen() int
	// ArrayGetElm returns a JSON value indexed.
	ArrayGetElm(index int) Value
	// ArraySetElm sets a JSON value at the index.
	ArraySetElm(index int, v Value)
	// ArrayAddElm adds JSON values to the back.
	ArrayAddElm(vs ...Value)
	// ArrayLen returns the number of elements.
	ArrayLen() int
	// ArraySlice returns a sliced JSON array.
	ArraySlice(begin int, endExclusive int) Value
}

Functions for creation of JSON values:

// Null returns a JSON value representing null.
func Null() Value

// Boolean returns a JSON boolean value.
func Boolean(b bool) Value

// String returns a JSON string value of s.
func String(s string) Value

// Number returns a JSON number value of n.
func Number[V ~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~float32 | ~float64 | json.Number](n V) Value

// Object returns a JSON object value containing specified properties.
func Object(p ...Props) Value
// Props representing properties of JSON object.
type Props map[string]Value

// Array returns a JSON array value containing specified values.
func Array(vs ...Value) Value

Functions for visiting each value included in a JSON value:

// Walk traverses a JSON value v and calls the visitor function for each the JSON values included in v.
// If a call of visitor returned an error, Walk immediately returns with the error.
func Walk(v Value, visitor func(path Path, val Value) error) error

// Find finds the JSON value specified by the Path in a JSON value v.
// If the JSON value associated with the Path exists, the found JSON value and true are returned; otherwise nil and false are returned.
func Find(v Value, path Path) (Value, bool)

Documentation

Index

• func Walk(v Value, visitor func(path Path, val Value) error) error
• type Key
  • func KeyInt(index int) Key
  • func (k Key) Int() int
  • func (k Key) String() string
• type Path
  • func (p Path) Append(key Key) Path
  • func (p Path) Equals(other Path) bool
  • func (p Path) Get(index int) Key
  • func (p Path) Len() int
  • func (p Path) Slice(begin int, endExclusive int) Path
• type Props
• type Type
  • func (t Type) String() string
• type Value
  • func Array(vs ...Value) Value
  • func Boolean(b bool) Value
  • func Find(v Value, path Path) (Value, bool)
  • func Null() Value
  • func Number[...](n V) Value
  • func Object(p ...Props) Value
  • func String(s string) Value

Functions

func Walk

func Walk(v Value, visitor func(path Path, val Value) error) error

Walk traverses a JSON value v and calls the visitor function for each the JSON values included in v. If a call of visitor returned an error, Walk immediately returns with the error.

Types

type Key

type Key string

Key represents a key for a member in a JSON object or an index for an element in a JSON array.

func KeyInt

func KeyInt(index int) Key

KeyInt creates Key from JOSN array index.

func (Key) Int

func (k Key) Int() int

String returns index for JSON array in int.

func (Key) String

func (k Key) String() string

String returns key for JSON object in string.

type Path

type Path []Key

Path represents a sequence of the Keys. An empty path Path{} represents a root JSON value.

func (Path) Append

func (p Path) Append(key Key) Path

Append creates a new Path appended the key to the end of the original Path.

func (Path) Equals

func (p Path) Equals(other Path) bool

Equals returns true if two Paths contain the same keys in the same order; otherwise false.

func (Path) Get

func (p Path) Get(index int) Key

Get returns a Key at the index.

func (Path) Len

func (p Path) Len() int

Len returns the number of keys.

func (Path) Slice

func (p Path) Slice(begin int, endExclusive int) Path

Slice creates a new Path sliced from begin to and of the original Path.

type Props

type Props map[string]Value

Props representing properties of JSON object.

type Type

type Type int

Type represents type of JSON values.

const (
	// TypeNull represents the type for the JSON null value.
	TypeNull Type = iota
	// TypeString represents the type for the JSON string values.
	TypeString
	// TypeNumber represents the type for the JSON number values.
	TypeNumber
	// TypeBoolean represents the type for the JSON boolean values.
	TypeBoolean
	// TypeArray represents the type for the JSON array values.
	TypeArray
	// TypeObject represents the type for the JSON object values.
	TypeObject
)

func (Type) String

func (t Type) String() string

String provides a representation in string.

type Value

type Value interface {
	json.Marshaler
	json.Unmarshaler
	// Type returns JSON type.
	Type() Type
	// Assign assigns a JSON value to this object.
	Assign(v Value)
	// Clone deeply copies itself.
	Clone() Value
	// NumberGet returns this JSON value as a number.
	NumberGet() json.Number
	// StringGet returns this JSON value as a string.
	StringGet() string
	// BooleanGet returns this JSON value as a boolean.
	BooleanGet() bool
	// ObjectKeys returns keys of this JSON value as a object.
	ObjectKeys() []string
	// ObjectHasElm returns whether this JSON value as a object has the key.
	ObjectHasElm(key string) bool
	// ObjectHasElm returns a JSON value associated the key.
	ObjectGetElm(key string) Value
	// ObjectHasElm associates a JSON value by the key.
	ObjectSetElm(key string, v Value)
	// ObjectDelElm deletes the key and the associated JSON value.
	ObjectDelElm(key string)
	// ObjectLen returns the number of keys.
	ObjectLen() int
	// ArrayGetElm returns a JSON value indexed.
	ArrayGetElm(index int) Value
	// ArraySetElm sets a JSON value at the index.
	ArraySetElm(index int, v Value)
	// ArrayAddElm adds JSON values to the back.
	ArrayAddElm(vs ...Value)
	// ArrayLen returns the number of elements.
	ArrayLen() int
	// ArraySlice returns a sliced JSON array.
	ArraySlice(begin int, endExclusive int) Value
}

Value models a JSON-structured data.

func Array

func Array(vs ...Value) Value

Array returns a JSON array value containing specified values.

func Boolean

func Boolean(b bool) Value

Boolean returns a JSON boolean value.

func Find

func Find(v Value, path Path) (Value, bool)

Find finds the JSON value specified by the Path in a JSON value v. If the JSON value associated with the Path exists, the found JSON value and true are returned; otherwise nil and false are returned.

func Null

func Null() Value

Null returns a JSON value representing null.

func Number

func Number[V ~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~float32 | ~float64 | json.Number](n V) Value

Number returns a JSON number value of n.

func Object

func Object(p ...Props) Value

Object returns a JSON object value containing specified properties.

func String

func String(s string) Value

String returns a JSON string value of s.