conversion

Documentation

Overview

Package conversion provides go object versioning.

Specifically, conversion provides a way for you to define multiple versions of the same object. You may write functions which implement conversion logic, but for the fields which did not change, copying is automated. This makes it easy to modify the structures you use in memory without affecting the format you store on disk or respond to in your external API calls.

Index

• Variables
• func Convert_Slice_byte_To_Slice_byte(in *[]byte, out *[]byte, s Scope) error
• func EnforcePtr(obj interface{}) (reflect.Value, error)
• type ConversionFunc
• type ConversionFuncs
  • func NewConversionFuncs() ConversionFuncs
  • func (c ConversionFuncs) AddUntyped(a, b interface{}, fn ConversionFunc) error
  • func (c ConversionFuncs) Merge(other ConversionFuncs) ConversionFuncs
• type Converter
  • func NewConverter(nameFn NameFunc) *Converter
  • func (c *Converter) Convert(src, dest interface{}, flags FieldMatchingFlags, meta *Meta) error
  • func (c *Converter) DefaultMeta(t reflect.Type) (FieldMatchingFlags, *Meta)
  • func (c *Converter) RegisterGeneratedUntypedConversionFunc(a, b interface{}, fn ConversionFunc) error
  • func (c *Converter) RegisterIgnoredConversion(from, to interface{}) error
  • func (c *Converter) RegisterInputDefaults(in interface{}, fn FieldMappingFunc, defaultFlags FieldMatchingFlags) error
  • func (c *Converter) RegisterUntypedConversionFunc(a, b interface{}, fn ConversionFunc) error
  • func (c *Converter) WithConversions(fns ConversionFuncs) *Converter
• type DebugLogger
• type Equalities
  • func EqualitiesOrDie(funcs ...interface{}) Equalities
• type FieldMappingFunc
• type FieldMatchingFlags
  • func (f FieldMatchingFlags) IsSet(flag FieldMatchingFlags) bool
• type Meta
• type NameFunc
• type Scope

Variables

var DefaultNameFunc = func(t reflect.Type) string { return t.Name() }

Functions

func Convert_Slice_byte_To_Slice_byte

func Convert_Slice_byte_To_Slice_byte(in *[]byte, out *[]byte, s Scope) error

Convert_Slice_byte_To_Slice_byte prevents recursing into every byte

func EnforcePtr

func EnforcePtr(obj interface{}) (reflect.Value, error)

EnforcePtr ensures that obj is a pointer of some sort. Returns a reflect.Value of the dereferenced pointer, ensuring that it is settable/addressable. Returns an error if this is not possible.

Types

type ConversionFunc

type ConversionFunc func(a, b interface{}, scope Scope) error

ConversionFunc converts the object a into the object b, reusing arrays or objects or pointers if necessary. It should return an error if the object cannot be converted or if some data is invalid. If you do not wish a and b to share fields or nested objects, you must copy a before calling this function.

type ConversionFuncs

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

func NewConversionFuncs

func NewConversionFuncs() ConversionFuncs

func (ConversionFuncs) AddUntyped

func (c ConversionFuncs) AddUntyped(a, b interface{}, fn ConversionFunc) error

AddUntyped adds the provided conversion function to the lookup table for the types that are supplied as a and b. a and b must be pointers or an error is returned. This method overwrites previously defined functions.

func (ConversionFuncs) Merge

func (c ConversionFuncs) Merge(other ConversionFuncs) ConversionFuncs

Merge returns a new ConversionFuncs that contains all conversions from both other and c, with other conversions taking precedence.

type Converter

type Converter struct {

	// If non-nil, will be called to print helpful debugging info. Quite verbose.
	Debug DebugLogger
	// contains filtered or unexported fields
}

Converter knows how to convert one type to another.

func NewConverter

func NewConverter(nameFn NameFunc) *Converter

NewConverter creates a new Converter object.

func (*Converter) Convert

func (c *Converter) Convert(src, dest interface{}, flags FieldMatchingFlags, meta *Meta) error

Convert will translate src to dest if it knows how. Both must be pointers. If no conversion func is registered and the default copying mechanism doesn't work on this type pair, an error will be returned. Read the comments on the various FieldMatchingFlags constants to understand what the 'flags' parameter does. 'meta' is given to allow you to pass information to conversion functions, it is not used by Convert() other than storing it in the scope. Not safe for objects with cyclic references!

func (*Converter) DefaultMeta

func (c *Converter) DefaultMeta(t reflect.Type) (FieldMatchingFlags, *Meta)

DefaultMeta returns the conversion FieldMappingFunc and meta for a given type.

func (*Converter) RegisterGeneratedUntypedConversionFunc

func (c *Converter) RegisterGeneratedUntypedConversionFunc(a, b interface{}, fn ConversionFunc) error

RegisterGeneratedUntypedConversionFunc registers a function that converts between a and b by passing objects of those types to the provided function. The function *must* accept objects of a and b - this machinery will not enforce any other guarantee.

func (*Converter) RegisterIgnoredConversion

func (c *Converter) RegisterIgnoredConversion(from, to interface{}) error

RegisterIgnoredConversion registers a "no-op" for conversion, where any requested conversion between from and to is ignored.

func (*Converter) RegisterInputDefaults

func (c *Converter) RegisterInputDefaults(in interface{}, fn FieldMappingFunc, defaultFlags FieldMatchingFlags) error

RegisterInputDefaults registers a field name mapping function, used when converting from maps to structs. Inputs to the conversion methods are checked for this type and a mapping applied automatically if the input matches in. A set of default flags for the input conversion may also be provided, which will be used when no explicit flags are requested.

func (*Converter) RegisterUntypedConversionFunc

func (c *Converter) RegisterUntypedConversionFunc(a, b interface{}, fn ConversionFunc) error

RegisterUntypedConversionFunc registers a function that converts between a and b by passing objects of those types to the provided function. The function *must* accept objects of a and b - this machinery will not enforce any other guarantee.

func (*Converter) WithConversions

func (c *Converter) WithConversions(fns ConversionFuncs) *Converter

WithConversions returns a Converter that is a copy of c but with the additional fns merged on top.

type DebugLogger

type DebugLogger interface {
	Logf(format string, args ...interface{})
}

DebugLogger allows you to get debugging messages if necessary.

type Equalities

type Equalities struct {
	reflect.Equalities
}

The code for this type must be located in third_party, since it forks from go std lib. But for convenience, we expose the type here, too.

func EqualitiesOrDie

func EqualitiesOrDie(funcs ...interface{}) Equalities

For convenience, panics on errors

type FieldMappingFunc

type FieldMappingFunc func(key string, sourceTag, destTag reflect.StructTag) (source string, dest string)

FieldMappingFunc can convert an input field value into different values, depending on the value of the source or destination struct tags.

type FieldMatchingFlags

type FieldMatchingFlags int

FieldMatchingFlags contains a list of ways in which struct fields could be copied. These constants may be | combined.

const (
	// Loop through destination fields, search for matching source
	// field to copy it from. Source fields with no corresponding
	// destination field will be ignored. If SourceToDest is
	// specified, this flag is ignored. If neither is specified,
	// or no flags are passed, this flag is the default.
	DestFromSource FieldMatchingFlags = 0
	// Loop through source fields, search for matching dest field
	// to copy it into. Destination fields with no corresponding
	// source field will be ignored.
	SourceToDest FieldMatchingFlags = 1 << iota
	// Don't treat it as an error if the corresponding source or
	// dest field can't be found.
	IgnoreMissingFields
	// Don't require type names to match.
	AllowDifferentFieldTypeNames
)

func (FieldMatchingFlags) IsSet

func (f FieldMatchingFlags) IsSet(flag FieldMatchingFlags) bool

IsSet returns true if the given flag or combination of flags is set.

type Meta

type Meta struct {
	// KeyNameMapping is an optional function which may map the listed key (field name)
	// into a source and destination value.
	KeyNameMapping FieldMappingFunc
	// Context is an optional field that callers may use to pass info to conversion functions.
	Context interface{}
}

Meta is supplied by Scheme, when it calls Convert.

type NameFunc

type NameFunc func(t reflect.Type) string

type Scope

type Scope interface {
	// Call Convert to convert sub-objects. Note that if you call it with your own exact
	// parameters, you'll run out of stack space before anything useful happens.
	Convert(src, dest interface{}, flags FieldMatchingFlags) error

	// SrcTags and DestTags contain the struct tags that src and dest had, respectively.
	// If the enclosing object was not a struct, then these will contain no tags, of course.
	SrcTag() reflect.StructTag
	DestTag() reflect.StructTag

	// Flags returns the flags with which the conversion was started.
	Flags() FieldMatchingFlags

	// Meta returns any information originally passed to Convert.
	Meta() *Meta
}

Scope is passed to conversion funcs to allow them to continue an ongoing conversion. If multiple converters exist in the system, Scope will allow you to use the correct one from a conversion function--that is, the one your conversion function was called by.