stramp

README

Stramp

What?

Convert a struct to a flat map[string]string.

Why?

Golang's struct is a natural representation for semantically related key-value pairs. Lots of key-value stores (like etcd) don't have native support for nested structures. Stramp flattens a possibly nested struct into a flat key-value map.

How?

Define your struct. Any fields which are not exported or are missing the stramp tag are ignored.

type Person struct {
    Name      Name     `stramp:"name"`
    Nicknames []string `stramp:"nicknames"`
    Age       int      `stramp:"age"`
}

type Name struct {
    FirstName string `stramp:"first_name"`
    Surname   string `stramp:"surname"`
}

a := Person{
    Name: Name{
        FirstName: "John",
        Surname:   "Smith",
    },
    Nicknames: []string{"Jonny", "James"},
    Age:       55,
}

kv, _ := stramp.Stramp(a)

b := Person{}

_ = stramp.DeStramp(kv, &b)

The Basics

Supported Types

• int, int8, int16, int32, int64
• uint
• float32, float64
• string
• bool
• slice (int | float64 | string)
• struct

Keys

Fields

The key for each struct field is given by its tag.

type A struct {
    Foo string `stramp:"foo"`
}

If the tag etcd clashes, you can change it:

stramp.TagKey = "something"

Nesting

Nesting is represented in the keys using a separator. The default is . (a dot).

// Change separator to a forward slash
stramp.Sep = "/"

Slice elements are given a key based on their index. By default, the index is used unchanged.

// Change index key representation to use square brackets
stramp.IndexKey = func(i int) string {
    return fmt.Sprintf("[%d]", i)
}

If you change the IndexKey function, you should also change the inverse KeyIndex function to match. Note that KeyIndex is not used within stramp.Stramp nor stramp.DeStramp, thus you need only change it if you use the getter or setter functions.

TODO

• Unit Testing
• Support all fundamental types
• Support common built-in types (like time.Duration)
• Refactor project to make better use of CoR

Documentation

Index

• Variables
• func DeStramp(kv KV, i interface{}) error
• func Get(key string, i interface{}) (interface{}, error)
• func Key(parts ...string) string
• func UnMarshal(prefix string, kv KV, i interface{}) error
• func UnMarshalFloat(prefix string, kv KV, i interface{}) error
• func UnMarshalInt(prefix string, kv KV, i interface{}) error
• func UnMarshalSlice(prefix string, kv KV, i interface{}) error
• func UnMarshalString(prefix string, kv KV, i interface{}) error
• func UnMarshalStruct(prefix string, kv KV, i interface{}) error
• type IndexKeyFn
• type KV
  • func Marshal(prefix string, i interface{}) (KV, error)
  • func MarshalFloat(prefix string, i interface{}) (KV, error)
  • func MarshalInt(prefix string, i interface{}) (KV, error)
  • func MarshalSlice(prefix string, i interface{}) (KV, error)
  • func MarshalString(prefix string, i interface{}) (KV, error)
  • func MarshalStruct(prefix string, i interface{}) (KV, error)
  • func Stramp(i interface{}) (KV, error)
  • func (kv KV) Merge(other KV)
• type KeyIndexFn
• type Marshaler
• type UnMarshaler

Variables

var (
	MarshalChain []Marshaler

	ErrTypeMismatch    = errors.New("type mismatch")
	ErrUnsupportedType = errors.New("unsupported type")
	ErrFailedMarshal   = errors.New("failed to marshal")
)

var (
	// Sep is the key separator for nested keys
	Sep = "."

	// TagKey is the tag prefix for struct fields
	TagKey = "stramp"

	// RequireTag defines if struct fields which do not have a tag named TagKey should be ignored.
	// If false, the field's name will be used if no tag has been set.
	RequireTag = false

	// IndexKey translates a slice index into a string key
	IndexKey = func(i int) string { return strconv.FormatInt(int64(i), 10) }

	KeyIndex = func(i string) int {
		x, err := strconv.ParseInt(i, 10, 64)

		if err != nil {
			return -1
		}

		return int(x)
	}
)

var (
	UnMarshalChain []UnMarshaler

	ErrImmutableType   = errors.New("destination type is immutable")
	ErrFailedUnMarshal = errors.New("failed to unmarshal")
	ErrMissingKey      = errors.New("missing key")
)

var (
	ErrNotStruct = errors.New("attempt to stramp non-struct type")
)

var (
	ErrUnknownField = errors.New("unknown field")
)

Functions

func DeStramp

func DeStramp(kv KV, i interface{}) error

func Get

func Get(key string, i interface{}) (interface{}, error)

func Key

func Key(parts ...string) string

Key joins all non-empty strings given into a single string key using the Sep separator.

func UnMarshal

func UnMarshal(prefix string, kv KV, i interface{}) error

func UnMarshalFloat

func UnMarshalFloat(prefix string, kv KV, i interface{}) error

func UnMarshalInt

func UnMarshalInt(prefix string, kv KV, i interface{}) error

func UnMarshalSlice

func UnMarshalSlice(prefix string, kv KV, i interface{}) error

func UnMarshalString

func UnMarshalString(prefix string, kv KV, i interface{}) error

func UnMarshalStruct

func UnMarshalStruct(prefix string, kv KV, i interface{}) error

Types

type IndexKeyFn

type IndexKeyFn func(int) string

IndexKeyFn is a function that translates a slice index into a string key.

type KV

type KV map[string]string

KV is a string -> string mapping

func Marshal

func Marshal(prefix string, i interface{}) (KV, error)

func MarshalFloat

func MarshalFloat(prefix string, i interface{}) (KV, error)

func MarshalInt

func MarshalInt(prefix string, i interface{}) (KV, error)

func MarshalSlice

func MarshalSlice(prefix string, i interface{}) (KV, error)

func MarshalString

func MarshalString(prefix string, i interface{}) (KV, error)

func MarshalStruct

func MarshalStruct(prefix string, i interface{}) (KV, error)

func Stramp

func Stramp(i interface{}) (KV, error)

func (KV) Merge

func (kv KV) Merge(other KV)

Merge merges in the key-value pairs from the other KV. In case of duplicate keys, those from the other KV take precedence.

type KeyIndexFn

type KeyIndexFn func(string) int

KeyIndexFn is a function that translates a string key into a slice index.

type Marshaler

type Marshaler func(prefix string, i interface{}) (KV, error)

type UnMarshaler

type UnMarshaler func(prefix string, kv KV, i interface{}) error