unstruct

README

unstruct

unstruct is a library to read external values and decode them into the structs.

unstruct reads values from external sources using Source interface.

It is very simple interface, so you can easily implement custom Source.

Synopsis

import (
	"fmt"
	"os"

	"github.com/aereal/unstruct"
)

func main() {
	decoder := unstruct.NewDecoder(unstruct.NewEnvironmentSource())
	var val struct {
		ExampleString string
		ExampleInt    int
		ExampleBool   bool
	}
	_ = decoder.Decode(&val)
}

See examples on pkg.go.dev.

Installation

go get github.com/aereal/unstruct

Motivation

The practical application may have various and complicated configuration.

If you build the configuration from external data sources, you may face issues like below:

• fetch from remote data sources
  • the application must read secret data that like credentials from remote data sources using secure channels.
• initialization
  • complicated configuration may have many fields; you must initialize all of them.
• validation:
  • you have to check the existence of all of the mandatory fields.
• type conversions
  • the application configuration may include some values that differs from strings, such as numbers, booleans, or anything else.
  • external data sources may support just limited scalar types, so you have to convert/parse external values into the application configuration's values.

unstruct works as simple decoder that decodes external data into Go's values like encoding/json.

License

See LICENSE file.

Documentation

Overview

Package unstruct is a library to read external values and decode them into the structs.

Example

package main

import (
	"fmt"
	"os"

	"github.com/aereal/unstruct"
)

func main() {
	decoder := unstruct.NewDecoder(unstruct.NewEnvironmentSource())
	var val struct {
		ExampleString string
		ExampleInt    int
		ExampleBool   bool
	}
	os.Setenv("EXAMPLE_STRING", "str")
	os.Setenv("EXAMPLE_INT", "42")
	os.Setenv("EXAMPLE_BOOL", "true")
	if err := decoder.Decode(&val); err != nil {
		panic(err)
	}
	fmt.Printf("%#v", val)
}

Output:

struct { ExampleString string; ExampleInt int; ExampleBool bool }{ExampleString:"str", ExampleInt:42, ExampleBool:true}

Index

• Variables
• type DecodeFieldError
  • func (e *DecodeFieldError) Error() string
  • func (e *DecodeFieldError) Is(other error) bool
  • func (e *DecodeFieldError) Unwrap() error
• type Decoder
  • func NewDecoder(srcs ...Source) *Decoder
  • func (d *Decoder) Decode(target any) error
• type EnvironmentSource
  • func NewEnvironmentSource(opts ...EnvironmentSourceOption) *EnvironmentSource
  • func (s *EnvironmentSource) FillValue(path Path, target reflect.Value) error
• type EnvironmentSourceOption
  • func WithPrefix(prefix string) EnvironmentSourceOption
  • func WithSliceDelimiter(delimiter string) EnvironmentSourceOption
• type MapSource
  • func NewMapSource(m map[string]any) *MapSource
  • func (s *MapSource) FillValue(path Path, target reflect.Value) error
• type Path
• type Source
• type UnsupportedTypeError

Examples

• Package

Variables

var (
	ErrInvalidTarget = errors.New("target must be a pointer to the struct")
	ErrValueNotFound = errors.New("no value found")
)

Types

type DecodeFieldError

type DecodeFieldError struct {
	// Field is a struct field that error occurs.
	Field reflect.StructField

	// Err is an error that occurs.
	Err error
}

DecodeFieldError is an error type represents the decode failure on the field.

func (*DecodeFieldError) Error

func (e *DecodeFieldError) Error() string

func (*DecodeFieldError) Is

func (e *DecodeFieldError) Is(other error) bool

func (*DecodeFieldError) Unwrap

func (e *DecodeFieldError) Unwrap() error

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder runs data sources against given target value and completes target value.

func NewDecoder

func NewDecoder(srcs ...Source) *Decoder

func (*Decoder) Decode

func (d *Decoder) Decode(target any) error

Decode decodes the values that comes from Codec's sources into given target.

type EnvironmentSource

type EnvironmentSource struct {
	// contains filtered or unexported fields
}

EnvironmentSource is a Source that reads values from environment variables.

func NewEnvironmentSource

func NewEnvironmentSource(opts ...EnvironmentSourceOption) *EnvironmentSource

func (*EnvironmentSource) FillValue

func (s *EnvironmentSource) FillValue(path Path, target reflect.Value) error

type EnvironmentSourceOption

type EnvironmentSourceOption func(*environmentSourceConfig)

func WithPrefix

func WithPrefix(prefix string) EnvironmentSourceOption

WithPrefix indicates the EnvironmentSource fetches environment variables with given prefix.

func WithSliceDelimiter

func WithSliceDelimiter(delimiter string) EnvironmentSourceOption

type MapSource

type MapSource struct {
	// contains filtered or unexported fields
}

MapSource is a Source that fills values from given the map.

func NewMapSource

func NewMapSource(m map[string]any) *MapSource

func (*MapSource) FillValue

func (s *MapSource) FillValue(path Path, target reflect.Value) error

type Path

type Path []reflect.StructField

type Source

type Source interface {
	FillValue(path Path, target reflect.Value) error
}

Source is an interface that fetches the values from external sources and fills into given target.

type UnsupportedTypeError

type UnsupportedTypeError = internal.UnsupportedTypeError

UnsupportedTypeError is an error type represents target value type is not supported by Source.