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
- type Value
- func (this *Value) Bytes() []byte
- 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
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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.
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 ¶
Create a new Value object from a slice of bytes. (this need not be valid JSON)
func (*Value) GetAttachment ¶
Return the object attached to this Value with this key. If no object is attached with this key, nil is returned.
func (*Value) Index ¶
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:
- If an alias has been set for this index, that is returned.
- 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.
- 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.
- If none of these successfully find a value, the return value is nil, and the return error is *Undefined.
func (*Value) Path ¶
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:
- If an alias has been set for this path, that is returned.
- 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.
- 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.
- If none of these successfully find a value, the return value is nil, and the return error is *Undefined.
func (*Value) RemoveAttachment ¶
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 ¶
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 ¶
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 ¶
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.
Source Files
Directories