conversion

package
v1.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 17, 2016 License: Apache-2.0 Imports: 4 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func ByteSliceCopy added in v1.1.3 

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

ByteSliceCopy 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.

func IsMissingKind 

func IsMissingKind(err error) bool

func IsMissingVersion 

func IsMissingVersion(err error) bool

func IsNotRegisteredError 

func IsNotRegisteredError(err error) bool

IsNotRegisteredError returns true if the error indicates the provided object or input data is not registered.

func NewMissingKindErr 

func NewMissingKindErr(data string) error

func NewMissingVersionErr 

func NewMissingVersionErr(data string) error

func NewNotRegisteredErr added in v1.1.3 

func NewNotRegisteredErr(gvk unversioned.GroupVersionKind, t reflect.Type) error

NewNotRegisteredErr is exposed for testing.

Types

type Cloner 

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

Cloner knows how to copy one type to another.

func NewCloner 

func NewCloner() *Cloner

NewCloner creates a new Cloner object.

func (*Cloner) DeepCopy 

func (c *Cloner) DeepCopy(in interface{}) (interface{}, error)

DeepCopy will perform a deep copy of a given object.

func (*Cloner) RegisterDeepCopyFunc 

func (c *Cloner) RegisterDeepCopyFunc(deepCopyFunc interface{}) error

RegisterGeneratedDeepCopyFunc registers a copying func with the Cloner. deepCopyFunc must take three parameters: a type input, a pointer to a type output, and a pointer to Cloner. It should return an error.

Example: c.RegisterGeneratedDeepCopyFunc( 

func(in Pod, out *Pod, c *Cloner) error {
        // deep copy logic...
        return nil
 })

func (*Cloner) RegisterGeneratedDeepCopyFunc 

func (c *Cloner) RegisterGeneratedDeepCopyFunc(deepCopyFunc interface{}) error

Similar to RegisterDeepCopyFunc, but registers deep copy function that were automatically generated.

type ConversionFuncs added in v1.1.3 

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

func NewConversionFuncs added in v1.1.3 

func NewConversionFuncs() ConversionFuncs

func (ConversionFuncs) Add added in v1.1.3 

func (c ConversionFuncs) Add(fns ...interface{}) error

Add adds the provided conversion functions to the lookup table - they must have the signature `func(type1, type2, Scope) error`. Functions are added in the order passed and will override previously registered pairs.

func (ConversionFuncs) Merge added in v1.1.3 

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() *Converter

NewConverter creates a new Converter object.

func (*Converter) ConversionFuncValue added in v1.1.3 

func (c *Converter) ConversionFuncValue(inType, outType reflect.Type) (reflect.Value, bool)

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) DefaultConvert 

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

DefaultConvert will translate src to dest if it knows how. Both must be pointers. No conversion func is used. If 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 DefaultConvert() other than storing it in the scope. Not safe for objects with cyclic references!

func (*Converter) HasConversionFunc 

func (c *Converter) HasConversionFunc(inType, outType reflect.Type) bool

func (*Converter) IsConversionIgnored added in v1.1.3 

func (c *Converter) IsConversionIgnored(inType, outType reflect.Type) bool

IsConversionIgnored returns true if the specified objects should be dropped during conversion.

func (*Converter) RegisterConversionFunc 

func (c *Converter) RegisterConversionFunc(conversionFunc interface{}) error

RegisterConversionFunc registers a conversion func with the Converter. conversionFunc must take three parameters: a pointer to the input type, a pointer to the output type, and a conversion.Scope (which should be used if recursive conversion calls are desired). It must return an error.

Example: c.RegisterConversionFunc( 

func(in *Pod, out *v1.Pod, s Scope) error {
        // conversion logic...
        return nil
 })

func (*Converter) RegisterDefaultingFunc 

func (c *Converter) RegisterDefaultingFunc(defaultingFunc interface{}) error

RegisterDefaultingFunc registers a value-defaulting func with the Converter. defaultingFunc must take one parameters: a pointer to the input type.

Example: c.RegisteDefaultingFunc( 

func(in *v1.Pod) {
        // defaulting logic...
 })

func (*Converter) RegisterGeneratedConversionFunc 

func (c *Converter) RegisterGeneratedConversionFunc(conversionFunc interface{}) error

Similar to RegisterConversionFunc, but registers conversion function that were automatically generated.

func (*Converter) RegisterIgnoredConversion added in v1.1.3 

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) SetStructFieldCopy 

func (c *Converter) SetStructFieldCopy(srcFieldType interface{}, srcFieldName string, destFieldType interface{}, destFieldName string) error

SetStructFieldCopy registers a correspondence. Whenever a struct field is encountered which has a type and name matching srcFieldType and srcFieldName, it wil be copied into the field in the destination struct matching destFieldType & Name, if such a field exists. May be called multiple times, even for the same source field & type--all applicable copies will be performed.

func (*Converter) WithConversions added in v1.1.3 

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 errrors

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 {
	SrcVersion  string
	DestVersion string

	// KeyNameMapping is an optional function which may map the listed key (field name)
	// into a source and destination value.
	KeyNameMapping FieldMappingFunc
}

Meta is supplied by Scheme, when it calls Convert.

type Scheme 

type Scheme struct {

	// Indent will cause the JSON output from Encode to be indented,
	// if and only if it is true.
	Indent bool
	// contains filtered or unexported fields
}

Scheme defines an entire encoding and decoding scheme.

func NewScheme 

func NewScheme() *Scheme

NewScheme manufactures a new scheme.

func (*Scheme) AddConversionFuncs 

func (s *Scheme) AddConversionFuncs(conversionFuncs ...interface{}) error

AddConversionFuncs adds functions to the list of conversion functions. The given functions should know how to convert between two of your API objects, or their sub-objects. We deduce how to call these functions from the types of their two parameters; see the comment for Converter.Register.

Note that, if you need to copy sub-objects that didn't change, you can use the conversion.Scope object that will be passed to your conversion function. Additionally, all conversions started by Scheme will set the SrcVersion and DestVersion fields on the Meta object. Example:

s.AddConversionFuncs( 

func(in *InternalObject, out *ExternalObject, scope conversion.Scope) error {
	// You can depend on Meta() being non-nil, and this being set to
	// the source version, e.g., ""
	s.Meta().SrcVersion
	// You can depend on this being set to the destination version,
	// e.g., "v1".
	s.Meta().DestVersion
	// Call scope.Convert to copy sub-fields.
	s.Convert(&in.SubFieldThatMoved, &out.NewLocation.NewName, 0)
	return nil
},

)

(For more detail about conversion functions, see Converter.Register's comment.)

Also note that the default behavior, if you don't add a conversion function, is to sanely copy fields that have the same names and same type names. It's OK if the destination type has extra fields, but it must not remove any. So you only need to add conversion functions for things with changed/removed fields.

func (*Scheme) AddDeepCopyFuncs 

func (s *Scheme) AddDeepCopyFuncs(deepCopyFuncs ...interface{}) error

AddDeepCopyFuncs adds functions to the list of deep copy functions. Note that to copy sub-objects, you can use the conversion.Cloner object that will be passed to your deep-copy function.

func (*Scheme) AddDefaultingFuncs 

func (s *Scheme) AddDefaultingFuncs(defaultingFuncs ...interface{}) error

AddDefaultingFuncs adds functions to the list of default-value functions. Each of the given functions is responsible for applying default values when converting an instance of a versioned API object into an internal API object. These functions do not need to handle sub-objects. We deduce how to call these functions from the types of their two parameters.

s.AddDefaultingFuncs( 

func(obj *v1.Pod) {
	if obj.OptionalField == "" {
		obj.OptionalField = "DefaultValue"
	}
},

)

func (*Scheme) AddGeneratedConversionFuncs 

func (s *Scheme) AddGeneratedConversionFuncs(conversionFuncs ...interface{}) error

Similar to AddConversionFuncs, but registers conversion functions that were automatically generated.

func (*Scheme) AddGeneratedDeepCopyFuncs 

func (s *Scheme) AddGeneratedDeepCopyFuncs(deepCopyFuncs ...interface{}) error

Similar to AddDeepCopyFuncs, but registers deep copy functions that were automatically generated.

func (*Scheme) AddIgnoredConversionType added in v1.1.3 

func (s *Scheme) AddIgnoredConversionType(from, to interface{}) error

AddIgnoredConversionType identifies a pair of types that should be skipped by dynamic conversion (because the data inside them is explicitly dropped during conversion).

func (*Scheme) AddKnownTypeWithName 

func (s *Scheme) AddKnownTypeWithName(gvk unversioned.GroupVersionKind, obj interface{})

AddKnownTypeWithName is like AddKnownTypes, but it lets you specify what this type should be encoded as. Useful for testing when you don't want to make multiple packages to define your structs.

func (*Scheme) AddKnownTypes 

func (s *Scheme) AddKnownTypes(gv unversioned.GroupVersion, types ...interface{})

AddKnownTypes registers all types passed in 'types' as being members of version 'version'. All objects passed to types should be pointers to structs. The name that go reports for the struct becomes the "kind" field when encoding.

func (*Scheme) AddStructFieldConversion 

func (s *Scheme) AddStructFieldConversion(srcFieldType interface{}, srcFieldName string, destFieldType interface{}, destFieldName string) error

AddStructFieldConversion allows you to specify a mechanical copy for a moved or renamed struct field without writing an entire conversion function. See the comment in Converter.SetStructFieldCopy for parameter details. Call as many times as needed, even on the same fields.

func (*Scheme) AddUnversionedTypes added in v1.1.3 

func (s *Scheme) AddUnversionedTypes(version unversioned.GroupVersion, types ...interface{})

AddUnversionedTypes registers all types passed in 'types' as being members of version 'version', and marks them as being convertible to all API versions. All objects passed to types should be pointers to structs. The name that go reports for the struct becomes the "kind" field when encoding.

func (*Scheme) Convert 

func (s *Scheme) Convert(in, out interface{}) error

Convert will attempt to convert in into out. Both must be pointers. For easy testing of conversion functions. Returns an error if the conversion isn't possible. You can call this with types that haven't been registered (for example, a to test conversion of types that are nested within registered types), but in that case, the conversion.Scope object passed to your conversion functions won't have SrcVersion or DestVersion fields set correctly in Meta().

func (*Scheme) ConvertToVersion 

func (s *Scheme) ConvertToVersion(in interface{}, outGroupVersionString string) (interface{}, error)

ConvertToVersion attempts to convert an input object to its matching Kind in another version within this scheme. Will return an error if the provided version does not contain the inKind (or a mapping by name defined with AddKnownTypeWithName).

func (*Scheme) Converter 

func (s *Scheme) Converter() *Converter

Converter allows access to the converter for the scheme

func (*Scheme) DeepCopy 

func (s *Scheme) DeepCopy(in interface{}) (interface{}, error)

Performs a deep copy of the given object.

func (*Scheme) IsUnversioned added in v1.1.3 

func (s *Scheme) IsUnversioned(obj interface{}) (unversioned bool, registered bool)

IsUnversioned returns true if the Go object is registered as an unversioned type, or sets ok to false if the provided object is not registered in the scheme.

func (*Scheme) KnownTypes 

func (s *Scheme) KnownTypes(gv unversioned.GroupVersion) map[string]reflect.Type

KnownTypes returns an array of the types that are known for a particular version.

func (*Scheme) Log 

func (s *Scheme) Log(l DebugLogger)

Log sets a logger on the scheme. For test purposes only

func (*Scheme) NewObject 

func (s *Scheme) NewObject(kind unversioned.GroupVersionKind) (interface{}, error)

NewObject returns a new object of the given version and name, or an error if it hasn't been registered.

func (*Scheme) ObjectKind added in v1.1.2 

func (s *Scheme) ObjectKind(obj interface{}) (unversioned.GroupVersionKind, error)

ObjectKind returns the group,version,kind of the go object, or an error if it's not a pointer or is unregistered.

func (*Scheme) ObjectKinds added in v1.1.2 

func (s *Scheme) ObjectKinds(obj interface{}) ([]unversioned.GroupVersionKind, error)

ObjectKinds returns all possible group,version,kind of the go object, or an error if it's not a pointer or is unregistered.

func (*Scheme) Recognizes 

func (s *Scheme) Recognizes(gvk unversioned.GroupVersionKind) bool

Recognizes returns true if the scheme is able to handle the provided group,version,kind of an object.

func (*Scheme) RegisterInputDefaults 

func (s *Scheme) RegisterInputDefaults(in interface{}, fn FieldMappingFunc, defaultFlags FieldMatchingFlags) error

RegisterInputDefaults sets the provided field mapping function and field matching as the defaults for the provided input type. The fn may be nil, in which case no mapping will happen by default. Use this method to register a mechanism for handling a specific input type in conversion, such as a map[string]string to structs.

func (*Scheme) WithConversions added in v1.1.3 

func (s *Scheme) WithConversions(fns ConversionFuncs) *Scheme

WithConversions returns a scheme with additional conversion functions

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

	// DefaultConvert performs the default conversion, without calling a conversion func
	// on the current stack frame. This makes it safe to call from a conversion func.
	DefaultConvert(src, dest interface{}, flags FieldMatchingFlags) error

	// If registered, returns a function applying defaults for objects of a given type.
	// Used for automatically generating conversion functions.
	DefaultingInterface(inType reflect.Type) (interface{}, bool)

	// 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.

Source Files

View all Source files

Directories

Path Synopsis
Package queryparams provides conversion from versioned runtime objects to URL query values
 Package queryparams provides conversion from versioned runtime objects to URL query values

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.