https://github.com/cheesycoffee/envparser
A lightweight Go package for parsing environment variables into struct fields using tags
https://github.com/cheesycoffee/envparser
env environment-variables golang golang-library struct structs
Last synced: 3 months ago
JSON representation
A lightweight Go package for parsing environment variables into struct fields using tags
- Host: GitHub
- URL: https://github.com/cheesycoffee/envparser
- Owner: cheesycoffee
- Created: 2025-05-11T14:28:59.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-05-11T15:59:58.000Z (8 months ago)
- Last Synced: 2025-05-13T00:55:40.759Z (8 months ago)
- Topics: env, environment-variables, golang, golang-library, struct, structs
- Language: Go
- Homepage:
- Size: 9.77 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# envparser
A lightweight Go package for parsing environment variables into struct fields using tags, with support for nested/embedded structs and custom decoding.
## Compatibility
- **Go 1.12 or later**
This library is compatible with Go 1.12+ and does not rely on generics or Go modules features introduced after that version.
## ✨ Features
* Simple struct-tag-based configuration
* Support for various primitive types
* Nested and embedded structs
* JSON, XML, Form Data, Base64 decoding via struct tags
* Custom error aggregation
* Works with unexported structs in the same package
---
## 🍞 Installation
```bash
go get github.com/cheesycoffee/envparser
```
---
## 🧠 Supported Data Types
| Go Type | Supported |
| --------------------------------------------------- | ------------------- |
| `string` | ✅ |
| `int`, `int32`, `int64` | ✅ |
| `uint`, `uint32`, `uint64` | ✅ |
| `float32`, `float64` | ✅ |
| `bool` | ✅ |
| `time.Duration` | ✅ |
| `time.Time` (RFC3339 format) | ✅ |
| `[]string` | ✅ (comma-separated) |
| `[]int`, `[]uint` , `[]uint32`, `[]uint64`. | ✅ (comma-separated) |
| `[]float32`, `[]float64`. | ✅ (comma-separated) |
| Structs (anonymous/embedded) | ✅ |
| Structs with `json`/`xml`/`form`/`base64` tags via `encoding:"xml"`/`encoding:"json"`/`encoding:"form"`/`encoding:"base64"` | ✅ |
---
## 🔧 Usage
### 1. Basic Usage
```go
package main
import (
"log"
"time"
"github.com/joho/godotenv"
"github.com/cheesycoffee/envparser"
)
type Nested struct {
NestedValueString string `env:"NESTED_VALUE_STRING"`
NestedValueInt int `env:"NESTED_VALUE_INT"`
}
type Embeded struct {
EmbededValueString string `env:"EMBEDED_VALUE_STRING"`
EmbededValueInt int `env:"EMBEDED_VALUE_INT"`
}
type JSONData struct {
Name string `json:"name"`
Age int `json:"age"`
}
type XMLData struct {
Name string `xml:"name"`
Age int `xml:"age"`
}
type Config struct {
AppName string `env:"APP_NAME"`
Port int `env:"PORT"`
Debug bool `env:"DEBUG"`
PhiVal float32 `env:"PHI_VAL"`
Timeout time.Duration `env:"TIMEOUT"`
LaunchAt time.Time `env:"LAUNCH_AT"` // RFC3339 format
AllowedHosts []string `env:"ALLOWED_HOSTS"`
IDs []uint64 `env:"UINT_IDS"`
NestedValue // nested
EmbededValue EmbededValue // embeded
JSONData JSONData `env:"JSON_VALUE" encoding:"json"`
XMLDATA XMLDATA `env:"XML_VALUE" encoding:"xml"`
FormValue url.Values `env:"FORM_VALUE" encoding:"form"`
FileData []byte `env:"FILE_VALUE" encoding:"base64"`
}
func main() {
_ = godotenv.Load()
var cfg Config
if err := envparser.Parse(&cfg); err != nil {
log.Fatal(err)
}
log.Printf("%+v\n", cfg)
}
```
### .env Example
```
APP_NAME=EnvApp
PORT=8080
DEBUG=true
TIMEOUT=30s
LAUNCH_AT="2023-10-01T15:04:05Z"
ALLOWED_HOSTS="example.com,api.example.com"
PHI_VAL="3.14"
UINT_IDS="1,2,4,5"
NESTED_VALUE_STRING="nested value"
NESTED_VALUE_INT=5
EMBEDED_VALUE_STRING="embeded value string"
EMBEDED_VALUE_INT=5
JSON_VALUE="{\"name\":\"Alice\",\"age\":30}"
XML_VALUE="Alice30"
FORM_VALUE="name=alice&age=30"
FILE_VALUE="SGVsbG8gR28gd29ybGQh"
```
---
## ⚠️ Error Handling
If multiple fields fail to parse, `Parse` aggregates and returns them all:
```go
err := envparser.Parse(&cfg)
if err != nil {
log.Fatalf("Failed to load config:\n%v", err)
}
```
---
## 👀 Notes
* Ensure the target is passed as a **pointer to a struct**: `Parse(&cfg)`
* Environment variable keys must be explicitly defined with `env:"KEY"`
* If a field has no `env` tag or is marked `env:"-"`, it will be ignored
* Embedded/anonymous structs are parsed recursively