redmap

README

Redmap

Redmap is a general purpose Go module to convert structs to map of strings and vice versa, when possible.

One particular use case of Redmap is serializing and deserializing Redis object, which stores everything as strings.

Goals

• Keep the API similar to encoding/json: we do all hate learning yet another library
• API stability
• Excellent test coverage

Installation

In a project using Go modules, run this in your terminal application:

go get github.com/livingsilver94/redmap

When the download finishes, you'll find Redmap under the unsurprising name of redmap.

Usage

This example shows the simplest usage of Redmap. Usage of struct tags and unmarshaling pitfalls are better illustrated in the documentation.

package main

import (
	"fmt"
	"github.com/livingsilver94/redmap"
)

type MyStruct struct {
	AString string
	AnInt   int
}

func main() {
	// Struct to map.
	myS := MyStruct{AString: "universe", AnInt: 42}
	mp, err := redmap.Marshal(myS)
	fmt.Println(mp, err)

	// Map to struct.
	var mySIsBack MyStruct
	err = redmap.Unmarshal(mp, &mySIsBack)
	fmt.Println(mySIsBack, err)
}

Documentation

Index

• Variables
• func Marshal(v interface{}) (map[string]string, error)
• func Unmarshal(data map[string]string, v interface{}) error

Variables

var (
	// ErrNilValue is returned when an argument passed is nil but it should not be.
	ErrNilValue = errors.New("nil")
	// ErrNotPointer is retuned when an argument passed is not a pointer but it should be.
	ErrNotPointer = errors.New("not a pointer")
	// ErrNotStruct is returned when an argument passed is not a struct but it should be.
	ErrNotStruct = errors.New("not a struct type")
)

Functions

func Marshal

func Marshal(v interface{}) (map[string]string, error)

Marshal returns the map[string]string representation of v, which must be a struct, by reading every exported field and translating it into a (key, value) pair to be added to the resulting map. Interfaces or pointers to struct are also accepted.

Marshal converts all non-reference built-in types except arrays, plus structs implementing encoding.TextMarshaler or fmt.Stringer, checked in this exact order.

The encoding of each struct field can be customized by the format string stored under the "redmap" key in the struct field's tag. The format string gives the name of the field, possibly followed by a comma-separated list of options. The name may be empty in order to specify options without overriding the default field name. If the format string is equal to "-", the struct field is excluded from marshaling.

Examples of struct field tags and their meanings:

// Field appears in the map as key "customName".
Field int `redmap:"customName"`

// Field appears in the map as key "customName" and
// the field is omitted from the map if its value
// is empty as defined by the Go language.
Field int `redmap:"customName,omitempty"`

// Field appears in the map as key "Field" (the default), but
// the field is skipped if empty. Note the leading comma.
Field int `redmap:",omitempty"`

// Field is ignored by this package.
Field int `redmap:"-"`

// Field appears in the map as key "-".
Field int `redmap:"-,"`

// Field must be a struct. Field is flattened and its fields
// are added to the map as (key, value) pairs, where the keys
// are constructed in the "customName.subFieldName" format.
Field int `redmap:"customName,inline"`

func Unmarshal

func Unmarshal(data map[string]string, v interface{}) error

Unmarshal sets v's fields according to its map representation contained by data. v must be a pointer to struct or an interface. Neither data nor v can be nil.

Unmarshal uses the inverse of the encodings that Marshal uses, so all the types supported by it are also supported in Unmarshal, except the interfaces: only encoding.TextUnmarshaler can be unmarshaled.

The decoding of each struct field can be customized by the format string documented in Marshal.