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 ¶
Constants ¶
This section is empty.
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") // ErrNoCodec is returned when a type cannot be marshaled or unmarshaled, // i.e. it is neither a struct nor implements StringMap(Un)marshaler. ErrNoCodec = errors.New("not an encodable or decodable type") )
Functions ¶
func Marshal ¶
Marshal returns the map[string]string representation of v, which must be a struct or implementing StringMapMarshaler. When implementing the interface, the map is returned verbatim from its method along with the error value. When not, Marshal reads every exported field and translates it into a (key, value) pair to be added to the resulting map. Interfaces or pointers to struct are also accepted.
Marshal converts all fields with built-in types except arrays, functions and channels, plus structs implementing encoding.TextMarshaler or fmt.Stringer, checked in this exact order. If a field is a pointer to a supported type, the underlying type's value is marshaled. If the pointer is nil, it is marshaled as it had the underlying type's zero value unless `omitempty` is specified.
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" unless // it has the zero value as defined by the Go specifications. // In such case, the field is not added to the map. Field int `redmap:"customName,omitempty"` // Field appears in the map as key "Field" (the default), but // the field is skipped if zero. 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 or implementing StringMapMarshaler. // The resulting map is added to the final map with keys flattened, // constructed in the "customName.subKeyName" format. Field int `redmap:"customName,inline"`
func Unmarshal ¶
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 fmt.Stringer which doesn't have an inverse.
The decoding of each struct field can be customized by the format string documented in Marshal.
Types ¶
type StringMapMarshaler ¶ added in v1.1.0
StringMapMarshaler is the interface implemented by types that can marshal themselves into a map of strings.
type StringMapUnmarshaler ¶ added in v1.1.0
StringMapUnmarshaler is the interface implemented by types that can unmarshal themselves from a map of strings. Implementations must copy the given map if they wish to modify it.
Source Files