instruct

README

InStruct - Library for creating input-to-struct conversions

This is meant to be wrapped in another library, not to be used directly. See some of the library users for examples.

Used by

• InReq: https://github.com/rrgmc/inreq

Licenses

• uses modified MIT code from https://github.com/nofeaturesonlybugs/coerce

Author

Rangel Reale (rangelreale@gmail.com)

Documentation

Overview

Package instruct is a library for creating input-to-struct conversions

Index

• Constants
• Variables
• func DefaultFieldNameMapper(operation string, name string) string
• type DecodeContext
• type DecodeOperation
• type DecodeOperationFunc
  • func (f DecodeOperationFunc[IT, DC]) Decode(ctx DC, input IT, field reflect.Value, typ reflect.Type, tag *Tag) (bool, any, error)
• type DecodeOperationValidate
• type DecodeOptions
  • func NewDecodeOptions[IT any, DC DecodeContext]() DecodeOptions[IT, DC]
• type Decoder
  • func NewDecoder[IT any, DC DecodeContext](options DefaultOptions[IT, DC]) *Decoder[IT, DC]
  • func (d *Decoder[IT, DC]) Decode(input IT, data any, decodeOptions DecodeOptions[IT, DC]) error
• type DefaultDecodeContext
  • func NewDefaultDecodeContext(fnMapper FieldNameMapper) DefaultDecodeContext
  • func (d *DefaultDecodeContext) FieldNameMapper() FieldNameMapper
  • func (d *DefaultDecodeContext) GetUsedValues(operation string) map[string]bool
  • func (d *DefaultDecodeContext) ValueUsed(operation string, name string)
• type DefaultOptions
  • func NewDefaultOptions[IT any, DC DecodeContext]() DefaultOptions[IT, DC]
  • func (o *DefaultOptions[IT, DC]) DefaultMapTagsSet(t reflect.Type, m MapTags)
  • func (o *DefaultOptions[IT, DC]) StructInfoCache(cache bool)
• type FieldNameMapper
• type MapTags
• type Resolver
• type StructOption
• type Tag
• type TagOptions
  • func NewTagOptions() TagOptions
  • func (t *TagOptions) BoolValue(name string, defaultValue bool) (bool, error)
  • func (t *TagOptions) Exists(name string) bool
  • func (t *TagOptions) Get(name string) (string, bool)
  • func (t *TagOptions) Value(name string, defaultValue string) string
• type TypeDecoder
  • func NewTypeDecoder[IT any, DC DecodeContext, T any](options TypeDefaultOptions[IT, DC]) *TypeDecoder[IT, DC, T]
  • func (d *TypeDecoder[IT, DC, T]) Decode(input IT, decodeOptions DecodeOptions[IT, DC]) (T, error)
• type TypeDefaultOptions
  • func NewTypeDefaultOptions[IT any, DC DecodeContext]() TypeDefaultOptions[IT, DC]

Constants

const (
	OperationIgnore  string = "-"
	OperationRecurse        = "recurse"
)

Default operations.

const (
	SOOptionWhenBefore  = "before"
	SOOptionWhenAfter   = "after"
	SOOptionWhenDefault = SOOptionWhenAfter
)

StructOption "when" values.

const StructOptionMapTag = "_"

StructOptionMapTag corresponds to StructOption in a MapTags.

Variables

var IgnoreDecodeValue = struct{}{}

IgnoreDecodeValue can be returned from [DecodeOperation.Decode] to signal that the value should not be set on the struct field. This is used for example in HTTP "body" decoders.

Functions

func DefaultFieldNameMapper

func DefaultFieldNameMapper(operation string, name string) string

DefaultFieldNameMapper converts names to lowercase using strings.ToLower.

Types

type DecodeContext

type DecodeContext interface {
	// ValueUsed signals that the value was used.
	ValueUsed(operation string, name string)
	// GetUsedValues returns the list of used values for the operation.
	GetUsedValues(operation string) map[string]bool
	// FieldNameMapper returns the FieldNameMapper instance to be used for converting the struct field name.
	FieldNameMapper() FieldNameMapper
}

DecodeContext is the context sent to DecodeOperation.

type DecodeOperation

type DecodeOperation[IT any, DC DecodeContext] interface {
	// Decode decodes a value for a field. If you have a value easily available, return it in "value" and
	// ignore the "field" parameter (don't try any kind of conversion). Otherwise, set the "field" value
	// directly and return IgnoreDecodeValue in "value", for example, when decoding a JSON HTTP body
	// into a struct field.
	// If isList is true, try to return an array/slice if available.
	Decode(ctx DC, input IT, isList bool, field reflect.Value, tag *Tag) (found bool, value any, err error)
}

DecodeOperation is the interface for the input-to-struct decoders.

type DecodeOperationFunc

type DecodeOperationFunc[IT any, DC DecodeContext] func(ctx DC, input IT, field reflect.Value, typ reflect.Type, tag *Tag) (bool, any, error)

DecodeOperationFunc wraps a DecodeOperation as a function.

func (DecodeOperationFunc[IT, DC]) Decode

func (f DecodeOperationFunc[IT, DC]) Decode(ctx DC, input IT, field reflect.Value, typ reflect.Type, tag *Tag) (bool, any, error)

type DecodeOperationValidate

type DecodeOperationValidate[IT any, DC DecodeContext] interface {
	Validate(ctx DC, input IT) error
}

DecodeOperationValidate allows a DecodeOperation to do a final validation.

type DecodeOptions

type DecodeOptions[IT any, DC DecodeContext] struct {
	Ctx                       DC      // decode context to be sent to DecodeOperation.
	MapTags                   MapTags // decode call-specific MapTags. They may override existing ones.
	UseDecodeMapTagsAsDefault bool    // internal flag to allow Decode functions without an instance to set MapTags as a default one.
}

func NewDecodeOptions

func NewDecodeOptions[IT any, DC DecodeContext]() DecodeOptions[IT, DC]

NewDecodeOptions returns a DecodeOptions with the default values.

type Decoder

type Decoder[IT any, DC DecodeContext] struct {
	// contains filtered or unexported fields
}

Decoder decodes inputs to structs.

func NewDecoder

func NewDecoder[IT any, DC DecodeContext](options DefaultOptions[IT, DC]) *Decoder[IT, DC]

NewDecoder creates a Decoder instance without any decode operations. At least one must be added for decoding to work.

func (*Decoder[IT, DC]) Decode

func (d *Decoder[IT, DC]) Decode(input IT, data any, decodeOptions DecodeOptions[IT, DC]) error

Decode decodes the input to the struct passed in "data".

type DefaultDecodeContext

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

DefaultDecodeContext implements the standard decode context.

func NewDefaultDecodeContext

func NewDefaultDecodeContext(fnMapper FieldNameMapper) DefaultDecodeContext

NewDefaultDecodeContext creates an instance of DefaultDecodeContext.

func (*DefaultDecodeContext) FieldNameMapper

func (d *DefaultDecodeContext) FieldNameMapper() FieldNameMapper

func (*DefaultDecodeContext) GetUsedValues

func (d *DefaultDecodeContext) GetUsedValues(operation string) map[string]bool

func (*DefaultDecodeContext) ValueUsed

func (d *DefaultDecodeContext) ValueUsed(operation string, name string)

type DefaultOptions

type DefaultOptions[IT any, DC DecodeContext] struct {
	TagName          string                             // struct tag name. Default "inreq".
	DefaultRequired  bool                               // whether the default for fields should be "required" or "not required"
	DecodeOperations map[string]DecodeOperation[IT, DC] // list of decode operations

	FieldNameMapper FieldNameMapper // field name mapper. Default one uses [strings.ToLower].

	Resolver Resolver // interface used to convert strings to the struct field type.
	// contains filtered or unexported fields
}

func NewDefaultOptions

func NewDefaultOptions[IT any, DC DecodeContext]() DefaultOptions[IT, DC]

NewDefaultOptions returns a DefaultOptions with the default values.

func (*DefaultOptions[IT, DC]) DefaultMapTagsSet

func (o *DefaultOptions[IT, DC]) DefaultMapTagsSet(t reflect.Type, m MapTags)

func (*DefaultOptions[IT, DC]) StructInfoCache

func (o *DefaultOptions[IT, DC]) StructInfoCache(cache bool)

type FieldNameMapper

type FieldNameMapper func(operation string, name string) string

FieldNameMapper maps a struct field name to the target field name. The default one uses strings.ToLower.

type MapTags

type MapTags map[string]any

MapTags is an alternative to struct tags, and can be used to override them.

type Resolver

type Resolver interface {
	Resolve(target reflect.Value, value any) error
}

Resolver converts values to the type of the struct field.

type StructOption

type StructOption struct{}

StructOption can be used as a struct field to give options to the struct itself.

type Tag

type Tag struct {
	Operation string     // decode operation
	Name      string     // data name (for example, header or query param name)
	Required  bool       // whether this field is required to be set
	Options   TagOptions // options
	IsSO      bool
	SOWhen    string // struct options: when to parse (before or after the fields)
	SORecurse bool   // struct options: whether to recurse into inner struct
}

Tag contains the options parsed from the struct tags or MapTags

type TagOptions

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

func NewTagOptions

func NewTagOptions() TagOptions

func (*TagOptions) BoolValue

func (t *TagOptions) BoolValue(name string, defaultValue bool) (bool, error)

func (*TagOptions) Exists

func (t *TagOptions) Exists(name string) bool

func (*TagOptions) Get

func (t *TagOptions) Get(name string) (string, bool)

func (*TagOptions) Value

func (t *TagOptions) Value(name string, defaultValue string) string

type TypeDecoder

type TypeDecoder[IT any, DC DecodeContext, T any] struct {
	// contains filtered or unexported fields
}

TypeDecoder decodes inputs to structs for a specific type.

func NewTypeDecoder

func NewTypeDecoder[IT any, DC DecodeContext, T any](options TypeDefaultOptions[IT, DC]) *TypeDecoder[IT, DC, T]

NewTypeDecoder creates a TypeDecoder instance for a specific type without any decode operations. At least one must be added for decoding to work.

func (*TypeDecoder[IT, DC, T]) Decode

func (d *TypeDecoder[IT, DC, T]) Decode(input IT, decodeOptions DecodeOptions[IT, DC]) (T, error)

Decode decodes the input to the generic type.

type TypeDefaultOptions

type TypeDefaultOptions[IT any, DC DecodeContext] struct {
	DefaultOptions[IT, DC]
	MapTags MapTags // type-specific MapTags. They may override existing ones.
}

func NewTypeDefaultOptions

func NewTypeDefaultOptions[IT any, DC DecodeContext]() TypeDefaultOptions[IT, DC]

NewTypeDefaultOptions returns a TypeDefaultOptions with the default values.