Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update readme text, examples, and badges #24

Merged
merged 1 commit into from
Jan 29, 2023
Merged

update readme text, examples, and badges #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 6 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

![Marshmallow Campfire](https://raw.githubusercontent.com/PerimeterX/marshmallow/assets/campfire.png)

[![CodeQL Status](https://img.shields.io/github/workflow/status/perimeterx/marshmallow/CodeQL?label=CodeQL&logo=github)](https://github.com/PerimeterX/marshmallow/actions/workflows/codeql.yml?query=branch%3Amain++)
[![Run Tests](https://img.shields.io/github/workflow/status/perimeterx/marshmallow/Go?label=Run%20Tests&logo=github)](https://github.com/PerimeterX/marshmallow/actions/workflows/go.yml?query=branch%3Amain)
[![Dependency Review](https://img.shields.io/github/workflow/status/perimeterx/marshmallow/Dependency%20Review?label=Dependency%20Review&logo=github)](https://github.com/PerimeterX/marshmallow/actions/workflows/dependency-review.yml?query=branch%3Amain)
[![CodeQL Status](https://img.shields.io/github/actions/workflow/status/perimeterx/marshmallow/codeql.yml?branch=main&logo=github&label=CodeQL)](https://github.com/PerimeterX/marshmallow/actions/workflows/codeql.yml?query=branch%3Amain++)
[![Run Tests](https://img.shields.io/github/actions/workflow/status/perimeterx/marshmallow/go.yml?branch=main&logo=github&label=Run%20Tests)](https://github.com/PerimeterX/marshmallow/actions/workflows/go.yml?query=branch%3Amain)
[![Dependency Review](https://img.shields.io/github/actions/workflow/status/perimeterx/marshmallow/dependency-review.yml?logo=github&label=Dependency%20Review)](https://github.com/PerimeterX/marshmallow/actions/workflows/dependency-review.yml?query=branch%3Amain)
[![Go Report Card](https://goreportcard.com/badge/github.com/perimeterx/marshmallow)](https://goreportcard.com/report/github.com/perimeterx/marshmallow)
![Manual Code Coverage](https://img.shields.io/badge/coverage-91.9%25-green)
![Manual Code Coverage](https://img.shields.io/badge/coverage-92.4%25-green)
[![Go Reference](https://pkg.go.dev/badge/github.com/perimeterx/marshmallow.svg)](https://pkg.go.dev/github.com/perimeterx/marshmallow)
[![Licence](https://img.shields.io/github/license/perimeterx/marshmallow)](LICENSE)
[![Latest Release](https://img.shields.io/github/v/release/perimeterx/marshmallow)](https://github.com/PerimeterX/marshmallow/releases)
Expand Down Expand Up @@ -49,7 +49,6 @@ import (
)

func main() {
marshmallow.EnableCache() // this is used to boost performance, read more below
v := struct {
Foo string `json:"foo"`
Boo []int `json:"boo"`
Expand All @@ -60,6 +59,8 @@ func main() {
}
```

**Examples can be found [here](example_test.go)**

## Performance Benchmark And Alternatives

Marshmallow performs best when dealing with mixed data - when some fields are known and some are unknown.
Expand Down Expand Up @@ -183,8 +184,6 @@ Marshmallow also supports caching of refection information using
and
[EnableCustomCache](https://github.com/PerimeterX/marshmallow/blob/d3500aa5b0f330942b178b155da933c035dd3906/cache.go#L35).

**Examples can be found [here](example_test.go)**

# Marshmallow Logo

Marshmallow logo and assets by [Adva Rom](https://www.linkedin.com/in/adva-rom-7a6738127/) are licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.<br />
Expand Down
225 changes: 161 additions & 64 deletions example_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,122 +3,235 @@ package marshmallow_test
import (
"fmt"
"github.com/perimeterx/marshmallow"
"sync"
)

type flatStruct struct {
Foo string `json:"foo"`
Boo []int `json:"boo"`
// ExampleBasicUnmarshal shows a basic example usage of marshmallow's unmarshalling capabilities
func ExampleBasicUnmarshal() {
// we have the following data
data := []byte(`{"name":"some name", "values": [1, 2, 3], "more_data": "some stuff I am not interested in..."}`)
// we want to read the "name" field, and modify the "values" field.
// we're not directly interested in the other fields, but we do want to retain them.

type exampleStruct struct {
Name string `json:"name"`
Values []int `json:"values"`
}

v := exampleStruct{}
// we pass in a struct containing the fields we're interested in,
// marshmallow will populate it and return a result map containing all data
result, err := marshmallow.Unmarshal(data, &v)
if err != nil {
panic(err)
}

fmt.Printf("Struct data: %+v\n", v)
fmt.Printf("Map data: %+v\n", result)

// now we can work with the struct data in a safe and maintainable manner
v.Values[0] = 42
fmt.Printf("Name is %s\n", v.Name)

// pointer value changes in the struct will also be visible from the map
// more info at https://github.com/PerimeterX/marshmallow/issues/23#issuecomment-1403409592
fmt.Printf("Map data after changes: %+v\n", result)

// Output:
// Struct data: {Name:some name Values:[1 2 3]}
// Map data: map[more_data:some stuff I am not interested in... name:some name values:[1 2 3]]
// Name is some name
// Map data after changes: map[more_data:some stuff I am not interested in... name:some name values:[42 2 3]]
}

// ExampleExcludeKnownFields shows how to use the WithExcludeKnownFieldsFromMap option to exclude struct fields
// from the result map. more info at https://github.com/PerimeterX/marshmallow/issues/16
func ExampleExcludeKnownFields() {
type exampleStruct struct {
Foo string `json:"foo"`
Boo []int `json:"boo"`
}

// unmarshal with mode marshmallow.ModeExcludeKnownFieldsFromReturnedMap
// this will return unmarshalled result without known fields
v := exampleStruct{}
result, err := marshmallow.Unmarshal(
[]byte(`{"foo":"bar","boo":[1,2,3],"goo":"untyped"}`),
&v,
marshmallow.WithExcludeKnownFieldsFromMap(true),
)
fmt.Printf("v=%+v, result=%+v, err=%T\n", v, result, err)
// Output:
// v={Foo:bar Boo:[1 2 3]}, result=map[goo:untyped], err=<nil>
}

// ExampleJSONDataHandler shows how to capture nested unknown fields
// more info at https://github.com/PerimeterX/marshmallow/issues/15
func ExampleJSONDataHandler() {
type parentStruct struct {
Known string `json:"known"`
Nested childStruct `json:"nested"`
}

data := []byte(`{"known": "foo","unknown": "boo","nested": {"known": "goo","unknown": "doo"}}`)
p := &parentStruct{}
_, err := marshmallow.Unmarshal(data, p)
fmt.Printf("err: %v\n", err)
fmt.Printf("nested data: %+v\n", p.Nested.Data)
// Output:
// err: <nil>
// nested data: map[known:goo unknown:doo]
}

func ExampleUnmarshal() {
// enable marshmallow cache to boost up performance by reusing field type information.
// ExampleCache shows how to enable marshmallow cache to boost up performance by reusing field type information.
// more info: https://github.com/PerimeterX/marshmallow/blob/22e3c7fe4423d7c5f317d95f84de524253e0aed3/cache.go#L35
func ExampleCache() {
// enable default cache
marshmallow.EnableCache()

type exampleStruct struct {
Foo string `json:"foo"`
Boo []int `json:"boo"`
}
v := exampleStruct{}
_, _ = marshmallow.Unmarshal([]byte(`{"foo":"bar","boo":[1,2,3]}`), &v)

// enable custom cache, you can pass any implementation of the marshmallow.Cache interface
// this lets you control the size of the cache, eviction policy, or any other aspect of it.
marshmallow.EnableCustomCache(&sync.Map{})
}

// ExampleUnmarshalErrorHandling shows all error handling capabilities of marshmallow.Unmarshal
func ExampleUnmarshalErrorHandling() {
type exampleStruct struct {
Foo string `json:"foo"`
Boo []int `json:"boo"`
}

// unmarshal with mode marshmallow.ModeFailOnFirstError and valid value
// this will finish unmarshalling and return a nil err
v := flatStruct{}
v := exampleStruct{}
result, err := marshmallow.Unmarshal([]byte(`{"foo":"bar","boo":[1,2,3]}`), &v)
fmt.Printf("ModeFailOnFirstError and valid value: v=%+v, result=%+v, err=%T\n", v, result, err)

// unmarshal with mode marshmallow.ModeFailOnFirstError and invalid value
// this will return nil result and an error
v = flatStruct{}
v = exampleStruct{}
result, err = marshmallow.Unmarshal([]byte(`{"foo":2,"boo":[1,2,3]}`), &v)
fmt.Printf("ModeFailOnFirstError and invalid value: result=%+v, err=%T\n", result, err)

// unmarshal with mode marshmallow.ModeAllowMultipleErrors and valid value
// this will finish unmarshalling and return a nil err
v = flatStruct{}
result, err = marshmallow.Unmarshal([]byte(`{"foo":"bar","boo":[1,2,3]}`), &v,
marshmallow.WithMode(marshmallow.ModeAllowMultipleErrors))
v = exampleStruct{}
result, err = marshmallow.Unmarshal(
[]byte(`{"foo":"bar","boo":[1,2,3]}`),
&v,
marshmallow.WithMode(marshmallow.ModeAllowMultipleErrors),
)
fmt.Printf("ModeAllowMultipleErrors and valid value: v=%+v, result=%+v, err=%T\n", v, result, err)

// unmarshal with mode marshmallow.ModeAllowMultipleErrors and invalid value
// this will return a partially populated result and an error
v = flatStruct{}
result, err = marshmallow.Unmarshal([]byte(`{"foo":2,"boo":[1,2,3]}`), &v,
marshmallow.WithMode(marshmallow.ModeAllowMultipleErrors))
v = exampleStruct{}
result, err = marshmallow.Unmarshal(
[]byte(`{"foo":2,"boo":[1,2,3]}`),
&v,
marshmallow.WithMode(marshmallow.ModeAllowMultipleErrors),
)
fmt.Printf("ModeAllowMultipleErrors and invalid value: result=%+v, err=%T\n", result, err)

// unmarshal with mode marshmallow.ModeFailOverToOriginalValue and valid value
// this will finish unmarshalling and return a nil err
v = flatStruct{}
result, err = marshmallow.Unmarshal([]byte(`{"foo":"bar","boo":[1,2,3]}`), &v,
marshmallow.WithMode(marshmallow.ModeFailOverToOriginalValue))
v = exampleStruct{}
result, err = marshmallow.Unmarshal(
[]byte(`{"foo":"bar","boo":[1,2,3]}`),
&v,
marshmallow.WithMode(marshmallow.ModeFailOverToOriginalValue),
)
fmt.Printf("ModeFailOverToOriginalValue and valid value: v=%+v, result=%+v, err=%T\n", v, result, err)

// unmarshal with mode marshmallow.ModeFailOverToOriginalValue and invalid value
// this will return a fully unmarshalled result, failing to the original invalid values, and an error
v = flatStruct{}
result, err = marshmallow.Unmarshal([]byte(`{"foo":2,"boo":[1,2,3]}`), &v,
marshmallow.WithMode(marshmallow.ModeFailOverToOriginalValue))
v = exampleStruct{}
result, err = marshmallow.Unmarshal(
[]byte(`{"foo":2,"boo":[1,2,3]}`),
&v,
marshmallow.WithMode(marshmallow.ModeFailOverToOriginalValue),
)
fmt.Printf("ModeFailOverToOriginalValue and invalid value: result=%+v, err=%T\n", result, err)

// unmarshal with mode marshmallow.ModeExcludeKnownFieldsFromReturnedMap and valid value
// this will return unmarshalled result without known fields
v = flatStruct{}
result, err = marshmallow.Unmarshal([]byte(`{"foo":"bar","boo":[1,2,3],"goo":"untyped"}`), &v,
marshmallow.WithExcludeKnownFieldsFromMap(true))
fmt.Printf("ModeExcludeKnownFieldsFromReturnedMap and valid value: v=%+v, result=%+v, err=%T\n", v, result, err)

// Output:
// ModeFailOnFirstError and valid value: v={Foo:bar Boo:[1 2 3]}, result=map[boo:[1 2 3] foo:bar], err=<nil>
// ModeFailOnFirstError and invalid value: result=map[], err=*jlexer.LexerError
// ModeAllowMultipleErrors and valid value: v={Foo:bar Boo:[1 2 3]}, result=map[boo:[1 2 3] foo:bar], err=<nil>
// ModeAllowMultipleErrors and invalid value: result=map[boo:[1 2 3]], err=*marshmallow.MultipleLexerError
// ModeFailOverToOriginalValue and valid value: v={Foo:bar Boo:[1 2 3]}, result=map[boo:[1 2 3] foo:bar], err=<nil>
// ModeFailOverToOriginalValue and invalid value: result=map[boo:[1 2 3] foo:2], err=*marshmallow.MultipleLexerError
// ModeExcludeKnownFieldsFromReturnedMap and valid value: v={Foo:bar Boo:[1 2 3]}, result=map[goo:untyped], err=<nil>
}

func ExampleUnmarshalFromJSONMap() {
// enable marshmallow cache to boost up performance by reusing field type information.
marshmallow.EnableCache()
// ExampleUnmarshalFromJSONMap shows all error handling capabilities of marshmallow.UnmarshalFromJSONMap
func ExampleUnmarshalFromJSONMapErrorHandling() {
type exampleStruct struct {
Foo string `json:"foo"`
Boo []int `json:"boo"`
}

// unmarshal with mode marshmallow.ModeFailOnFirstError and valid value
// this will finish unmarshalling and return a nil err
v := flatStruct{}
result, err := marshmallow.UnmarshalFromJSONMap(
map[string]interface{}{"foo": "bar", "boo": []interface{}{float64(1), float64(2), float64(3)}}, &v)
v := exampleStruct{}
data := map[string]interface{}{"foo": "bar", "boo": []interface{}{float64(1), float64(2), float64(3)}}
result, err := marshmallow.UnmarshalFromJSONMap(data, &v)
fmt.Printf("ModeFailOnFirstError and valid value: v=%+v, result=%+v, err=%T\n", v, result, err)

// unmarshal with mode marshmallow.ModeFailOnFirstError and invalid value
// this will return nil result and an error
v = flatStruct{}
result, err = marshmallow.UnmarshalFromJSONMap(
map[string]interface{}{"foo": float64(2), "boo": []interface{}{float64(1), float64(2), float64(3)}}, &v)
v = exampleStruct{}
data = map[string]interface{}{"foo": float64(2), "boo": []interface{}{float64(1), float64(2), float64(3)}}
result, err = marshmallow.UnmarshalFromJSONMap(data, &v)
fmt.Printf("ModeFailOnFirstError and invalid value: result=%+v, err=%T\n", result, err)

// unmarshal with mode marshmallow.ModeAllowMultipleErrors and valid value
// this will finish unmarshalling and return a nil err
v = flatStruct{}
v = exampleStruct{}
data = map[string]interface{}{"foo": "bar", "boo": []interface{}{float64(1), float64(2), float64(3)}}
result, err = marshmallow.UnmarshalFromJSONMap(
map[string]interface{}{"foo": "bar", "boo": []interface{}{float64(1), float64(2), float64(3)}}, &v,
marshmallow.WithMode(marshmallow.ModeAllowMultipleErrors))
data,
&v,
marshmallow.WithMode(marshmallow.ModeAllowMultipleErrors),
)
fmt.Printf("ModeAllowMultipleErrors and valid value: v=%+v, result=%+v, err=%T\n", v, result, err)

// unmarshal with mode marshmallow.ModeAllowMultipleErrors and invalid value
// this will return a partially populated result and an error
v = flatStruct{}
v = exampleStruct{}
data = map[string]interface{}{"foo": float64(2), "boo": []interface{}{float64(1), float64(2), float64(3)}}
result, err = marshmallow.UnmarshalFromJSONMap(
map[string]interface{}{"foo": float64(2), "boo": []interface{}{float64(1), float64(2), float64(3)}}, &v,
marshmallow.WithMode(marshmallow.ModeAllowMultipleErrors))
data,
&v,
marshmallow.WithMode(marshmallow.ModeAllowMultipleErrors),
)
fmt.Printf("ModeAllowMultipleErrors and invalid value: result=%+v, err=%T\n", result, err)

// unmarshal with mode marshmallow.ModeFailOverToOriginalValue and valid value
// this will finish unmarshalling and return a nil err
v = flatStruct{}
v = exampleStruct{}
data = map[string]interface{}{"foo": "bar", "boo": []interface{}{float64(1), float64(2), float64(3)}}
result, err = marshmallow.UnmarshalFromJSONMap(
map[string]interface{}{"foo": "bar", "boo": []interface{}{float64(1), float64(2), float64(3)}}, &v,
marshmallow.WithMode(marshmallow.ModeFailOverToOriginalValue))
data,
&v,
marshmallow.WithMode(marshmallow.ModeFailOverToOriginalValue),
)
fmt.Printf("ModeFailOverToOriginalValue and valid value: v=%+v, result=%+v, err=%T\n", v, result, err)

// unmarshal with mode marshmallow.ModeFailOverToOriginalValue and invalid value
// this will return a fully unmarshalled result, failing to the original invalid values, and an error
v = flatStruct{}
v = exampleStruct{}
data = map[string]interface{}{"foo": float64(2), "boo": []interface{}{float64(1), float64(2), float64(3)}}
result, err = marshmallow.UnmarshalFromJSONMap(
map[string]interface{}{"foo": float64(2), "boo": []interface{}{float64(1), float64(2), float64(3)}}, &v,
marshmallow.WithMode(marshmallow.ModeFailOverToOriginalValue))
data,
&v,
marshmallow.WithMode(marshmallow.ModeFailOverToOriginalValue),
)
fmt.Printf("ModeFailOverToOriginalValue and invalid value: result=%+v, err=%T\n", result, err)
// Output:
// ModeFailOnFirstError and valid value: v={Foo:bar Boo:[1 2 3]}, result=map[boo:[1 2 3] foo:bar], err=<nil>
Expand All @@ -129,11 +242,6 @@ func ExampleUnmarshalFromJSONMap() {
// ModeFailOverToOriginalValue and invalid value: result=map[boo:[1 2 3] foo:2], err=*marshmallow.MultipleError
}

type parentStruct struct {
Known string `json:"known"`
Nested childStruct `json:"nested"`
}

type childStruct struct {
Known string `json:"known"`

Expand All @@ -143,14 +251,3 @@ type childStruct struct {
func (c *childStruct) HandleJSONData(data map[string]interface{}) {
c.Data = data
}

func ExampleJSONDataHandler() {
data := []byte(`{"known": "foo","unknown": "boo","nested": {"known": "goo","unknown": "doo"}}`)
p := &parentStruct{}
_, err := marshmallow.Unmarshal(data, p)
fmt.Printf("err: %v\n", err)
fmt.Printf("nested data: %+v\n", p.Nested.Data)
// Output:
// err: <nil>
// nested data: map[known:goo unknown:doo]
}