README
¶
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 Field() 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
- SetField() 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 Actual()
- 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 Field(), Index() and Actual() 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
Usage
// read some JSON
bytes := []byte(`{"type":"test"}`)
// create a Value object
doc := value.NewValueFromBytes(bytes)
// attempt to access a nested Value
docType, err := doc.Field("type")
if err != nil {
panic("no property type exists")
}
// convert docType to a native go value
docTypeValue := docType.Actual()
// display the value
fmt.Printf("document type is %v\n", docTypeValue)
Output
$ ./example
document type is test
Documentation
¶
Index ¶
Constants ¶
const ( NOT_JSON = iota NULL BOOLEAN NUMBER STRING ARRAY OBJECT )
The data types supported by Value
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AnnotatedValue ¶
type AnnotatedValue interface {
Value
GetAttachment(key string) interface{}
SetAttachment(key string, val interface{})
RemoveAttachment(key string) interface{}
}
func NewAnnotatedValue ¶
func NewAnnotatedValue(val interface{}) AnnotatedValue
Create an AnnotatedValue to hold attachments
type Undefined ¶
type Undefined 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.
type Unsettable ¶
type Unsettable string
When you try to set a nested property or index that does not exist, the return error will be Unsettable.
func (Unsettable) Error ¶
func (this Unsettable) Error() string
Description of which property or index was unsettable (if known).
type Value ¶
type Value interface {
Type() int // Data type constant
Actual() interface{} // Native Go representation
Duplicate() Value // Shallow copy
DuplicateForUpdate() Value // Deep copy for UPDATE statements; returns Values whose SetIndex() will extend arrays as needed
Bytes() []byte // JSON byte encoding
Field(field string) (Value, error) // Object field dereference
SetField(field string, val interface{}) error // Object field setting
Index(index int) (Value, error) // Array index dereference
SetIndex(index int, val interface{}) error // Array index setting
}
An interface for storing and manipulating a (possibly JSON) value.
func NewValueFromBytes ¶
Create a new Value from a slice of bytes. (this need not be valid JSON)
Source Files
Directories