parsley

README

Parsley JSON

Parsley JSON is a JSON decoder that parses a JSON string into objects. Parsley JSON uses the definition of a struct to generate code that is efficient and fast. This library is inspired by easyjson.

Installation

go install github.com/Soreing/parsley/parsley@latest
go get github.com/Soreing/parsley

Usage

Objects that implement the ParsleyJSON interfaces can be used in the Unmarshal functions to encode or decode data. The interface can be implemented with the generator (or custom written for rare use cases).

dat := []byte (`{"name": "A Box", "weight": 10.5}`)
box := Box{}

err := parsley.Unmarshal(dat, &box)
if err != nil {
	panic(err)
}

Code Generation

To encode/decode data, first you need to generate the mapping functions for the structs you want to use. The json flag tells the generator to process the defined struct. You can add more flags separated by commas.

//parsley:json
type Box struct {
	Name   string  `json:"name"`
	Weight float64 `json:"weight"`
}

//parsley:json
type BoxList []Box

Run the generator with the path to the file or folder to the module. Assuming the above file is in tests/models/box.go, use the following command:

parsley tests/models/box.go

Struct Flags

Flag	Description
json	Process the struct or type define in the generator
skip	Skip the struct or type define during generation
public	Include private fields in encoding/decoding

Command Line Arguments

Arg	Description
-all	Processes all structs in a file or directory
-public	Include private fields in encoding/decoding for all types
-output_filename	Sets the filename of the generated code
-camel_case	Uses camel case naming for fields unless explicitly defined
-lower_case	Uses lower case naming for fields unless explicitly defined
-kebab_case	Uses kebab case naming for fields unless explicitly defined
-snake_case	Uses snake case naming for fields unless explicitly defined
-pascal_case	Uses pascal case naming for fields unless explicitly defined

Todo List

• Implement reading of scientific (exponential) notation for number fields
• Improve speed of floating point number creation

Documentation

Index

• func Decode(data []byte, val Unmarshaller, cfgs ...Config) error
• func Unmarshal(data []byte, v any) error
• type Config
  • func MergeConfigs(cfgs ...Config) Config
  • func UseFilter(filter []Filter) Config
  • func UseFixedBuffer(bytes int) Config
  • func UseRelativeBuffer(percentage int) Config
• type Filter
• type Unmarshaller

Functions

func Decode

func Decode(data []byte, val Unmarshaller, cfgs ...Config) error

Decode takes a JSON string in a byte array and reads the content of the JSON into an object in the parameter list that implements the Unmarshaller interface. An optional list of config options can be provided to modify the decoder.

func Unmarshal

func Unmarshal(data []byte, v any) error

Unmarshal takes a JSON string in a byte array and reads the content of the JSON into an object in the parameter list. The object must implement the Unmarshaller interface, otherwise it returns an error. This function matches the signature of the standard library's Unmarshal function. To enforce objects implementing the Unmarshaller interface at compile time, use the Decode function instead.

Types

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config describes optional settings that alter the behavior of the encoder/decoder.

func MergeConfigs

func MergeConfigs(cfgs ...Config) Config

MergeConfigs takes multiple config options and merges them into a single object.

func UseFilter

func UseFilter(filter []Filter) Config

UseFilter creates a config from a filter list. Only fields that appear in the filter list will be processed by the encoder/decoder If the filter is nil, all elements get processed.

Example:

var filter = []parsley.Filter{
    {"name": []parsley.Filter{
        {"firstName": nil},
        {"lastName": nil},
    }},
    {"address": []parsley.Filter{
        {"country": nil},
        {"city": nil},
    }},
    {"age": nil},
}

func UseFixedBuffer

func UseFixedBuffer(bytes int) Config

UseFixedBuffer creates a config to add extra buffer space for the encoder. The function adds a fixed number of bytes space.

A larger buffer can speed up encoding by reducing required allocations. Extra buffer space is only recommended if the object contains strings with characters that should be escaped.

func UseRelativeBuffer

func UseRelativeBuffer(percentage int) Config

UseRelativeBuffer creates a config to add extra buffer space for the encoder. The function calculates the length of all string fields and uses a percentage of that as extra buffer space.

A larger buffer can speed up encoding by reducing required allocations. Extra buffer space is only recommended if the object contains strings with characters that should be escaped.

type Filter

type Filter struct {
	Field  string
	Filter []Filter
}

Filter specifies a filter structure with a field name (key) and a nested filter list used for nested objects.

type Unmarshaller

type Unmarshaller interface {
	DecodeObjectPJSON(r *reader.Reader, filter []Filter) error
}

Unmarshaller describes methods for an object to unmarshal a JSON string as a byte array into an object, mapping the values to the fields