reflections

README

Reflections

The reflections library provides high-level abstractions on top of the go language standard reflect library.

In practice, the reflect library's API proves somewhat low-level and un-intuitive. Using it can turn out pretty complex, daunting, and scary, especially when doing simple things like accessing a structure field value, a field tag, etc.

The reflections package aims to make developers' life easier when it comes to introspect struct values at runtime. Its API takes inspiration in the python language's getattr, setattr, and hasattr set of methods and provides simplified access to structure fields and tags.

• Reflections
  • Documentation
  • Usage
    • GetField
    • GetFieldKind
    • GetFieldType
    • GetFieldTag
    • HasField
    • Fields
    • Items
    • Tags
    • GetFieldNameByTagValue
  • Important notes
  • Contribute

Documentation

Head to the documentation to get more details on the library's API.

Usage

GetField

GetField returns the content of a structure field. For example, it proves beneficial when you want to iterate over struct-specific field values. You can provide GetField a structure or a pointer to a struct as the first argument.

s := MyStruct {
    FirstField: "first value",
    SecondField: 2,
    ThirdField: "third value",
}

fieldsToExtract := []string{"FirstField", "ThirdField"}

for _, fieldName := range fieldsToExtract {
    value, err := reflections.GetField(s, fieldName)
    DoWhatEverWithThatValue(value)
}

GetFieldKind

GetFieldKind returns the reflect.Kind of a structure field. You can use it to operate type assertion over a structure field at runtime. You can provide GetFieldKind a structure or a pointer to structure as the first argument.

s := MyStruct{
    FirstField: "first value",
    SecondField: 2,
    ThirdField: "third value",
}

var firstFieldKind reflect.String
var secondFieldKind reflect.Int
var err error

firstFieldKind, err = GetFieldKind(s, "FirstField")
if err != nil {
    log.Fatal(err)
}

secondFieldKind, err = GetFieldKind(s, "SecondField")
if err != nil {
    log.Fatal(err)
}

GetFieldType

GetFieldType returns the string literal of a structure field type. You can use it to operate type assertion over a structure field at runtime. You can provide GetFieldType a structure or a pointer to structure as the first argument.

s := MyStruct{
    FirstField: "first value",
    SecondField: 2,
    ThirdField: "third value",
}

var firstFieldKind string
var secondFieldKind string
var err error

firstFieldKind, err = GetFieldType(s, "FirstField")
if err != nil {
    log.Fatal(err)
}

secondFieldKind, err = GetFieldType(s, "SecondField")
if err != nil {
    log.Fatal(err)
}

GetFieldTag

GetFieldTag extracts a specific structure field tag. You can provide GetFieldTag a structure or a pointer to structure as the first argument.

s := MyStruct{}

tag, err := reflections.GetFieldTag(s, "FirstField", "matched")
if err != nil {
    log.Fatal(err)
}
fmt.Println(tag)

tag, err = reflections.GetFieldTag(s, "ThirdField", "unmatched")
if err != nil {
    log.Fatal(err)
}
fmt.Println(tag)

HasField

HasField asserts a field exists through the structure. You can provide HasField a struct or a pointer to a struct as the first argument.

s := MyStruct {
    FirstField: "first value",
    SecondField: 2,
    ThirdField: "third value",
}

// has == true
has, _ := reflections.HasField(s, "FirstField")

// has == false
has, _ := reflections.HasField(s, "FourthField")

Fields

Fields returns the list of structure field names so that you can access or update them later. You can provide Fields with a struct or a pointer to a struct as the first argument.

s := MyStruct {
    FirstField: "first value",
    SecondField: 2,
    ThirdField: "third value",
}

var fields []string

// Fields will list every structure exportable fields.
// Here, it's content would be equal to:
// []string{"FirstField", "SecondField", "ThirdField"}
fields, _ = reflections.Fields(s)

Items

Items returns the structure's field name to the values map. You can provide Items with a struct or a pointer to structure as the first argument.

s := MyStruct {
    FirstField: "first value",
    SecondField: 2,
    ThirdField: "third value",
}

var structItems map[string]interface{}

// Items will return a field name to
// field value map
structItems, _ = reflections.Items(s)

Tags

Tags returns the structure's fields tag with the provided key. You can provide Tags with a struct or a pointer to a struct as the first argument.

s := MyStruct {
    FirstField: "first value",      `matched:"first tag"`
    SecondField: 2,                 `matched:"second tag"`
    ThirdField: "third value",      `unmatched:"third tag"`
}

var structTags map[string]string

// Tags will return a field name to tag content
// map. N.B that only field with the tag name
// you've provided will be matched.
// Here structTags will contain:
// {
// "FirstField": "first tag",
// "SecondField": "second tag",
// }
structTags, _ = reflections.Tags(s, "matched")

SetField

SetField updates a structure's field value with the one provided. Note that you can't set un-exported fields and that the field and value types must match.

s := MyStruct {
    FirstField: "first value",
    SecondField: 2,
    ThirdField: "third value",
}

//To be able to set the structure's values,
// it must be passed as a pointer.
_ := reflections.SetField(&s, "FirstField", "new value")

// If you try to set a field's value using the wrong type,
// an error will be returned
err := reflection.SetField(&s, "FirstField", 123) // err != nil

GetFieldNameByTagValue

GetFieldNameByTagValue looks up a field with a matching {tagKey}:"{tagValue}" tag in the provided obj item. If obj is not a struct, nor a pointer, or it does not have a field tagged with the tagKey, and the matching tagValue, this function returns an error.

s := MyStruct {
    FirstField: "first value",      `matched:"first tag"`
    SecondField: 2,                 `matched:"second tag"`
    ThirdField: "third value",      `unmatched:"third tag"`
}

// Getting field name from external source as json would be a headache to convert it manually, 
// so we get it directly from struct tag
// returns fieldName = "FirstField"
fieldName, _ = reflections.GetFieldNameByTagValue(s, "matched", "first tag");

// later we can do GetField(s, fieldName)

Important notes

• Un-exported fields can't be accessed nor set using the reflections library. The Go lang standard reflect library intentionally prohibits un-exported fields values access or modifications.

Contribute

• Check for open issues or open a new issue to start a discussion around a feature idea or a bug.
• Fork the repository on GitHub to start making your changes to the master branch, or branch off of it.
• Write tests showing that the bug was fixed or the feature works as expected.
• Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to AUTHORS.

Documentation

Overview

Package reflections provides high level abstractions over the Go standard reflect library.

In practice, the `reflect` library's API proves somewhat low-level and un-intuitive. Using it can turn out pretty complex, daunting, and scary, when doing simple things like accessing a structure field value, a field tag, etc.

The `reflections` package aims to make developers' life easier when it comes to introspect struct values at runtime. Its API takes inspiration in the python language's `getattr,` `setattr,` and `hasattr` set of methods and provides simplified access to structure fields and tags.

Index

• Variables
• func Fields(obj interface{}) ([]string, error)
• func FieldsDeep(obj interface{}) ([]string, error)
• func GetField(obj interface{}, name string) (interface{}, error)
• func GetFieldKind(obj interface{}, name string) (reflect.Kind, error)
• func GetFieldNameByTagValue(obj interface{}, tagKey, tagValue string) (string, error)
• func GetFieldTag(obj interface{}, fieldName, tagKey string) (string, error)
• func GetFieldType(obj interface{}, name string) (string, error)
• func HasField(obj interface{}, name string) (bool, error)
• func Items(obj interface{}) (map[string]interface{}, error)
• func ItemsDeep(obj interface{}) (map[string]interface{}, error)
• func SetField(obj interface{}, name string, value interface{}) error
• func Tags(obj interface{}, key string) (map[string]string, error)
• func TagsDeep(obj interface{}, key string) (map[string]string, error)

Examples

• Fields
• GetField
• GetFieldKind
• GetFieldNameByTagValue
• GetFieldTag
• GetFieldType
• HasField
• Items
• ItemsDeep
• SetField
• Tags

Variables

var ErrUnexportedField = errors.New("unexported field")

ErrUnexportedField indicates that an operation failed as a result of applying to a non-exported struct field.

var ErrUnsupportedType = errors.New("unsupported type")

ErrUnsupportedType indicates that the provided type doesn't support the requested reflection operation.

Functions

func Fields

func Fields(obj interface{}) ([]string, error)

Fields returns the struct fields names list. The `obj` parameter can either be a structure or pointer to structure.

Example

package main

import (
	"fmt"

	"github.com/oleiade/reflections"
)

type MyStruct struct {
	MyEmbeddedStruct
	FirstField  string `matched:"first tag"`
	SecondField int    `matched:"second tag"`
	ThirdField  string `unmatched:"third tag"`
}

type MyEmbeddedStruct struct {
	EmbeddedField string
}

func main() {
	s := MyStruct{
		FirstField:  "first value",
		SecondField: 2,
		ThirdField:  "third value",
	}

	var fields []string

	// Fields will list every structure exportable fields.
	// Here, it's content would be equal to:
	// []string{"FirstField", "SecondField", "ThirdField"}
	fields, _ = reflections.Fields(s)
	fmt.Println(fields)

}

Output:

[MyEmbeddedStruct FirstField SecondField ThirdField]

func FieldsDeep

func FieldsDeep(obj interface{}) ([]string, error)

FieldsDeep returns "flattened" fields.

Note that FieldsDeep treats fields from anonymous inner structs as normal fields.

func GetField

func GetField(obj interface{}, name string) (interface{}, error)

GetField returns the value of the provided obj field. The `obj` can either be a structure or pointer to structure.

Example

package main

import (
	"fmt"
	"log"

	"github.com/oleiade/reflections"
)

type MyStruct struct {
	MyEmbeddedStruct
	FirstField  string `matched:"first tag"`
	SecondField int    `matched:"second tag"`
	ThirdField  string `unmatched:"third tag"`
}

type MyEmbeddedStruct struct {
	EmbeddedField string
}

func main() {
	s := MyStruct{
		FirstField:  "first value",
		SecondField: 2,
		ThirdField:  "third value",
	}

	fieldsToExtract := []string{"FirstField", "ThirdField"}

	for _, fieldName := range fieldsToExtract {
		value, err := reflections.GetField(s, fieldName)
		if err != nil {
			log.Fatal(err)
		}

		fmt.Println(value)

	}
}

Output:

first value
third value

func GetFieldKind

func GetFieldKind(obj interface{}, name string) (reflect.Kind, error)

GetFieldKind returns the kind of the provided obj field. The `obj` can either be a structure or pointer to structure.

Example

package main

import (
	"fmt"
	"log"
	"reflect"

	"github.com/oleiade/reflections"
)

type MyStruct struct {
	MyEmbeddedStruct
	FirstField  string `matched:"first tag"`
	SecondField int    `matched:"second tag"`
	ThirdField  string `unmatched:"third tag"`
}

type MyEmbeddedStruct struct {
	EmbeddedField string
}

func main() {
	s := MyStruct{
		FirstField:  "first value",
		SecondField: 2,
		ThirdField:  "third value",
	}

	var firstFieldKind reflect.Kind
	var secondFieldKind reflect.Kind
	var err error

	// GetFieldKind will return reflect.String
	firstFieldKind, err = reflections.GetFieldKind(s, "FirstField")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(firstFieldKind)

	// GetFieldKind will return reflect.Int
	secondFieldKind, err = reflections.GetFieldKind(s, "SecondField")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(secondFieldKind)

}

Output:

string
int

func GetFieldNameByTagValue

func GetFieldNameByTagValue(obj interface{}, tagKey, tagValue string) (string, error)

GetFieldNameByTagValue looks up a field with a matching `{tagKey}:"{tagValue}"` tag in the provided `obj` item. The `obj` parameter must be a `struct`, or a `pointer` to one. If the `obj` parameter doesn't have a field tagged with the `tagKey`, and the matching `tagValue`, this function returns an error.

Example

package main

import (
	"encoding/json"
	"fmt"
	"log"

	"github.com/oleiade/reflections"
)

func main() {
	type Order struct {
		Step     string `json:"order_step"`
		ID       string `json:"id"`
		Category string `json:"category"`
	}
	type Condition struct {
		Field string `json:"field"`
		Value string `json:"value"`
		Next  string `json:"next"`
	}

	// JSON data from external source
	orderJSON := `{
		"order_step": "cooking",
		"id": "45457-fv54f54",
		"category": "Pizzas"
	}`

	conditionJSON := `{
		"field": "order_step", 
		"value": "cooking",
		"next": "serve"
	}`

	// Storing JSON in corresponding Variables
	var order Order
	err := json.Unmarshal([]byte(orderJSON), &order)
	if err != nil {
		log.Fatal(err)
	}

	var condition Condition
	err = json.Unmarshal([]byte(conditionJSON), &condition)
	if err != nil {
		log.Fatal(err)
	}

	fieldName, _ := reflections.GetFieldNameByTagValue(order, "json", condition.Field)
	fmt.Println(fieldName)
	fieldValue, _ := reflections.GetField(order, fieldName)
	fmt.Println(fieldValue)

}

Output:

Step
cooking

func GetFieldTag

func GetFieldTag(obj interface{}, fieldName, tagKey string) (string, error)

GetFieldTag returns the provided obj field tag value. The `obj` parameter can either be a structure or pointer to structure.

Example

package main

import (
	"fmt"
	"log"

	"github.com/oleiade/reflections"
)

type MyStruct struct {
	MyEmbeddedStruct
	FirstField  string `matched:"first tag"`
	SecondField int    `matched:"second tag"`
	ThirdField  string `unmatched:"third tag"`
}

type MyEmbeddedStruct struct {
	EmbeddedField string
}

func main() {
	s := MyStruct{}

	tag, err := reflections.GetFieldTag(s, "FirstField", "matched")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(tag)

	tag, err = reflections.GetFieldTag(s, "ThirdField", "unmatched")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(tag)

}

Output:

first tag
third tag

func GetFieldType

func GetFieldType(obj interface{}, name string) (string, error)

GetFieldType returns the kind of the provided obj field. The `obj` can either be a structure or pointer to structure.

Example

package main

import (
	"fmt"
	"log"

	"github.com/oleiade/reflections"
)

type MyStruct struct {
	MyEmbeddedStruct
	FirstField  string `matched:"first tag"`
	SecondField int    `matched:"second tag"`
	ThirdField  string `unmatched:"third tag"`
}

type MyEmbeddedStruct struct {
	EmbeddedField string
}

func main() {
	s := MyStruct{
		FirstField:  "first value",
		SecondField: 2,
		ThirdField:  "third value",
	}

	var firstFieldType string
	var secondFieldType string
	var err error

	// GetFieldType will return reflect.String
	firstFieldType, err = reflections.GetFieldType(s, "FirstField")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(firstFieldType)

	// GetFieldType will return reflect.Int
	secondFieldType, err = reflections.GetFieldType(s, "SecondField")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(secondFieldType)

}

Output:

string
int

func HasField

func HasField(obj interface{}, name string) (bool, error)

HasField checks if the provided `obj` struct has field named `name`. The `obj` can either be a structure or pointer to structure.

Example

package main

import (
	"fmt"

	"github.com/oleiade/reflections"
)

type MyStruct struct {
	MyEmbeddedStruct
	FirstField  string `matched:"first tag"`
	SecondField int    `matched:"second tag"`
	ThirdField  string `unmatched:"third tag"`
}

type MyEmbeddedStruct struct {
	EmbeddedField string
}

func main() {
	s := MyStruct{
		FirstField:  "first value",
		SecondField: 2,
		ThirdField:  "third value",
	}

	// has == true
	has, _ := reflections.HasField(s, "FirstField")
	fmt.Println(has)

	// has == false
	has, _ = reflections.HasField(s, "FourthField")
	fmt.Println(has)

}

Output:

true
false

func Items

func Items(obj interface{}) (map[string]interface{}, error)

Items returns the field:value struct pairs as a map. The `obj` parameter can either be a structure or pointer to structure.

Example

package main

import (
	"fmt"

	"github.com/oleiade/reflections"
)

type MyStruct struct {
	MyEmbeddedStruct
	FirstField  string `matched:"first tag"`
	SecondField int    `matched:"second tag"`
	ThirdField  string `unmatched:"third tag"`
}

type MyEmbeddedStruct struct {
	EmbeddedField string
}

func main() {
	s := MyStruct{
		FirstField:  "first value",
		SecondField: 2,
		ThirdField:  "third value",
	}

	var structItems map[string]interface{}

	// Items will return a field name to
	// field value map
	structItems, _ = reflections.Items(s)
	fmt.Println(structItems)

}

Output:

map[FirstField:first value MyEmbeddedStruct:{} SecondField:2 ThirdField:third value]

func ItemsDeep

func ItemsDeep(obj interface{}) (map[string]interface{}, error)

ItemsDeep returns "flattened" items. Note that ItemsDeep will treat fields from anonymous inner structs as normal fields.

Example

package main

import (
	"fmt"

	"github.com/oleiade/reflections"
)

type MyStruct struct {
	MyEmbeddedStruct
	FirstField  string `matched:"first tag"`
	SecondField int    `matched:"second tag"`
	ThirdField  string `unmatched:"third tag"`
}

type MyEmbeddedStruct struct {
	EmbeddedField string
}

func main() {
	s := MyStruct{
		FirstField:  "first value",
		SecondField: 2,
		ThirdField:  "third value",
		MyEmbeddedStruct: MyEmbeddedStruct{
			EmbeddedField: "embedded value",
		},
	}

	var structItems map[string]interface{}

	// ItemsDeep will return a field name to
	// field value map, including fields from
	// anonymous embedded structs
	structItems, _ = reflections.ItemsDeep(s)
	fmt.Println(structItems)

}

Output:

map[EmbeddedField:embedded value FirstField:first value SecondField:2 ThirdField:third value]

func SetField

func SetField(obj interface{}, name string, value interface{}) error

SetField sets the provided obj field with provided value.

The `obj` parameter must be a pointer to a struct, otherwise it soundly fails. The provided `value` type should match with the struct field being set.

Example

package main

import (
	"log"

	"github.com/oleiade/reflections"
)

type MyStruct struct {
	MyEmbeddedStruct
	FirstField  string `matched:"first tag"`
	SecondField int    `matched:"second tag"`
	ThirdField  string `unmatched:"third tag"`
}

type MyEmbeddedStruct struct {
	EmbeddedField string
}

func main() {
	s := MyStruct{
		FirstField:  "first value",
		SecondField: 2,
		ThirdField:  "third value",
	}

	// In order to be able to set the structure's values,
	// a pointer to it has to be passed to it.
	err := reflections.SetField(&s, "FirstField", "new value")
	if err != nil {
		log.Fatal(err)
	}

	// Note that if you try to set a field's value using the wrong type,
	// an error will be returned
	_ = reflections.SetField(&s, "FirstField", 123) // err != nil

}

func Tags

func Tags(obj interface{}, key string) (map[string]string, error)

Tags lists the struct tag fields. The `obj` can whether be a structure or pointer to structure.

Example

package main

import (
	"fmt"

	"github.com/oleiade/reflections"
)

type MyStruct struct {
	MyEmbeddedStruct
	FirstField  string `matched:"first tag"`
	SecondField int    `matched:"second tag"`
	ThirdField  string `unmatched:"third tag"`
}

type MyEmbeddedStruct struct {
	EmbeddedField string
}

func main() {
	s := MyStruct{
		FirstField:  "first value",
		SecondField: 2,
		ThirdField:  "third value",
	}

	var structTags map[string]string

	// Tags will return a field name to tag content
	// map. Nota that only field with the tag name
	// you've provided which will be matched.
	// Here structTags will contain:
	// {
	//     "FirstField": "first tag",
	//     "SecondField": "second tag",
	// }
	structTags, _ = reflections.Tags(s, "matched")
	fmt.Println(structTags)

}

Output:

map[FirstField:first tag MyEmbeddedStruct: SecondField:second tag ThirdField:]

func TagsDeep

func TagsDeep(obj interface{}, key string) (map[string]string, error)

TagsDeep returns "flattened" tags. Note that TagsDeep treats fields from anonymous inner structs as normal fields.