stronf

README

github.com/kevinfalting/structconf/stronf

See https://pkg.go.dev/github.com/kevinfalting/structconf/stronf for package documentation.

Documentation

Overview

Package stronf exposes the core of the structconf module to support writing custom configuration handlers.

The core ideas revolve around the Field, HandleFunc, and how values are Coerce'd into the Field.

The core properties of a Field are:

• Not mutable from outside of the stronf package.
• Expose only enough information to make programmatic decisions about what values to return.
• Expose reflect package members only when necessary, and to avoid an unecessary abstraction layer.

The core properties of a settable field in SettableFields are:

• Is settable from the reflect package's perspective.
• Satisfies either encoding.TextUnmarshaler or encoding.BinaryUnmarshaler interfaces, checked for in that order.
• Is a value type.

When testing, there is no interface for the Field, so a test struct must be defined and a call to SettableFields is required to get a slice of Field to work with. There are good examples of this in the confhandler package tests.

Index

• func Coerce(field Field, val any) (any, error)
• type Field
  • func SettableFields(v any) ([]Field, error)
  • func (f Field) IsZero() bool
  • func (f Field) Kind() reflect.Kind
  • func (f Field) LookupTag(key, tag string) (string, bool)
  • func (f Field) Name() string
  • func (f Field) Parse(ctx context.Context, handler HandleFunc) error
  • func (f Field) Type() reflect.Type
  • func (f Field) Value() any
• type HandleFunc
  • func CombineHandlers(handlers ...HandleFunc) HandleFunc

Examples

• Field.LookupTag

Functions

func Coerce

func Coerce(field Field, val any) (any, error)

Coerce will attempt to convert the provided value into the field's type.

Types

type Field

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

Field represents a single settable struct field in the parsed struct.

func SettableFields

func SettableFields(v any) ([]Field, error)

SettableFields returns a slice of all settable struct fields in the provided struct. The provided argument must be a pointer to a struct.

func (Field) IsZero

func (f Field) IsZero() bool

IsZero checks if the struct field's value is it's zero type.

func (Field) Kind

func (f Field) Kind() reflect.Kind

Kind returns the field's reflect.Kind.

func (Field) LookupTag

func (f Field) LookupTag(key, tag string) (string, bool)

LookupTag will return the value associated with the key and optional tag. See examples for supported formats. The bool reports if the key or tag was explicitly found in the struct tag.

Example

package main

import (
	"fmt"
	"log"

	"github.com/kevinfalting/structconf/stronf"
)

func main() {
	type Config struct {
		DatabaseURL string `conf:"env:DATABASE_URL,required,key:val" custom:"flag:db-url" emptyKey:""`
	}

	var config Config
	fields, err := stronf.SettableFields(&config)
	if err != nil {
		log.Println(err)
		return
	}

	if len(fields) != 1 {
		log.Println("expected 1 field")
		return
	}

	field := fields[0]
	if _, ok := field.LookupTag("no-exist", "hello"); ok {
		log.Println("should not recieve a value for a key that doesn't exist")
	}

	if val, ok := field.LookupTag("emptyKey", ""); ok {
		fmt.Printf("val: %q\n", val)
	}

	if val, ok := field.LookupTag("custom", "flag"); ok {
		fmt.Printf("val: %q\n", val)
	}

	if val, ok := field.LookupTag("conf", "env"); ok {
		fmt.Printf("val: %q\n", val)
	}

	if val, ok := field.LookupTag("conf", "required"); ok {
		fmt.Printf("val: %q\n", val)
	}
}

Output:

val: ""
val: "db-url"
val: "DATABASE_URL"
val: ""

func (Field) Name

func (f Field) Name() string

Name returns the name of the struct field.

func (Field) Parse

func (f Field) Parse(ctx context.Context, handler HandleFunc) error

Parse will call the handler against the field and set the field to the returned handler value. If the handler returns nil, no change is made to the field.

func (Field) Type

func (f Field) Type() reflect.Type

Type returns the field's reflect.Type.

func (Field) Value

func (f Field) Value() any

Value returns the value of the struct field.

type HandleFunc

type HandleFunc func(ctx context.Context, field Field, proposedValue any) (any, error)

HandleFunc is the function signature for working on a Field.

func CombineHandlers

func CombineHandlers(handlers ...HandleFunc) HandleFunc

CombineHandlers will return a handler that calls each handler in the order they are provided. The last handler takes precedence over the one before it.