README

reflectx

The sqlx package has special reflect needs. In particular, it needs to:

  • be able to map a name to a field
  • understand embedded structs
  • understand mapping names to fields by a particular tag
  • user specified name -> field mapping functions

These behaviors mimic the behaviors by the standard library marshallers and also the behavior of standard Go accessors.

The first two are amply taken care of by Reflect.Value.FieldByName, and the third is addressed by Reflect.Value.FieldByNameFunc, but these don't quite understand struct tags in the ways that are vital to most marshallers, and they are slow.

This reflectx package extends reflect to achieve these goals.

Expand ▾ Collapse ▴

Documentation

Overview

    Package reflectx implements extensions to the standard reflect lib suitable for implementing marshalling and unmarshalling packages. The main Mapper type allows for Go-compatible named attribute access, including accessing embedded struct attributes and the ability to use functions and struct tags to customize field names.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func Deref

    func Deref(t reflect.Type) reflect.Type

      Deref is Indirect for reflect.Types

      func FieldByIndexes

      func FieldByIndexes(v reflect.Value, indexes []int) reflect.Value

        FieldByIndexes returns a value for the field given by the struct traversal for the given value.

        func FieldByIndexesReadOnly

        func FieldByIndexesReadOnly(v reflect.Value, indexes []int) reflect.Value

          FieldByIndexesReadOnly returns a value for a particular struct traversal, but is not concerned with allocating nil pointers because the value is going to be used for reading and not setting.

          Types

          type FieldInfo

          type FieldInfo struct {
          	Index    []int
          	Path     string
          	Field    reflect.StructField
          	Zero     reflect.Value
          	Name     string
          	Options  map[string]string
          	Embedded bool
          	Children []*FieldInfo
          	Parent   *FieldInfo
          }

            A FieldInfo is metadata for a struct field.

            type Mapper

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

              Mapper is a general purpose mapper of names to struct fields. A Mapper behaves like most marshallers in the standard library, obeying a field tag for name mapping but also providing a basic transform function.

              func NewMapper

              func NewMapper(tagName string) *Mapper

                NewMapper returns a new mapper using the tagName as its struct field tag. If tagName is the empty string, it is ignored.

                func NewMapperFunc

                func NewMapperFunc(tagName string, f func(string) string) *Mapper

                  NewMapperFunc returns a new mapper which optionally obeys a field tag and a struct field name mapper func given by f. Tags will take precedence, but for any other field, the mapped name will be f(field.Name)

                  func NewMapperTagFunc

                  func NewMapperTagFunc(tagName string, mapFunc, tagMapFunc func(string) string) *Mapper

                    NewMapperTagFunc returns a new mapper which contains a mapper for field names AND a mapper for tag values. This is useful for tags like json which can have values like "name,omitempty".

                    func (*Mapper) FieldByName

                    func (m *Mapper) FieldByName(v reflect.Value, name string) reflect.Value

                      FieldByName returns a field by its mapped name as a reflect.Value. Panics if v's Kind is not Struct or v is not Indirectable to a struct Kind. Returns zero Value if the name is not found.

                      func (*Mapper) FieldMap

                      func (m *Mapper) FieldMap(v reflect.Value) map[string]reflect.Value

                        FieldMap returns the mapper's mapping of field names to reflect values. Panics if v's Kind is not Struct, or v is not Indirectable to a struct kind.

                        func (*Mapper) FieldsByName

                        func (m *Mapper) FieldsByName(v reflect.Value, names []string) []reflect.Value

                          FieldsByName returns a slice of values corresponding to the slice of names for the value. Panics if v's Kind is not Struct or v is not Indirectable to a struct Kind. Returns zero Value for each name not found.

                          func (*Mapper) TraversalsByName

                          func (m *Mapper) TraversalsByName(t reflect.Type, names []string) [][]int

                            TraversalsByName returns a slice of int slices which represent the struct traversals for each mapped name. Panics if t is not a struct or Indirectable to a struct. Returns empty int slice for each name not found.

                            func (*Mapper) TraversalsByNameFunc

                            func (m *Mapper) TraversalsByNameFunc(t reflect.Type, names []string, fn func(int, []int) error) error

                              TraversalsByNameFunc traverses the mapped names and calls fn with the index of each name and the struct traversal represented by that name. Panics if t is not a struct or Indirectable to a struct. Returns the first error returned by fn or nil.

                              func (*Mapper) TypeMap

                              func (m *Mapper) TypeMap(t reflect.Type) *StructMap

                                TypeMap returns a mapping of field strings to int slices representing the traversal down the struct to reach the field.

                                type StructMap

                                type StructMap struct {
                                	Tree  *FieldInfo
                                	Index []*FieldInfo
                                	Paths map[string]*FieldInfo
                                	Names map[string]*FieldInfo
                                }

                                  A StructMap is an index of field metadata for a struct.

                                  func (StructMap) GetByPath

                                  func (f StructMap) GetByPath(path string) *FieldInfo

                                    GetByPath returns a *FieldInfo for a given string path.

                                    func (StructMap) GetByTraversal

                                    func (f StructMap) GetByTraversal(index []int) *FieldInfo

                                      GetByTraversal returns a *FieldInfo for a given integer path. It is analogous to reflect.FieldByIndex, but using the cached traversal rather than re-executing the reflect machinery each time.

                                      Source Files