gowalker

README

Golang struct walker

Walking throught golang struct to fullfil its fields from ENV variables.

Install

$ go get github.com/vkd/gowalker

Example of the config parsing

import (
	"log"
	"os"

	"github.com/vkd/gowalker"
	"github.com/vkd/gowalker/config"
)

type Config struct {
	LogLevel string        `flag:"loglevel" env:"LOGLEVEL" required:"true"`
	Timeout  time.Duration `default:"3s"`

	DB  struct {
		Port  int `default:"5432" flag:"db-port" env:"DB_PORT"`
	}
}

func ParseConfig() {
	var cfg Config
	err := config.Walk(&cfg, log.New(os.Stdout, "", 0),
		gowalker.Flags(gowalker.FieldKey("flag", gowalker.Fullname("-", strings.ToLower)), os.Args),
		gowalker.Envs(gowalker.FieldKey("env", gowalker.Fullname("_", strings.ToUpper)), os.LookupEnv),
		gowalker.Tag("default"),
		gowalker.Required("required"),
	)
	if err != nil {
		if errors.Is(err, gowalker.ErrPrintHelp) {
			return nil
		}
		...
	}
}

Documentation

Overview

Example

package main

import (
	"fmt"
	"strings"
	"time"

	"github.com/vkd/gowalker"
	"github.com/vkd/gowalker/config"
	"golang.org/x/text/cases"
	"golang.org/x/text/language"
)

type titleName string

func (c *titleName) SetString(s string) error {
	*c = titleName(cases.Title(language.Und).String(s) + "!")
	return nil
}

func main() {
	var cfg struct {
		Name    titleName
		Timeout time.Duration `default:"3s"`

		DB struct {
			Username string `required:""`
			Password string `required:""`
		}

		Metrics struct {
			Addr string `env:"METRICS_URL"`
		}
	}

	// osLookupEnv := os.LookupEnv
	osLookupEnv := func(key string) (string, bool) {
		v, ok := map[string]string{
			"MY_ORG_DB_USERNAME": "postgres",
			"MY_ORG_METRICS_URL": "localhost:5678",
		}[key]
		return v, ok
	}

	// osArgs := os.Args
	osArgs := []string{"gowalker", "--timeout=5s", "--db-password", "example", "--name=gowalker"}

	err := config.Walk(&cfg, nil,
		gowalker.Flags(gowalker.FieldKey("flag", gowalker.Fullname("-", strings.ToLower)), osArgs),
		gowalker.Envs(gowalker.Prefix("MY_ORG_", gowalker.FieldKey("env", gowalker.Fullname("_", strings.ToUpper))), osLookupEnv),
		gowalker.Tag("default"),
		gowalker.Required("required"),
	)
	fmt.Printf("%v, %v", cfg, err)
}

Output:

{Gowalker! 5s {postgres example} {localhost:5678}}, <nil>

Index

• Variables
• func IsGoWalkerField(value reflect.Value) bool
• func KeyUpdatedFields(fs Fields) string
• func Walk(value interface{}, fs Fields, w Walker, cs ...Option) error
• type DefaultTag
  • func (t DefaultTag) Doc(field reflect.StructField, fs Fields) string
  • func (t DefaultTag) Name() string
  • func (t DefaultTag) Step(value reflect.Value, field reflect.StructField, fs Fields) (bool, error)
• type Env
  • func Envs(fk FieldKeyer, osLookupEnv LookupFunc) *Env
  • func (e *Env) Doc(field reflect.StructField, fs Fields) string
  • func (e *Env) Name() string
  • func (e *Env) Step(value reflect.Value, field reflect.StructField, fs Fields) (bool, error)
• type FieldKeyer
  • func FieldKey(t Tag, namer Namer) FieldKeyer
  • func NestedFieldKey(t, fkey Tag, namer Namer) FieldKeyer
  • func Prefix(p string, fk FieldKeyer) FieldKeyer
• type FieldKeyerFunc
  • func (f FieldKeyerFunc) FieldKey(field reflect.StructField, fs Fields) string
• type Fields
  • func MakeFields(cap int) Fields
  • func (f Fields) Names() iter.Seq[string]
• type Flag
  • func Flags(fk FieldKeyer, osArgs []string) *Flag
  • func (f *Flag) Doc(field reflect.StructField, fs Fields) string
  • func (f *Flag) Init(ptr interface{}) error
  • func (*Flag) Name() string
  • func (f *Flag) Step(v reflect.Value, sf reflect.StructField, fs Fields) (ok bool, _ error)
• type GoWalkerFielder
• type LookupFunc
• type Maybe
  • func (m Maybe[T]) Get() (zero T, _ bool)
  • func (Maybe[T]) GoWalkerField()
  • func (Maybe[T]) GoWalkerMaybe()
  • func (m *Maybe[T]) Set(v T)
• type Namer
  • func Fullname(separator string, convFn func(string) string) Namer
• type NamerFunc
  • func (n NamerFunc) Key(fs iter.Seq[string]) string
• type Option
  • func StepOnStructFields() Option
• type Required
  • func (r Required) Doc(field reflect.StructField, fs Fields) string
  • func (r Required) Name() string
  • func (r Required) Step(value reflect.Value, field reflect.StructField, fs Fields) (bool, error)
• type Tag
  • func (t Tag) Doc(field reflect.StructField, fs Fields) string
  • func (t Tag) Name() string
  • func (t Tag) Names(f Fields) iter.Seq[string]
  • func (t Tag) Step(value reflect.Value, field reflect.StructField, fs Fields) (bool, error)
• type UpdatedFields
  • func FlagWalk(ptr interface{}, fs Fields, kb FieldKeyer, osArgs []string) (UpdatedFields, error)
  • func (u UpdatedFields) Has(fs Fields) bool
• type Walker
• type WalkerFunc
  • func (f WalkerFunc) Step(value reflect.Value, field reflect.StructField, fs Fields) (bool, error)
• type WalkersOR
  • func (w WalkersOR) Step(value reflect.Value, field reflect.StructField, fs Fields) (bool, error)

Examples

• Package
• Walk (CollectAllPublicFields)
• Walk (FromMapOfStrings)

Variables

var DashToLoverNamer = Fullname("-", strings.ToLower)

DashToLoverNamer - concat a lowercase parent's name with a lowercase child's one with dash.

var DefaultNamer = Fullname("", nil)

var EnvNamer = UpperNamer

EnvNamer - STRUCT_FIELD naming.

var ErrPrintHelp = fmt.Errorf("print help")

var ErrRequiredField = errors.New("field is required")

var ErrUnsupportedValue = errors.New("unsupported type for value: allowed only ptr")

ErrUnsupportedValue is raised if value is passed not as a pointer.

var FlagNamer = DashToLoverNamer

FlagNamer - struct-field naming.

var StructFieldNamer = Fullname(".", nil)

StructFieldNamer - concat a parent's name with a child's one with dot.

var UpperNamer = Fullname("_", strings.ToUpper)

UpperNamer - concat a uppercase parent's name with a uppercase child's one with underscore.

Functions

func IsGoWalkerField

func IsGoWalkerField(value reflect.Value) bool

func KeyUpdatedFields

func KeyUpdatedFields(fs Fields) string

func Walk

func Walk(value interface{}, fs Fields, w Walker, cs ...Option) error

Walk - walk struct by all public fields.

Should be passed as pointer: type myStruct struct var s myStruct gowalker.Walk(&s, ...)

Example (CollectAllPublicFields)

package main

import (
	"fmt"
	"reflect"
	"time"

	"github.com/vkd/gowalker"
)

type visitedFields []string

func (f *visitedFields) Step(value reflect.Value, field reflect.StructField, fs gowalker.Fields) (set bool, err error) {
	key := gowalker.DashToLoverNamer.Key(fs.Names())
	*f = append(*f, key)
	return false, nil
}

func main() {
	var config struct {
		Name string
		Port int
		DB   struct {
			URL  string
			Port int
		}

		StartedAt time.Time
	}

	var fs visitedFields
	err := gowalker.Walk(&config, gowalker.MakeFields(2), &fs)
	fmt.Printf("fields: %v, %v", fs, err)
}

Output:

fields: [name port db-url db-port startedat], <nil>

Example (FromMapOfStrings)

package main

import (
	"fmt"
	"reflect"

	"github.com/vkd/gowalker"
	"github.com/vkd/gowalker/setter"
)

func main() {
	var q struct {
		Name    string   `uri:"name"`
		Age     int      `uri:"age"`
		Friends []string `uri:"friends"`
		Coins   []int    `uri:"coins"`
		Keys    []int
	}

	uri := map[string][]string{
		"name":    {"mike"},
		"friends": {"igor", "alisa"},
	}

	fk := gowalker.FieldKey("uri", gowalker.DefaultNamer)
	w := gowalker.WalkerFunc(func(value reflect.Value, field reflect.StructField, fs gowalker.Fields) (stop bool, _ error) {
		key := fk.FieldKey(field, fs)
		v, ok := uri[key]
		if !ok {
			return false, nil
		}
		return true, setter.SetSliceStrings(value, field, v)
	})
	err := gowalker.Walk(&q, gowalker.MakeFields(1), w)
	fmt.Printf("%+v, %v", q, err)
}

Output:

{Name:mike Age:0 Friends:[igor alisa] Coins:[] Keys:[]}, <nil>

Types

type DefaultTag

type DefaultTag Tag

func (DefaultTag) Doc

func (t DefaultTag) Doc(field reflect.StructField, fs Fields) string

func (DefaultTag) Name

func (t DefaultTag) Name() string

func (DefaultTag) Step

func (t DefaultTag) Step(value reflect.Value, field reflect.StructField, fs Fields) (bool, error)

type Env

type Env struct {
	FieldKeyer
	LookupFunc
}

func Envs

func Envs(fk FieldKeyer, osLookupEnv LookupFunc) *Env

func (*Env) Doc

func (e *Env) Doc(field reflect.StructField, fs Fields) string

func (*Env) Name

func (e *Env) Name() string

func (*Env) Step

func (e *Env) Step(value reflect.Value, field reflect.StructField, fs Fields) (bool, error)

type FieldKeyer

type FieldKeyer interface {
	FieldKey(reflect.StructField, Fields) string
}

func FieldKey

func FieldKey(t Tag, namer Namer) FieldKeyer

func NestedFieldKey

func NestedFieldKey(t, fkey Tag, namer Namer) FieldKeyer

func Prefix

func Prefix(p string, fk FieldKeyer) FieldKeyer

type FieldKeyerFunc

type FieldKeyerFunc func(reflect.StructField, Fields) string

func (FieldKeyerFunc) FieldKey

func (f FieldKeyerFunc) FieldKey(field reflect.StructField, fs Fields) string

type Fields

type Fields []reflect.StructField

func MakeFields

func MakeFields(cap int) Fields

func (Fields) Names

func (f Fields) Names() iter.Seq[string]

type Flag

type Flag struct {
	FieldKeyer
	OsArgs []string
	// contains filtered or unexported fields
}

func Flags

func Flags(fk FieldKeyer, osArgs []string) *Flag

func (*Flag) Doc

func (f *Flag) Doc(field reflect.StructField, fs Fields) string

func (*Flag) Init

func (f *Flag) Init(ptr interface{}) error

func (*Flag) Name

func (*Flag) Name() string

func (*Flag) Step

func (f *Flag) Step(v reflect.Value, sf reflect.StructField, fs Fields) (ok bool, _ error)

type GoWalkerFielder

type GoWalkerFielder interface {
	GoWalkerField()
}

type LookupFunc

type LookupFunc func(key string) (string, bool)

type Maybe

type Maybe[T any] struct {
	IsSet bool
	Value T
}

func (Maybe[T]) Get

func (m Maybe[T]) Get() (zero T, _ bool)

func (Maybe[T]) GoWalkerField

func (Maybe[T]) GoWalkerField()

func (Maybe[T]) GoWalkerMaybe

func (Maybe[T]) GoWalkerMaybe()

func (*Maybe[T]) Set

func (m *Maybe[T]) Set(v T)

type Namer

type Namer interface {
	Key(fs iter.Seq[string]) string
}

func Fullname

func Fullname(separator string, convFn func(string) string) Namer

Fullname namer.

type NamerFunc

type NamerFunc func(fs iter.Seq[string]) string

func (NamerFunc) Key

func (n NamerFunc) Key(fs iter.Seq[string]) string

type Option

type Option interface {
	// contains filtered or unexported methods
}

func StepOnStructFields

func StepOnStructFields() Option

type Required

type Required Tag

func (Required) Doc

func (r Required) Doc(field reflect.StructField, fs Fields) string

func (Required) Name

func (r Required) Name() string

func (Required) Step

func (r Required) Step(value reflect.Value, field reflect.StructField, fs Fields) (bool, error)

type Tag

type Tag string

func (Tag) Doc

func (t Tag) Doc(field reflect.StructField, fs Fields) string

func (Tag) Name

func (t Tag) Name() string

func (Tag) Names

func (t Tag) Names(f Fields) iter.Seq[string]

func (Tag) Step

func (t Tag) Step(value reflect.Value, field reflect.StructField, fs Fields) (bool, error)

type UpdatedFields

type UpdatedFields map[string]struct{}

func FlagWalk

func FlagWalk(ptr interface{}, fs Fields, kb FieldKeyer, osArgs []string) (UpdatedFields, error)

func (UpdatedFields) Has

func (u UpdatedFields) Has(fs Fields) bool

type Walker

type Walker interface {
	Step(reflect.Value, reflect.StructField, Fields) (stop bool, _ error)
}

type WalkerFunc

type WalkerFunc func(reflect.Value, reflect.StructField, Fields) (stop bool, _ error)

func (WalkerFunc) Step

func (f WalkerFunc) Step(value reflect.Value, field reflect.StructField, fs Fields) (bool, error)

type WalkersOR

type WalkersOR []Walker

func (WalkersOR) Step

func (w WalkersOR) Step(value reflect.Value, field reflect.StructField, fs Fields) (bool, error)