README
¶
luna - Easier Parsing of Unstructured JSON in Go
Goal
The intent of this library is to create an easier interface to work with when parsing JSON in Go without having to create a bunch of structs with tags.
Features include:
- An interface that propagates errors until you finally extract a value to use
- More detailed error messages that give valuable debugging information (such as other keys in the map when a key is not found)
- Equivalent versions of value-retrieving functions to panic on error (but allow nesting results inside function calls)
Motivation
Parsing unstructured JSON is plain ugly in Go. Let's say you have the below JSON and you want to pull out the first person's score:
data := []byte(`{
"people": [
{
"name": "alice",
"score": 89.5,
"friends": [ "bob" ],
"deleted": false
},
{
"name": "bob",
"score": 75.5,
"friends": [],
"deleted": false,
}
]
}`)
If you didn't want to go through the hassle of creating structs that represent each of the entities in the JSON, you would have to do something like this:
var dataMap map[string]interface{}
err := json.Unmarshal(data, &dataMap)
if err != nil {
return err
}
peopleObj, ok := dataMap["people"] // peopleObj is an `interface{}`
if !ok {
return fmt.Errorf("people key not found")
}
peopleArray, ok := peopleObj.([]interface{})
if !ok {
return fmt.Errorf("people should be a []interface{}, but is a %T", peopleArray)
}
if len(peopleArray) == 0 {
return fmt.Errorf("no people found")
}
firstPerson := peopleObj[0] // firstPerson is an `interface{}`
firstPersonMap, ok := firstPerson.(map[string]interface{})
if !ok {
return fmt.Errorf("first person should be a map[string]interface{}, but is a %T", firstPerson)
}
firstPersonScore, ok := firstPersonMap["score"] // firstPersonScore is an `interface{}`
if !ok {
return fmt.Errorf("score not found")
}
score, ok := firstPersonScore.(float64)
if !ok {
return fmt.Errorf("score should be a float64, but is a %T", score)
}
Phew! That was a lot of code to get one little value out of a tiny JSON. Is it possible to write this more concisely but retain the all the validation that guards us against the data not being in the expected format?
Simple Code Without Sacrifice
Using this library, here's how you would pull out the same value and still include all the useful validation done above...
score, err := luna.MapFromBytes(data).Array("people").Map(0).Float("score")
if err != nil {
return err
}
fmt.Printf("Alice's score: %f\n", score)
Alice's score: 89.5
But what if we got the key wrong and used "grade" instead of "score"?
score, err := luna.MapFromBytes(data).Array("people").Map(0).Float("grade")
if err != nil {
fmt.Printf("Uh oh! %s\n", err)
}
Uh oh! key 'grade' not found at path $['people'][0], valid keys: name, score, friends, deleted
Well that's much cleaner! And we didn't have to do annoying type casting from interface{} or error checking along the
way. Just check once when you pull out the value and if any of the errors that we checked for in the old code happened,
they will be propagated to the final call to get the values out of the JSON. As a bonus, the error message
conveniently contains the full path to where the error happened along with the valid keys at that path!
Wow! How did that work?
Actually, it's not that complicated. Whenever you call .Array(...) or .Map(...) with an invalid index or key, it
returns a struct that holds on to that error and finally returns it when you call one of the other functions
like Float(...). Meanwhile, it also builds up and keeps track of the path so that if any error does happen, you'll
know exactly where to look!
But I really hate checking for errors... now what?
OK, what if you're really confident the value is there, need to send it to another function, and are willing to let it
panic if something went wrong? That's what the Must* versions of all the functions that return errors are for!
processScore(luna.MapFromBytes(data).Array("people").Map(0).MustFloat("score"))
Even with this approach, the panic will contain the same useful information you would get using the other methods.
So what's the full interface?
Check it out...
Documentation
¶
Index ¶
- type Array
- func (a Array) Array(idx int) Array
- func (a Array) Bool(idx int) (bool, error)
- func (a Array) Bytes() ([]byte, error)
- func (a Array) Err() error
- func (a Array) Float(idx int) (float64, error)
- func (a Array) Len() (int, error)
- func (a Array) Map(idx int) Map
- func (a Array) MustBool(idx int) bool
- func (a Array) MustBytes() []byte
- func (a Array) MustFloat(idx int) float64
- func (a Array) MustInner() []interface{}
- func (a Array) MustLen() int
- func (a Array) MustString(idx int) string
- func (a Array) String(idx int) (string, error)
- type Map
- func (m Map) Array(key string) Array
- func (m Map) Bool(key string) (bool, error)
- func (m Map) Bytes() ([]byte, error)
- func (m Map) Err() error
- func (m Map) Float(key string) (float64, error)
- func (m Map) Has(key string) (bool, error)
- func (m Map) Inner() (map[string]interface{}, error)
- func (m Map) Map(key string) Map
- func (m Map) MustBool(key string) bool
- func (m Map) MustBytes() []byte
- func (m Map) MustFloat(key string) float64
- func (m Map) MustHas(key string) bool
- func (m Map) MustInner() map[string]interface{}
- func (m Map) MustString(key string) string
- func (m Map) String(key string) (string, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Array ¶
type Array struct {
// contains filtered or unexported fields
}
Array provides methods to either navigate through the content of a JSON array or propagate any error that has occurred
func ArrayFromBytes ¶
ArrayFromBytes creates an Array from a []byte
func ArrayFromReader ¶
ArrayFromReader creates an Array from an io.Reader
func (Array) Array ¶
Array returns the array found at index `idx` in the array; errors will be propagated
func (Array) Bool ¶
Bool returns the value of a bool at index `idx` in the array, or a propagated error
func (Array) Bytes ¶
Bytes returns the serialized value into a slice of bytes, or a propagated error
func (Array) Float ¶
Float returns the value of a float at index `idx` in the array, or a propagated error
func (Array) MustBool ¶
MustBool returns the value of a bool at index `idx` in the array, or panics if there was an error
func (Array) MustBytes ¶
MustBytes returns the serialized value into a slice of bytes, or panics if there was an error
func (Array) MustFloat ¶
MustFloat returns the value of a float at index `idx` in the array, or panics if there was an error
func (Array) MustInner ¶
func (a Array) MustInner() []interface{}
MustInner returns the `[]interface{}` which this `Array` represents, or panics if there was an error
func (Array) MustString ¶
MustString returns the value of a string at index `idx` in the array, or panics if there was an error
type Map ¶
type Map struct {
// contains filtered or unexported fields
}
Map provides methods to either navigate through the content of a JSON object or propagate any error that has occurred
func MapFromBytes ¶
MapFromBytes creates a Map from a []byte
func MapFromReader ¶
MapFromReader creates a Map from an io.Reader
func (Map) Float ¶
Float returns the value of a float at key `key` in the map, or a propagated error
func (Map) Inner ¶
Inner returns the `[]interface{}` which this `Array` represents, or a propagated error
func (Map) MustBool ¶
MustBool returns the value of a bool at key `key` in the map, or panics if there was an error
func (Map) MustBytes ¶
MustBytes returns the serialized value into a slice of bytes, or panics if there was an error
func (Map) MustFloat ¶
MustFloat returns the value of a float at key `key` in the map, or panics if there was an error
func (Map) MustHas ¶
MustHas returns true if the map contains the key `key`, or panics if there was an error
func (Map) MustInner ¶
MustInner returns the `[]interface{}` which this `Array` represents, or panics if there was an error
func (Map) MustString ¶
MustString returns the value of a string at key `key` in the map, or panics if there was an error
Source Files