package
0.0.0-20201029031353-9742f5acb6e0
Repository: https://github.com/cachecashproject/go-cachecash.git
Documentation: pkg.go.dev

# README

Stable byte serialisation a-la protobuf

Code Design

Note: this is aspirational.

The config file describes the desired native language types and their serialised behaviours.

This is parsed into a data structure that provides an abstraction that can render a native language type and the required public (de)serialisation code for it.

For golang this is comprised of:

  • The struct definition
  • The Marshal method
  • The MarshalTo method
  • The Unmarshal Method
  • The UnMarshalFrom method
  • The Size method

Each type is expected to self delimit - no exterior containers are supplied. If a given type isn't of well defined size, then the serialisation code for that type should include its own length prefix tag.

Additionally though, to allow for clean and safe deserialisation, each type also creates additional helper methods:

  • MinimumSize - the smallest size that this type is permitted to be deserialised into. This is useful as it allows rolling up the requirements for structs and the like.

The abstract data structure has methods on it to emit the above methods, but also, to help write out those methods, it can be asked to write out valid default value - this is distinct from a zero value, because pointer types will be given an instance of the type they point at.

  • DefaultValueFor

On tests

Tests generate and then run generated tests on the generated code. This code is generated in ./ranger/testdata/pkg. If you wish to re-run the tests without a generation step (to test code you hacked up), run:

$ go test -race -v ./ranger/testdata/pkg -count 1

To fuzz:

$ make fuzz FUZZ=ranger/testdata/pkg

After running the first generation (AKA, run this first):

$ go test -race -v ./ranger

# Functions

Parse parses the content and returns a ConfigFormat; if an error is returned ConfigFormat is invalid.
ParseFile parses the content in a file specified by filename and returns a ConfigFormat; if an error is returned ConfigFormat is invalid.
UvarintSize calculates the size for a binary.Uvarint.

# Variables

ErrBadInterface is for when interface types (enums) are unaccounted for.
ErrLeftOverBytes is from when unmarhsals leave dangling content.
ErrLengthMismatch is when two lengths should match but do not.
ErrMarshalLength is returned when the marshal length does not match the generated content.
ErrShortRead indicates to users when an unmarshaling error has occurred because we ran out of bytes.
ErrShortWrite indicates to users when a marshal error has occurred because we ran out of bytes.
ErrTooLarge is for when values exceeed their input boundaries.
ErrTooMany is for when a length constraint was exceeded.

# Structs

ConfigFormat defines the format of the configuration file used to generate code -- this is the top level.
ConfigInterface defines a polymorphic type to marshal.
ConfigMatch specifies matching rules for validations.
ConfigRequire is hard requirements for validations.
ConfigType is the type definition wrapper; used for specifying member fields as well as any struct-level operations to apply such as validations or filtering.
ConfigTypeDefinition is the definition of an individual type member.
No description provided by the author
No description provided by the author
Integral represents integers that can be static or variable length.
ItemInstance adapts a field for use in arrays.
No description provided by the author
A static sized UInt8.

# Interfaces

Marshaler is an interface to define how marshaling happens in Ranger.
A Type is a type for which we can emit (de)serialisation code.
TypeInstance is an instance of a type e.g.