# Reflections Library

The reflections library provides a set of utilities for working with Go's reflection capabilities. It simplifies common reflection tasks such as getting and setting struct fields, inspecting field types and tags, and working with nested structs.

## Installation
To use this package, import it in your Go code:
```go
import "github.com/getevo/evo/v2/lib/reflections"
```

## Features

- **Field Access**: Get and set struct fields by name
- **Field Inspection**: Get field kind, type, and tag information
- **Field Discovery**: List all fields in a struct
- **Tag Handling**: Access and search for struct tags
- **Deep Reflection**: Work with nested struct fields
- **Type Safety**: Proper error handling for type mismatches

## Functions

---
### GetField

```go
func GetField(obj interface{}, name string) (interface{}, error)
```
Description: Returns the value of the provided object field.

---
### GetFieldKind
```go
func GetFieldKind(obj interface{}, name string) (reflect.Kind, error)
```
Description: Returns the kind of the provided object field.

---
### GetFieldType
```go
func GetFieldType(obj interface{}, name string) (string, error)
```
Description: Returns the type of the provided object field.

---
### GetFieldTag
```go
func GetFieldTag(obj interface{}, fieldName, tagKey string) (string, error)
```
Description: Returns the tag value of the provided object field.

---
### GetFieldNameByTagValue
```go
func GetFieldNameByTagValue(obj interface{}, tagKey, tagValue string) (string, error)
```
Description: Looks up a field with a matching tag value in the provided object.

---
### SetField
```go
func SetField(obj interface{}, name string, value interface{}) error
```
Description: Sets the value of the provided object field.

---
### HasField
```go
func HasField(obj interface{}, name string) (bool, error)
```
Description: Checks if the provided object has a field with the given name.

---
### Fields
```go
func Fields(obj interface{}) ([]string, error)
```
Description: Returns the names of the fields in the provided object.

---
### FieldsDeep
```go
func FieldsDeep(obj interface{}) ([]string, error)
```
Description: Returns the "flattened" names of the fields in the provided object, including fields from anonymous inner structs.

---
### Items
```go
func Items(obj interface{}) (map[string]interface{}, error)
```
Description: Returns the field:value pairs of the provided object as a map.

---
### ItemsDeep

```go
func ItemsDeep(obj interface{}) (map[string]interface{}, error)
```
Description: Returns the "flattened" field:value pairs of the provided object as a map, including fields from anonymous inner structs.

---
### Tags
```go
func Tags(obj interface{}, key string) (map[string]string, error)
```
Description: Returns the tags of the fields in the provided object as a map.

---
### TagsDeep
```go
func TagsDeep(obj interface{}, key string) (map[string]string, error)
```
Description: Returns the "flattened" tags of the fields in the provided object as a map, including fields from anonymous inner structs.

---

## Usage Examples

### Getting and Setting Fields

```go
package main

import (
    "fmt"
    "github.com/getevo/evo/v2/lib/reflections"
)

type Person struct {
    Name    string
    Age     int
    Address string
}

func main() {
    person := Person{
        Name:    "John Doe",
        Age:     30,
        Address: "123 Main St",
    }
    
    // Get a field value
    name, err := reflections.GetField(person, "Name")
    if err == nil {
        fmt.Printf("Name: %s\n", name)
    }
    
    // Set a field value
    err = reflections.SetField(&person, "Age", 31)
    if err == nil {
        fmt.Printf("Updated age: %d\n", person.Age)
    }
    
    // Check if a field exists
    hasField, _ := reflections.HasField(person, "Email")
    fmt.Printf("Has Email field: %t\n", hasField)
}
```

### Working with Field Types and Tags

```go
package main

import (
    "fmt"
    "github.com/getevo/evo/v2/lib/reflections"
)

type User struct {
    ID        int    `json:"id" db:"user_id"`
    Username  string `json:"username" db:"username"`
    Email     string `json:"email" db:"email"`
    CreatedAt string `json:"created_at" db:"created_at"`
}

func main() {
    user := User{
        ID:        1,
        Username:  "johndoe",
        Email:     "john@example.com",
        CreatedAt: "2023-01-01",
    }
    
    // Get field kind
    kind, _ := reflections.GetFieldKind(user, "Username")
    fmt.Printf("Username field kind: %s\n", kind)
    
    // Get field type
    fieldType, _ := reflections.GetFieldType(user, "ID")
    fmt.Printf("ID field type: %s\n", fieldType)
    
    // Get field tag
    jsonTag, _ := reflections.GetFieldTag(user, "Email", "json")
    fmt.Printf("Email JSON tag: %s\n", jsonTag)
    
    // Find field by tag value
    fieldName, _ := reflections.GetFieldNameByTagValue(user, "db", "user_id")
    fmt.Printf("Field with db tag 'user_id': %s\n", fieldName)
}
```

### Working with Nested Structs

```go
package main

import (
    "fmt"
    "github.com/getevo/evo/v2/lib/reflections"
)

type Address struct {
    Street  string
    City    string
    Country string
}

type Customer struct {
    Name    string
    Age     int
    Address Address
}

func main() {
    customer := Customer{
        Name: "Jane Doe",
        Age:  28,
        Address: Address{
            Street:  "456 Oak Ave",
            City:    "Metropolis",
            Country: "USA",
        },
    }
    
    // Get all fields including nested ones
    fieldsDeep, _ := reflections.FieldsDeep(customer)
    fmt.Println("All fields (deep):", fieldsDeep)
    
    // Get all field values including nested ones
    itemsDeep, _ := reflections.ItemsDeep(customer)
    for field, value := range itemsDeep {
        fmt.Printf("%s: %v\n", field, value)
    }
}
```

## How It Works

The reflections library uses Go's built-in `reflect` package to inspect and manipulate struct values at runtime. It provides a higher-level API that makes common reflection tasks easier and safer.

The library handles various edge cases, such as unexported fields, pointer values, and nested structs. It also provides both shallow and deep operations for working with nested structures.

---
#### [< Table of Contents](https://github.com/getevo/evo#table-of-contents)