jsonface: github.com/likebike/jsonface Index | Examples | Files

package jsonface

import "github.com/likebike/jsonface"

Package jsonface enables JSON Unmarshalling into Go Interfaces. This enables you to isolate your data type design from your deserialization logic.

When writing Go programs, I often want to create types that contain interface members like this:

type (
    Instrument interface {
        Play()
    }
    Bell  struct { BellPitch string }   // I am using contrived field names
    Drum  struct { DrumSize  float64 }  // to keep this example simple.

    BandMember struct {
        Name string
        Inst Instrument    // <---- Interface Member
    }
)

...But if I want to serialize/deserialize a BandMember using JSON, I'm going to have a bit of a problem because Go's json package can't unmarshal into an interface. Therefore, I need to define some custom unmarshalling logic at the BandMember level. This is not ideal, since the logic should really belong to Instrument, not BandMember. It becomes especially problematic if I have other data types that also contain Instrument members because then the unmarshalling complexity spreads there too!

This jsonface package enables me to define the unmarshalling logic at the Instrument level, avoiding the leaky-complexity described above.

Also note, the example above just shows a very simple interface struct field, but jsonface is very general; It can handle any data structure, no matter how deep or complex.

See the included examples for more usage information.

Code:

package main

// This example shows how you might normally design your data types and
// serialization logic without jsonface, and then it shows how to do the
// same thing with jsonface.

import (
    "jsonface"

    "fmt"
    "encoding/json"
)

type (
    Instrument interface {
        Play()
    }
    Bell struct{ BellPitch string } // I am using contrived field names
    Drum struct{ DrumSize float64 } // to keep this example simple.

    BandMember struct {
        Name string
        Inst Instrument // <---- Interface Member
    }
)

func (me Bell) Play() { fmt.Printf("Ding (%s Bell)\n", me.BellPitch) }
func (me Drum) Play() { fmt.Printf("Boom (%f Drum)\n", me.DrumSize) }

// // This is the normal solution for this situation; the Instrument unmarshalling
// // complexity leaks out to the BandMember level:
// func (me *BandMember) UnmarshalJSON(bs []byte) error {
//     var data struct {
//         Name string
//         Inst json.RawMessage
//     }
//     err := json.Unmarshal(bs, &data); if err!=nil { return err }
//
//     var Keys map[string]interface{}
//     err = json.Unmarshal(data.Inst, &Keys); if err!=nil { return err }
//
//     var InstrumentObj Instrument
//     if _,has:=Keys["BellPitch"]; has {
//         var bell Bell
//         err = json.Unmarshal(data.Inst, &bell); if err!=nil { return err }
//         InstrumentObj = bell
//     } else if _,has:=Keys["DrumSize"]; has {
//         var drum Drum
//         err = json.Unmarshal(data.Inst, &drum); if err!=nil { return err }
//         InstrumentObj = drum
//     } else {
//         return fmt.Errorf("Unknown Instument Type: %s",data.Inst)
//     }
//
//     me.Name, me.Inst = data.Name, InstrumentObj
//     return nil
// }

// This is the jsonface version of the above function.  It contains the complexity
// within the Instrument type.
func Instrument_UnmarshalJSON(bs []byte) (interface{}, error) {
    var Keys map[string]interface{}
    err := json.Unmarshal(bs, &Keys)
    if err != nil {
        return nil, err
    }

    if _, has := Keys["BellPitch"]; has {
        var bell Bell
        err = json.Unmarshal(bs, &bell)
        if err != nil {
            return nil, err
        }
        return bell, nil
    } else if _, has := Keys["DrumSize"]; has {
        var drum Drum
        err = json.Unmarshal(bs, &drum)
        if err != nil {
            return nil, err
        }
        return drum, nil
    } else {
        return nil, fmt.Errorf("Unknown Instument Type: %s", bs)
    }
}

// Register the callback with jsonface:
func init() {
    jsonface.AddGlobalCB("jsonface_test.Instrument", Instrument_UnmarshalJSON)
}

func main() {
    bs := []byte(`{"Name":"Gabriella","Inst":{"BellPitch":"B♭"}}`)
    var bandmember BandMember
    err := jsonface.GlobalUnmarshal(bs, &bandmember)
    if err != nil {
        panic(err)
    }
    fmt.Printf("bandmember=%#v\n", bandmember)

}

Code:

package main

// This is a basic example of direct marshalling and unmarshalling of an interface.
// In this particular example, the different shapes happen to have differently-
// named fields, so their types can be easily detected without adding extra type
// information to the marshalled data.

import (
    "jsonface"

    "fmt"
    "math"
    "errors"
    "encoding/json"
)

type (
    // type Shape interface { Area() float64 }  // Defined in common_test.go
    Circle struct{ Radius float64 }
    Square struct{ Length float64 }
)

func (me Circle) Area() float64 { return math.Pi * me.Radius * me.Radius }
func (me Square) Area() float64 { return me.Length * me.Length }

func Shape_UnmarshalJSON_1(bs []byte) (interface{}, error) {
    var data map[string]float64
    err := json.Unmarshal(bs, &data)
    if err != nil {
        return nil, err
    }
    if v, has := data["Radius"]; has {
        if v < 0 {
            return nil, errors.New("Negative Radius")
        }
        return Circle{v}, nil
    } else if v, has := data["Length"]; has {
        if v < 0 {
            return nil, errors.New("Negative Length")
        }
        return Square{v}, nil
    } else {
        return nil, fmt.Errorf("Unknown Shape Type: %s", bs)
    }
}

func main() {
    // Don't use ResetGlobalCBs in normal circumstances.  We need to use it here
    // so our tests don't conflict:
    jsonface.ResetGlobalCBs()
    // This would normally be placed in an init() function, but I can't do that
    // here because it conflicts with other tests:
    jsonface.AddGlobalCB("jsonface_test.Shape", Shape_UnmarshalJSON_1)

    var s1 Shape = Circle{2.5}
    var s2 Shape = Square{5.0}
    fmt.Printf("Before: s1=%#v s2=%#v\n", s1, s2)

    s1bs, err := json.Marshal(s1)
    if err != nil {
        panic(err)
    }
    s2bs, err := json.Marshal(s2)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Marshalled: s1=%s s2=%s\n", s1bs, s2bs)

    err = jsonface.GlobalUnmarshal(s1bs, &s1)
    if err != nil {
        panic(err)
    }
    err = jsonface.GlobalUnmarshal(s2bs, &s2)
    if err != nil {
        panic(err)
    }
    fmt.Printf("After : s1=%#v s2=%#v\n", s1, s2)

}

Code:

package main

// This is another example of direct marshalling and unmarshalling of an interface.
// In this example, the shapes have fields with the same name, therefore we need to
// add some extra type information during marshalling.

import (
    "jsonface"

    "fmt"
    "math"
    "errors"
    "encoding/json"
)

type (
    // type Shape interface { Area() float64 }  // Defined in common_test.go
    Pentagon struct{ Side float64 }
    Hexagon  struct{ Side float64 }
)

func (me Pentagon) Area() float64 {
    return (1.0 / 4.0) * math.Sqrt(5*(5+2*math.Sqrt(5))) * me.Side * me.Side
}
func (me Hexagon) Area() float64 { return (3.0 / 2.0) * math.Sqrt(3) * me.Side * me.Side }

func Shape_UnmarshalJSON_2(bs []byte) (interface{}, error) {
    var data struct {
        Type string
        Side float64
    }
    err := json.Unmarshal(bs, &data)
    if err != nil {
        return nil, err
    }
    if data.Side < 0 {
        return nil, errors.New("Negative Side")
    }

    switch data.Type {
    case "Pentagon":
        return Pentagon{data.Side}, nil
    case "Hexagon":
        return Hexagon{data.Side}, nil
    default:
        return nil, fmt.Errorf("Unknown Shape Type: %s", bs)
    }
}

func (me Pentagon) MarshalJSON() ([]byte, error) {
    data := struct {
        Type string
        Side float64
    }{"Pentagon", me.Side}
    return json.Marshal(data)
}
func (me Hexagon) MarshalJSON() ([]byte, error) {
    data := struct {
        Type string
        Side float64
    }{"Hexagon", me.Side}
    return json.Marshal(data)
}

func main() {
    // Don't use ResetGlobalCBs in normal circumstances.  We need to use it here
    // so our tests don't conflict:
    jsonface.ResetGlobalCBs()
    // This would normally be placed in an init() function, but I can't do that
    // here because it conflicts with other tests:
    jsonface.AddGlobalCB("jsonface_test.Shape", Shape_UnmarshalJSON_2)

    var s1 Shape = Pentagon{5}
    var s2 Shape = Hexagon{5}
    fmt.Printf("Before: s1=%#v s2=%#v\n", s1, s2)

    s1bs, err := json.Marshal(s1)
    if err != nil {
        panic(err)
    }
    s2bs, err := json.Marshal(s2)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Marshalled: s1=%s s2=%s\n", s1bs, s2bs)

    err = jsonface.GlobalUnmarshal(s1bs, &s1)
    if err != nil {
        panic(err)
    }
    err = jsonface.GlobalUnmarshal(s2bs, &s2)
    if err != nil {
        panic(err)
    }
    fmt.Printf("After : s1=%#v s2=%#v\n", s1, s2)

}

Code:

package main

// In this example, we show that jsonface supports unmarshalling of interfaces
// that are stored in arbitrary composite types, such as structs, slices, and maps.
// jsonface is completely recursive and general, so every data type is supported,
// no matter how complex.

import (
    "jsonface"

    "fmt"
    "encoding/json"
)

type (
    Food interface{}

    Water      struct{}
    Ice        Water                // Water can transform into Ice.
    Grass      struct{ W Water }    // A Grass consumes 1 Water.
    Corn       struct{ Ws []Water } // A Corn consumes multiple Waters.
    Cornflakes struct{ C Corn }     // Cornflakes is made of Corn.
    Cow        struct {             // Cow is a Food that also eats Foods.
        Name string
        Ate  []Food
    }
    Milk     struct{}
    Cream    Milk     // Milk can transform into Cream.
    IceCream struct { // IceCream consumes 1 Ice and 1 Cream.
        I   Ice
        C   Cream
    }
    MealName string // Breakfast, Lunch, Dinner, etc.
    Girl     struct {
        Name  string
        Meals map[MealName][]Food
    }
)

func Food_UnmarshalJSON(bs []byte) (interface{}, error) {
    var data struct{ Type string }
    err := json.Unmarshal(bs, &data)
    if err != nil {
        return nil, err
    }

    switch data.Type {
    case "Water":
        return Water{}, nil
    case "Ice":
        return Ice{}, nil
    case "Grass":
        var x Grass
        err = jsonface.GlobalUnmarshal(bs, &x)
        if err != nil {
            return nil, err
        }
        return x, nil
    case "Corn":
        var x Corn
        err = jsonface.GlobalUnmarshal(bs, &x)
        if err != nil {
            return nil, err
        }
        return x, nil
    case "Cornflakes":
        var x Cornflakes
        err = jsonface.GlobalUnmarshal(bs, &x)
        if err != nil {
            return nil, err
        }
        return x, nil
    case "Cow":
        // The Cow type contains nested Food interfaces which must also be unmarshalled.
        type X Cow // Use indirection to avoid infinite recursion.
        var x X
        err = jsonface.GlobalUnmarshal(bs, &x)
        if err != nil {
            return nil, err
        }
        return Cow(x), nil
    case "Milk":
        return Milk{}, nil
    case "Cream":
        return Cream{}, nil
    case "IceCream":
        var x IceCream
        err = jsonface.GlobalUnmarshal(bs, &x)
        if err != nil {
            return nil, err
        }
        return x, nil
    default:
        return nil, fmt.Errorf("Unknown Food Type: %s", bs)
    }
}

func (me Water) MarshalJSON() ([]byte, error) {
    data := struct{ Type string }{"Water"}
    return json.Marshal(data)
}
func (me Ice) MarshalJSON() ([]byte, error) {
    data := struct{ Type string }{"Ice"}
    return json.Marshal(data)
}
func (me Grass) MarshalJSON() ([]byte, error) {
    data := struct {
        Type string
        W    Water
    }{"Grass", me.W}
    return json.Marshal(data)
}
func (me Corn) MarshalJSON() ([]byte, error) {
    data := struct {
        Type string
        Ws   []Water
    }{"Corn", me.Ws}
    return json.Marshal(data)
}
func (me Cornflakes) MarshalJSON() ([]byte, error) {
    data := struct {
        Type string
        C    Corn
    }{"Cornflakes", me.C}
    return json.Marshal(data)
}
func (me Cow) MarshalJSON() ([]byte, error) {
    data := struct {
        Type string
        Name string
        Ate  []Food
    }{"Cow", me.Name, me.Ate}
    return json.Marshal(data)
}
func (me Milk) MarshalJSON() ([]byte, error) {
    data := struct{ Type string }{"Milk"}
    return json.Marshal(data)
}
func (me Cream) MarshalJSON() ([]byte, error) {
    data := struct{ Type string }{"Cream"}
    return json.Marshal(data)
}
func (me IceCream) MarshalJSON() ([]byte, error) {
    data := struct {
        Type string
        I    Ice
        C    Cream
    }{"IceCream", me.I, me.C}
    return json.Marshal(data)
}

func main() {
    // Don't use ResetGlobalCBs in normal circumstances.  We need to use it here
    // so our tests don't conflict:
    jsonface.ResetGlobalCBs()
    // These would normally be placed in an init() function, but I can't do that
    // here because it conflicts with other tests:
    jsonface.AddGlobalCB("jsonface_test.Food", Food_UnmarshalJSON)

    // It rains.  10 Waters are produced:
    waters := make([]Water, 10)
    water := func() (w Water) {
        w, waters = waters[len(waters)-1], waters[:len(waters)-1]
        return
    }

    // Some Grass and Corn grows:
    grass := Grass{water()}
    corn1 := Corn{[]Water{water(), water()}}
    corn2 := Corn{[]Water{water(), water(), water()}}

    // One Corn is turned into Cornflakes:
    cornflakes := Cornflakes{corn1}

    // The cow eats Grass, Corn, and Water:
    cow := Cow{"Bessie", []Food{grass, corn2, water()}}

    // The cow produces one Milk for each Food it ate:
    milks := make([]Milk, len(cow.Ate))
    milk := func() (m Milk) {
        m, milks = milks[len(milks)-1], milks[:len(milks)-1]
        return
    }

    // One Milk is turned into Cream:
    cream := Cream(milk())

    // One Water is turned into Ice:
    ice := Ice(water())

    // Make IceCream:
    icecream := IceCream{ice, cream}

    // Gabriella eats cereal for breakfast, icecream for lunch, and steak for dinner:
    gabriella := Girl{"Gabriella", map[MealName][]Food{
        "Breakfast": {cornflakes, milk()},
        "Lunch":     {icecream, water()},
        "Dinner":    {cow, milk()},
    }}
    fmt.Printf("Before: gabriella=%#v\n", gabriella)

    bs, err := json.Marshal(gabriella)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Marshalled: gabriella=%s\n", bs)

    err = jsonface.GlobalUnmarshal(bs, &gabriella)
    if err != nil {
        panic(err)
    }
    fmt.Printf("After : gabriella=%#v\n", gabriella)

}

Index

Examples

Package Files

lib.go

func AddGlobalCB Uses

func AddGlobalCB(name TypeName, cb CB)

AddGlobalCB adds an entry to the global callback registry. Then, when GlobalUnmarshal() is called, this global registry will be used to perform the unmarshalling. You will normally call AddGlobalCB() during program initialization (from an init() function) to register your unmarshallable interfaces.

func GlobalUnmarshal Uses

func GlobalUnmarshal(bs []byte, destPtr interface{}) error

GlobalUnmarshal uses the global callback registry (created by the AddGlobalCB() funcion) to unmarshal data.

func ResetGlobalCBs Uses

func ResetGlobalCBs()

ResetGlobalCBs removes all definitions from the global callback registry. You probably shouldn't use this -- I just need to use it from my unit tests because Go runs all tests consecutively without resetting the namespace, and so my tests conflict with eachother. I need to use this to reset the registry between tests.

If you think you need this, instead consider using Unmarshal() and passing in your own CBMap.

func Unmarshal Uses

func Unmarshal(bs []byte, destPtr interface{}, cbs CBMap) error

Unmarshal uses the provided CBMap to perform unmarshalling. It does not use the global callback registry. Most users will want to use GlobalUnmarshal() instead, but this function is provided for extra flexibility in advanced situations.

Some "advanced situations" where you might want to use Unmarshal() are:

* You want to unmarshal many objects in parallel.  (GlobalUnmarshal
  uses a lock, and therefore only processes items in series.)

* You only want the callback registration to be temporary.

* You are creating and *destroying* types dynamically.

* You need to avoid name collisions.  (Not usually a problem.)

Code:

package main

// This example shows how to use the jsonface.Unmarshal() function directly for
// advanced situations.  For normal cases, you'd use jsonface.GlobalUnmarshal() instead.

import (
    "jsonface"

    "fmt"
    "math"
    "encoding/json"
)

type (
    Transporter interface {
        Transport(distance_km float64) (time_hours float64)
    }

    Bike  struct{ NumGears int }
    Bus   struct{ LineName string }
    Tesla struct{ Charge float64 } // Charge is a number between 0 and 1.
)

func (me Bike) Transport(distance float64) (time float64) {
    // A Bike can go at least 8 km/h, and even faster with more gears:
    return distance / (8 + math.Sqrt(float64(me.NumGears)))
}
func (me Bus) Transport(distance float64) (time float64) {
    // Some bus lines are slower than others:
    var speed float64
    switch me.LineName {
    case "7":
        speed = 10
    case "185":
        speed = 12
    default:
        panic(fmt.Errorf("Unknown Bus Line: %s", me.LineName))
    }
    return distance / speed
}
func (me Tesla) Transport(distance float64) (time float64) {
    // A Tesla goes slower as it loses charge.
    // For simplicity of this example, the car does not lose charge during transportation.
    speed := 100 * me.Charge
    return distance / speed
}

func Transporter_UnmarshalJSON(bs []byte) (interface{}, error) {
    var data struct{ Type string }
    err := json.Unmarshal(bs, &data)
    if err != nil {
        return nil, err
    }

    switch data.Type {
    case "Bike":
        var bike Bike
        err := json.Unmarshal(bs, &bike)
        if err != nil {
            return nil, err
        }
        return bike, nil
    case "Bus":
        var bus Bus
        err := json.Unmarshal(bs, &bus)
        if err != nil {
            return nil, err
        }
        return bus, nil
    case "Tesla":
        var tesla Tesla
        err := json.Unmarshal(bs, &tesla)
        if err != nil {
            return nil, err
        }
        return tesla, nil
    default:
        return nil, fmt.Errorf("Unknown Transporter Type: %s", bs)
    }
}

func main() {
    var ts []Transporter
    bs := []byte(`[{ "Type":"Bike", "NumGears":9 }, { "Type":"Bus", "LineName":"7" }]`)
    cbmap := jsonface.CBMap{"jsonface_test.Transporter": Transporter_UnmarshalJSON}
    err := jsonface.Unmarshal(bs, &ts, cbmap)
    if err != nil {
        panic(err)
    }
    fmt.Printf("%#v\n", ts)

}

type CB Uses

type CB func([]byte) (interface{}, error)

'CB' means 'Callback'. It is used for unmarshalling, with the same interface as an UnmarshalJSON method.

type CBMap Uses

type CBMap map[TypeName]CB

CBMap is a TypeName-->CB mapping. It is used to tell the jsonface system which callbacks to use for which types.

type StuntDouble Uses

type StuntDouble string

StuntDouble is a type used internally within jsonface. Users of jsonface should ignore this type. It is an exported symbol (capitalized) for technical reasons -- the Go json unmarshaller requires destination types to be exported; an unexported symbol (lowercase) would not work. I apologize for the API noise.

func (StuntDouble) MarshalJSON Uses

func (me StuntDouble) MarshalJSON() ([]byte, error)

func (*StuntDouble) UnmarshalJSON Uses

func (me *StuntDouble) UnmarshalJSON(bs []byte) error

type TypeName Uses

type TypeName string

TypeName is the name of a type (usually prefixed by the package name). If you don't know the correct TypeName to use, try the GetTypeName() function.

func GetTypeName Uses

func GetTypeName(x interface{}) TypeName

GetTypeName can help you understand the correct TypeNames to use during development. After you understand how the TypeNames are made, you will usually just hard-code the names into your code, rather than using this function.

Coincidentally, this function produces the same result as fmt.Sprintf("%T",x) .

Code:

package main

import (
    "jsonface"

    "fmt"
    "os"
)

type A int64

func main() {
    var i int64
    fmt.Println("i:", jsonface.GetTypeName(i))

    var a A
    fmt.Println("a:", jsonface.GetTypeName(a))

    fmt.Println("&a:", jsonface.GetTypeName(&a))

    fmt.Println("os.Stdout:", jsonface.GetTypeName(os.Stdout))

}

Package jsonface imports 7 packages (graph). Updated 2019-09-25. Refresh now. Tools for package owners.