dparval

README

dparval - a delayed parsing value system

The goal is offer a consistent type structure to allow you to process JSON end-to-end with minimal parsing.

Features

• Create Value objects with unparsed JSON bytes or with JSON compatible go datatypes
• Access nested data using Path() and Index() methods
  • these also return Value objects (or Undefined) allowing you to delay parsing of nested objects as well
• Values of type OBJECT and ARRAY are mutable
  • SetPath() and SetIndex() allow you to overlay new Values into these objects
• Returning to []byte can be done at any time by calling Bytes()
  • the underlying raw bytes are reused if possible to avoid JSON encoding
• Exit the type system at any time by calling Value()
  • this will trigger parsing of any required values that have not yet been parsed
• Arbitrary data may be attached to a Value using the Set/Get/Remove Attachment() methods
• Check the type of Value using the Type() method

Documentation

See GoDoc

Performance

Two simple benchmarks which process a 1MB JSON file. The first uses NewValueFromBytes() with Path(), Index() and Value() calls and the second using json.Unmarshal() and map/slice calls. Both versions access the same property.

$ go test -bench .
PASS
BenchmarkLargeValue	      20	  76905386 ns/op	  25.23 MB/s
BenchmarkLargeMap	      20	 116378934 ns/op	  16.67 MB/s
ok  	github.com/mschoch/dparval	4.179s

Usage

// read some JSON
bytes := []byte(`{"type":"test"}`)

// create a Value object
doc := dparval.NewValueFromBytes(bytes)

// attempt to access a nested Value
docType, err := doc.Path("type")
if err != nil {
	panic("no property type exists")
}

// convert docType to a native go value
docTypeValue := docType.Value()

// display the value
fmt.Printf("document type is %v\n", docTypeValue)

Output

$ ./example
document type is test

Documentation

Overview

Work with JSON data without parsing for as long as possible

Index

• Constants
• type Undefined
  • func (this *Undefined) Error() string
• type Value
  • func NewValue(val interface{}) *Value
  • func NewValueFromBytes(bytes []byte) *Value
  • func (this *Value) Bytes() []byte
  • func (this *Value) Duplicate() *Value
  • func (this *Value) GetAttachment(key string) interface{}
  • func (this *Value) Index(index int) (*Value, error)
  • func (this *Value) Path(path string) (*Value, error)
  • func (this *Value) RemoveAttachment(key string) interface{}
  • func (this *Value) SetAttachment(key string, val interface{})
  • func (this *Value) SetIndex(index int, val interface{})
  • func (this *Value) SetPath(path string, val interface{})
  • func (this *Value) Type() int
  • func (this *Value) Value() interface{}
• type ValueChannel
• type ValueCollection

Constants

const (
	NOT_JSON = iota
	NULL
	BOOLEAN
	NUMBER
	STRING
	ARRAY
	OBJECT
)

The types supported by Value

Types

type Undefined

type Undefined struct {
	Path string
}

When you try to access a nested property or index that does not exist, the return value will be nil, and the return error will be *Undefined.

func (*Undefined) Error

func (this *Undefined) Error() string

Description of which property or index was undefined (if known).

type Value

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

A structure for storing and manipulating a (possibly JSON) value.

func NewValue

func NewValue(val interface{}) *Value

Create a new Value object from an existing object. MUST be one of the types supported by JSON. If the argument passed is an existing *Value, that will be returned without creating a new object.

func NewValueFromBytes

func NewValueFromBytes(bytes []byte) *Value

Create a new Value object from a slice of bytes. (this need not be valid JSON)

func (*Value) Bytes

func (this *Value) Bytes() []byte

func (*Value) Duplicate

func (this *Value) Duplicate() *Value

Create a duplicate of this Value with minimal effort Shallow copies are created of any ARRAY/OBJECT parsed values Shallow copies are created of any attachments

func (*Value) GetAttachment

func (this *Value) GetAttachment(key string) interface{}

Return the object attached to this Value with this key. If no object is attached with this key, nil is returned.

func (*Value) Index

func (this *Value) Index(index int) (*Value, error)

If this Value is of type ARRAY, this method attempts to access the requested index inside the array. If this Value is not of type ARRAY, then the return value is nil and the return error is *Undefined.

The path lookup has the following steps:

1. If an alias has been set for this index, that is returned.
2. If no alias has been set for this index, and the value has already been parsed, the value for that index in the parsed array is returned.
3. If no alias has been set, and the value has not yet been parsed, the value is accessed in the byte array using a jsonpointer expression.
4. If none of these successfully find a value, the return value is nil, and the return error is *Undefined.

func (*Value) Path

func (this *Value) Path(path string) (*Value, error)

If this Value is of type OBJECT, this method attempts to access the requested path inside the object. If this Value is not of type OBJECT, then the return value is nil and the return error is *Undefined.

The path lookup has the following steps:

1. If an alias has been set for this path, that is returned.
2. If no alias has been set for this path, and the value has already been parsed, the value for that key in the parsed object is returned.
3. If no alias has been set, and the value has not yet been parsed, the value is accessed in the byte array using a jsonpointer expression.
4. If none of these successfully find a value, the return value is nil, and the return error is *Undefined.

func (*Value) RemoveAttachment

func (this *Value) RemoveAttachment(key string) interface{}

Remove an object attached to this Value with this key. If there had been an object attached to this Value with this key it is returned, otherwise nil.

func (*Value) SetAttachment

func (this *Value) SetAttachment(key string, val interface{})

Attach an arbitrary object to this Value with the specified key. Any existing value attached with this same key will be overwritten.

func (*Value) SetIndex

func (this *Value) SetIndex(index int, val interface{})

If this Value is of type ARRAY, this method attempts to store an alias for this value at the specified index. If this Value is not of type ARRAY, nothing is done.

NOTE: All incoming values are brought into the type system, so the val argument must be compatible with the NewValue() method.

func (*Value) SetPath

func (this *Value) SetPath(path string, val interface{})

If this Value is of type OBJECT, this method attempts to store an alias for this value at the specified path. If this Value is not of type OBJECT, nothing is done.

NOTE: All incoming values are brought into the type system, so the val argument must be compatible with the NewValue() method.

func (*Value) Type

func (this *Value) Type() int

Determine the type of object stored in this Value.

func (*Value) Value

func (this *Value) Value() interface{}

The Value() function allows the data stored in this Value to return to its native Go representation. If this Value has not yet been parsed, it will be parsed at this time.

NOTE: If the Value is of type NOT_JSON, null will be returned.

type ValueChannel

type ValueChannel chan *Value

A channel of *Value objects

type ValueCollection

type ValueCollection []*Value

A collection of *Value objects