package envelope import ( "os" "reflect" ) // LoadFromEnv populates a struct with values from environment variables. // // The function takes a pointer to a struct and looks for fields with the `env` tag. // For each field with an `env` tag, it attempts to load the corresponding environment // variable and parse it into the field's type. // // Supported types include: // - string // - bool // - int, int8, int16, int32, int64 // - uint, uint8, uint16, uint32, uint64 // - float32, float64 // - time.Time (RFC3339 format) // - time.Duration // - net.IP // - net.IPNet (CIDR notation) // - url.URL // - []string, []int (comma-separated) // - Nested structs // - Custom types (via registered type parsers) // // For nested structs, the parent field's `env` tag is used as a prefix for all fields // in the nested struct. If the parent field doesn't have an `env` tag, no prefix is added. // // You can override the default parsers or add support for custom types using // RegisterTypeParser. This allows you to customize how environment variable values // are converted to specific types, including the built-in types. // // Example: // // type Config struct { // Host string `env:"HOST"` // Port int `env:"PORT"` // Timeout time.Duration `env:"TIMEOUT"` // Server struct { // MaxConns int `env:"MAX_CONNS"` // } `env:"SERVER"` // } // // // This would look for environment variables: // // HOST, PORT, TIMEOUT, SERVER_MAX_CONNS // // Returns an error if the input is not a pointer to a struct, or if any value // cannot be parsed into the corresponding field type. func LoadFromEnv(ptr any) error { v := reflect.ValueOf(ptr) if v.Kind() != reflect.Ptr || v.Elem().Kind() != reflect.Struct { return newNotPointerToStructError(v.Type()) } v = v.Elem() return loadStructFromEnv(v, "") } func loadStructFromEnv(v reflect.Value, prefix string) error { t := v.Type() for i := range t.NumField() { field := t.Field(i) fieldValue := v.Field(i) if !fieldValue.CanSet() { continue } if fieldValue.Kind() == reflect.Struct { if _, hasParser := typeParserRegistry[fieldValue.Type()]; !hasParser { if err := loadNestedStructFromEnv(fieldValue, field, prefix); err != nil { return err } continue } } envTag := field.Tag.Get("env") if envTag == "" { continue } if err := loadFieldFromEnv(fieldValue, field, envTag, prefix); err != nil { return err } } return nil } func loadNestedStructFromEnv(fieldValue reflect.Value, field reflect.StructField, parentPrefix string) error { // For nested structs, they can have 'env' struct tags // that indicate a prefix for their nested fields when // parsing them. // // e.g. if the parent struct has a tag of "USER" and it // has an inner field with a tag of "NAME", the environment // variable would be "USER_NAME". var nestedPrefix string envTag := field.Tag.Get("env") if envTag != "" { if parentPrefix != "" { nestedPrefix = parentPrefix + "_" + envTag } else { nestedPrefix = envTag } } else { nestedPrefix = parentPrefix } return loadStructFromEnv(fieldValue, nestedPrefix) } func loadFieldFromEnv(fieldValue reflect.Value, field reflect.StructField, envTag string, prefix string) error { envName := buildEnvVarName(envTag, prefix) envValue := os.Getenv(envName) if envValue == "" { return nil } return parseAndSetFieldValue(fieldValue, field, envValue, envName) } func buildEnvVarName(envTag string, prefix string) string { if prefix != "" { return prefix + "_" + envTag } return envTag } func parseAndSetFieldValue(fieldValue reflect.Value, field reflect.StructField, envValue string, envName string) error { if parser, exists := typeParserRegistry[fieldValue.Type()]; exists { val, err := parser.Parse(envValue) if err != nil { return newParseError(field.Name, envName, envValue, fieldValue.Type(), err) } fieldValue.Set(reflect.ValueOf(val)) return nil } return newUnsupportedTypeError(field.Name, fieldValue.Type()) }