engine

README

format-engine

format-engine is a library designed to create custom formatters like JSON, XML.

Installation

format-engine can be installed like any other Go library through go get:

$ go get github.com/gromey/format-engine

Or, if you are already using Go Modules, you may specify a version number as well:

$ go get github.com/gromey/format-engine@latest

Getting Started

After you get the library, you must generate your type using the following command:

$ go run github.com/gromey/format-engine/cmd/create-format -n=name

In this command, you must specify a name of your new formatter. The name must contain only letters and be as simple as possible.

This command generates a package with the name specified in the generate command. The package will contain two files asserts.go and tag.go.

WARNING: DO NOT EDIT asserts.go.

tag.go will contain the base implementation of your new formatter. You need to implement two functions Encode and Decode.

Encode function receives a value encoded into a byte array, if exists a tag value and a field name, here you can do additional encoding or return the byte array unchanged.

Decode function receives an encoded data, if exists a tag value and a field name, here you must find a byte array representing a value for the current field and perform initial decoding if necessary before returning this byte array.
You can change the input data and for the next field you will receive the data in a modified form, however this will not affect the original data, since you are working with a copy of the data.

Documentation

Index

• Variables
• type Config
• type Default
  • func (d Default[T]) Parse(string, *T) (bool, error)
  • func (d Default[T]) Skip(string) bool
• type Engine
  • func New[T any](tag Tag[T], cfg Config) Engine
• type Tag
• type Writer

Variables

var (
	ErrNotSupportType      = errors.New("cannot support type")
	ErrNilInterface        = errors.New("interface is nil")
	ErrPointerToUnexported = errors.New("cannot set embedded pointer to unexported struct")
	ErrInvalidFormat       = errors.New("the raw data has an invalid format for an object value")
)

Types

type Config

type Config struct {
	// StructOpener a byte array that denotes the beginning of a structure.
	// Will be automatically added when encoding.
	StructOpener []byte
	// StructCloser a byte array that denotes the end of a structure.
	// Will be automatically added when encoding.
	StructCloser []byte
	// UnwrapWhenDecoding this flag tells the library whether to remove the StructOpener and StructCloser bytes of a structure.
	UnwrapWhenDecoding bool
	// ValueSeparator a byte array separating values.
	// Will be automatically added when encoding.
	ValueSeparator []byte
	// RemoveSeparatorWhenDecoding this flag tells the library whether to remove the ValueSeparator.
	RemoveSeparatorWhenDecoding bool
	// Marshaller is used to check if a type implements a type of the Marshaller interface.
	Marshaller reflect.Type
	// Unmarshaler is used to check if a type implements a type of the Unmarshaler interface.
	Unmarshaler reflect.Type
}

type Default

type Default[T any] struct{}

func (Default[T]) Parse

func (d Default[T]) Parse(string, *T) (bool, error)

func (Default[T]) Skip

func (d Default[T]) Skip(string) bool

type Engine

type Engine interface {
	// Marshal encodes the value v and returns the encoded data.
	Marshal(v any) ([]byte, error)
	// Unmarshal decodes the encoded data and stores the result in the value pointed to by v.
	Unmarshal(data []byte, v any) error
}

Engine represents the main functions that the package implements.

func New

func New[T any](tag Tag[T], cfg Config) Engine

New returns a new entity that implements the Engine interface.

type Tag

type Tag[T any] interface {
	// Name returns the name of the tag. It's a mandatory function.
	Name() string
	// Skip returns a flag indicating that the field should be ignored.
	Skip(tagValue string) bool
	// Parse gets a tagValue string, parses the tagValue into tag *T,
	// returns a flag indicating that the field is skipped if it's empty,
	// and if parsing fails, it returns an error.
	Parse(tagValue string, tag *T) (bool, error)
	// Encode takes encoded data and performs secondary encoding.
	// It's a mandatory function.
	Encode(fieldName string, tag *T, in []byte, out Writer) error
	// Decode takes the raw encoded data and performs a primary decode.
	// It's a mandatory function.
	Decode(fieldName string, tag *T, in []byte, out Writer) error
	// IsMarshaller attempts to cast the value to a Marshaller interface,
	// if so, returns a marshal function.
	IsMarshaller(v reflect.Value) (func() ([]byte, error), bool)
	// IsUnmarshaler attempts to cast the value to an Unmarshaler interface,
	// if so, returns an unmarshal function.
	IsUnmarshaler(v reflect.Value) (func([]byte) error, bool)
	// contains filtered or unexported methods
}

Tag describes what functions an entity should implement to use when creating a new Engine entity. The entity must include an engine.Default that implements following default methods:

• Skip;
• Parse.

So it may not implement these methods.

type Writer

type Writer interface {
	Write(p []byte) (n int, err error)
	WriteByte(c byte) error
	WriteString(s string) (n int, err error)
}