json

README

A Simple JSON reader

This library is for dynamically inspecting parsed JSON values rather than for data binding or serialization.

import "github.com/mcvoid/json"

func TestUsage(t *testing.T) {
	// use one of the ParseXXX functions to get a JSON value from text.
	// You can pass in strings, []byte, or io.Reader.
	val, err := json.ParseString(`
	{
		"null": null,
		"integer": 5,
		"number": 5.0,
		"boolean": true,
		"array": [null, 5, 5.0, true],
		"object": {}
	}
	`)
	if err != nil {
		t.Error("Can't parse json... somehow.")
	}

	// to inspect the type, use the Type method.
	if val.Type() != json.Object {
		t.Error("JSON object is wrong type!")
	}

	// Objects can be extracted as maps of values
	m, _ := val.AsObject()
	if m["null"].Type() != json.Null {
		t.Error("JSON null is wrong type!")
	}

	// We differentiate integers and numbers, but integers count as numbers, too.
	// Integer is mainly there for large whole numbers that float64 might
	// not have the precision for.
	i, _ := m["integer"].AsNumber()
	n, _ := m["number"].AsNumber()
	if i != n {
		t.Error("It works this time, but this isn't the best way to check for floating point equivalency, btw")
	}

	// Arrays are represented as slices of JSON values.
	a, _ := m["array"].AsArray()

	// Booleans are bools.
	b, _ := a[3].AsBoolean()
	if !b {
		t.Error("true... isn't?")
	}

	// And that's all there is to it. Enjoy!
}

Uses a table-driven parser based on Doug Crockford's json-c JSON Checker C library / command line utility. This should lead to a fairly fast parsing time, though that's not guaranteed and isn't even a design goal.

See example_test.go for usage examples.

License

Copyright (c) 2022 Sean Wolcott

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Based on json-checker by (c) 2016 Douglas Crockford, no license information specified.

Documentation

Index

• Variables
• type Type
  • func (t Type) String() string
• type Value
  • func Parse(r io.Reader) (*Value, error)
  • func ParseBytes(b []byte) (*Value, error)
  • func ParseString(s string) (*Value, error)
  • func (v *Value) AsArray() ([]*Value, error)
  • func (v *Value) AsBoolean() (bool, error)
  • func (v *Value) AsInteger() (int64, error)
  • func (v *Value) AsNull() (struct{}, error)
  • func (v *Value) AsNumber() (float64, error)
  • func (v *Value) AsObject() (map[string]*Value, error)
  • func (v *Value) AsString() (string, error)
  • func (v *Value) Index(i int) *Value
  • func (v *Value) Key(k string) *Value
  • func (v *Value) String() string
  • func (v *Value) Type() Type

Variables

var (
	// A value is trying to be cast to an incorrect type.
	ErrType = errors.New("type error")
	// A problem occured while parsing the JSON
	ErrParse = errors.New("parse error")
)

Types

type Type

type Type int

The type of a JSON value.

const (
	Null Type = iota
	Number
	Integer
	String
	Boolean
	Array
	Object
)

Possible JSON values

func (Type) String

func (t Type) String() string

Returns a string representation of a JSON Type.

type Value

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

A structured JSON value

func Parse

func Parse(r io.Reader) (*Value, error)

Parses a JSON value from a Reader. If it cannot read a valid value, it returns an error. Returns nil error otherwise.

func ParseBytes

func ParseBytes(b []byte) (*Value, error)

Parses a JSON value from a byte slice. If it cannot read a valid value, it returns an error. Returns nil error otherwise.

func ParseString

func ParseString(s string) (*Value, error)

Parses a JSON value from a string. If it cannot read a valid value, it returns an error. Returns nil error otherwise.

func (*Value) AsArray

func (v *Value) AsArray() ([]*Value, error)

Extracts an array value from the JSON. Returns ErrType if the value is not array, nil otherwise.

func (*Value) AsBoolean

func (v *Value) AsBoolean() (bool, error)

Extracts a boolean value from the JSON. Returns ErrType if the value is not boolean, nil otherwise.

func (*Value) AsInteger

func (v *Value) AsInteger() (int64, error)

Extracts an integer from the JSON. Will not convert decimal to integer. If decimal precision is needed, use AsNumber instead. Returns ErrType if the value is niether a number nor an integer. Returns nil otherwise.

func (*Value) AsNull

func (v *Value) AsNull() (struct{}, error)

Extracts a null value from the JSON. Returns ErrType if the value is not null, nil otherwise.

func (*Value) AsNumber

func (v *Value) AsNumber() (float64, error)

Extracts a number from the JSON. If the value is an integer, it is cast to a float64. If integer precision is needed, use AsInteger instead. Returns ErrType if the value is niether a number nor an integer. Returns nil otherwise.

func (*Value) AsObject

func (v *Value) AsObject() (map[string]*Value, error)

Extracts an object value from the JSON. Returns ErrType if the value is not object, nil otherwise.

func (*Value) AsString

func (v *Value) AsString() (string, error)

Extracts a string value from the JSON. Returns ErrType if the value is not string, nil otherwise.

func (*Value) Index

func (v *Value) Index(i int) *Value

Fluent inteface for accessing array members. Returns nil instead of error.

func (*Value) Key

func (v *Value) Key(k string) *Value

Fluent inteface for accessing object members. Returns nil instead of error.

func (*Value) String

func (v *Value) String() string

Returns a string representation of the values. NOT valid JSON!

func (*Value) Type

func (v *Value) Type() Type

Gets the type of the current value.