diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3e9748b..5acc96c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -18,7 +18,7 @@ jobs:
with:
fetch-depth: 0
- name: Linter
- uses: golangci/golangci-lint-action@v6.1.0
+ uses: golangci/golangci-lint-action@v9.2.0
tests:
name: Tests
needs: lint
diff --git a/.golangci.bck.yaml b/.golangci.bck.yaml
new file mode 100644
index 0000000..73eca13
--- /dev/null
+++ b/.golangci.bck.yaml
@@ -0,0 +1,43 @@
+run:
+ deadline: 5m
+ issues-exit-code: 1
+
+output:
+ formats: colored-line-number
+ print-issued-lines: true
+ print-linter-name: true
+
+linters-settings:
+ dupl:
+ threshold: 250
+ lll:
+ line-length: 160
+ goconst:
+ min-len: 2
+ min-occurrences: 3
+ errcheck:
+ exclude-functions:
+ - (io.Closer).Close
+ cyclop:
+ max-complexity: 10
+ funlen:
+ lines: 50
+
+linters:
+ disable-all: true
+ enable:
+ - dupl
+ - errcheck
+ - goconst
+ - gosec
+ - gosimple
+ - govet
+ - ineffassign
+ - staticcheck
+ - typecheck
+ - unused
+ - funlen
+ - cyclop
+ - lll
+ - forbidigo
+
diff --git a/.golangci.yaml b/.golangci.yaml
index 73eca13..c378fae 100644
--- a/.golangci.yaml
+++ b/.golangci.yaml
@@ -1,43 +1,57 @@
+version: "2"
run:
- deadline: 5m
issues-exit-code: 1
-
output:
- formats: colored-line-number
- print-issued-lines: true
- print-linter-name: true
-
-linters-settings:
- dupl:
- threshold: 250
- lll:
- line-length: 160
- goconst:
- min-len: 2
- min-occurrences: 3
- errcheck:
- exclude-functions:
- - (io.Closer).Close
- cyclop:
- max-complexity: 10
- funlen:
- lines: 50
-
+ formats:
+ text:
+ path: stdout
+ print-linter-name: true
+ print-issued-lines: true
linters:
- disable-all: true
+ default: none
enable:
+ - cyclop
- dupl
- errcheck
+ - forbidigo
+ - funlen
- goconst
- gosec
- - gosimple
- govet
- ineffassign
+ - lll
- staticcheck
- - typecheck
- unused
- - funlen
- - cyclop
- - lll
- - forbidigo
-
+ settings:
+ cyclop:
+ max-complexity: 10
+ dupl:
+ threshold: 250
+ errcheck:
+ exclude-functions:
+ - (io.Closer).Close
+ funlen:
+ lines: 50
+ goconst:
+ min-len: 2
+ min-occurrences: 3
+ lll:
+ line-length: 160
+ exclusions:
+ generated: lax
+ presets:
+ - comments
+ - common-false-positives
+ - legacy
+ - std-error-handling
+ paths:
+ - third_party$
+ - builtin$
+ - examples$
+formatters:
+ exclusions:
+ generated: lax
+ paths:
+ - third_party$
+ - builtin$
+ - examples$
diff --git a/README.md b/README.md
index 774ec2c..fa11563 100644
--- a/README.md
+++ b/README.md
@@ -1,132 +1,268 @@
-# envYaml (Yaml with environment value loader)
+
-[](https://codecov.io/github/yuseferi/envyaml)
-[](https://github.com/yuseferi/envyaml/actions/workflows/ci.yml)
-[](https://www.gnu.org/licenses/agpl-3.0)
-
-[](https://goreportcard.com/report/github.com/yuseferi/envyaml)
+# π envYaml
-
-
+### Seamlessly merge YAML configuration with environment variables
+
+[](https://go.dev/)
+[](https://codecov.io/github/yuseferi/envyaml)
+[](https://github.com/yuseferi/envyaml/actions/workflows/ci.yml)
+[](https://goreportcard.com/report/github.com/yuseferi/envyaml)
+[](LICENSE)
+[](https://github.com/yuseferi/envyaml/releases)
+
+
+
-Storing application configuration in YAML files offers a clean and straightforward solution, but it's crucial to avoid exposing sensitive data like passwords and API keys. Environment variables provide a secure way to store secrets, preventing them from leaking into your codebase.
+**Keep your configuration clean. Keep your secrets safe.**
+
+[Installation](#-installation) β’
+[Quick Start](#-quick-start) β’
+[Features](#-features) β’
+[Examples](#-examples) β’
+[Contributing](#-contributing)
-The **envyaml** package bridges this gap, allowing you to seamlessly integrate environment variables into your YAML configuration. No more plain-text secrets or complex workarounds! Simply reference environment variables within your YAML file using placeholders, and envyaml will handle the rest, securely substituting the values during parsing.
+---
-With **envyaml**, you can:
+
-- Keep your configuration clean and organized in YAML.
-- Protect sensitive data by storing it in environment variables.
-- Enjoy a simple and intuitive integration process.
-- No more compromising between convenience and security. **envyaml** empowers you to manage your application configuration effectively while keeping your secrets safe.
+## π― The Problem
-## Installation
+You love YAML for configurationβit's clean, readable, and organized. But what about sensitive data like API keys, database passwords, and tokens? Hardcoding them is a security nightmare. π±
-To install envyaml, use `go get`:
+## β¨ The Solution
+**envYaml** bridges the gap between clean YAML configuration and secure environment variable management. Reference environment variables directly in your YAML files, and envYaml handles the rest!
+
+```yaml
+# config.yml - Clean and secure! π
+database:
+ host: localhost
+ port: 5432
+ password: ${DB_PASSWORD} # Loaded from environment
+
+api:
+ key: ${API_KEY} # Never committed to git
+ secret: ${API_SECRET} # Always secure
```
+
+## π Installation
+
+```bash
go get github.com/yuseferi/envyaml@latest
```
-## Usage
+**Requirements:** Go 1.25+
+
+## β‘ Quick Start
+
+**1. Create your YAML configuration:**
-### Example 1: Error on required env variable
+```yaml
+# config.yml
+host: localhost
+port: 3606
+password: ${DB_PASSWORD}
+```
+
+**2. Define your config struct:**
```go
-type TestConfig struct {
- Host string `yaml:"host" env:"TEST_HOST"`
- Port int `yaml:"port" env:"TEST_PORT"`
- Password string `yaml:"password" env:"TEST_PASSWORD,required"`
+type Config struct {
+ Host string `yaml:"host" env:"HOST"`
+ Port int `yaml:"port" env:"PORT"`
+ Password string `yaml:"password" env:"DB_PASSWORD,required"`
}
+```
-// Load the configuration
-var cfg TestConfig
-// assume your configs are in `config.yml` file and this is its content:
-//host: localhost
-//port: 3606
-//password: ${TEST_PASSWORD}
-err := envyaml.LoadConfig("config.yml", &cfg)
-if err != nil {
- log.Fatalln(err)
+**3. Load and use:**
+
+```go
+package main
+
+import (
+ "fmt"
+ "log"
+
+ "github.com/yuseferi/envyaml"
+)
+
+func main() {
+ var cfg Config
+
+ if err := envyaml.LoadConfig("config.yml", &cfg); err != nil {
+ log.Fatal(err)
+ }
+
+ fmt.Printf("Connected to %s:%d\n", cfg.Host, cfg.Port)
}
-fmt.Println(cfg)
```
-Error `failed to parse environment variables: env: required environment variable "TEST_PASSWORD" is not set` is expected because this variable has not been set.
+## π¨ Features
+
+| Feature | Description |
+|---------|-------------|
+| π **Seamless Integration** | Combine YAML files with environment variables effortlessly |
+| β
**Required Variables** | Mark critical env vars as required with automatic validation |
+| π·οΈ **Struct Tags** | Use familiar `yaml` and `env` struct tags |
+| π‘οΈ **Type Safety** | Full Go type safety with automatic type conversion |
+| π¦ **Zero Config** | Works out of the box with sensible defaults |
+| πͺΆ **Lightweight** | Minimal dependencies, maximum performance |
+
+## π Examples
-### Example 2: When env is defined
+### Required Environment Variables
+
+Mark sensitive variables as required to fail fast if they're missing:
```go
-type TestConfig struct {
- Host string `yaml:"host" env:"TEST_HOST"`
- Port int `yaml:"port" env:"TEST_PORT"`
- Password string `yaml:"password" env:"TEST_PASSWORD,required"`
+type Config struct {
+ Host string `yaml:"host" env:"HOST"`
+ Port int `yaml:"port" env:"PORT"`
+ Password string `yaml:"password" env:"DB_PASSWORD,required"` // π Required!
}
-// Load the configuration
-var cfg TestConfig
-// assume your configs are in `config.yml` file and this is its content:
-//host: localhost
-//port: 3606
-//password: ${TEST_PASSWORD}
-_ = os.Setenv("TEST_PASSWORD", "envyaml_pass")
+var cfg Config
err := envyaml.LoadConfig("config.yml", &cfg)
if err != nil {
-log.Fatalln(err)
-log.Fatalln(err)
+ // Error: failed to parse environment variables: env: required environment variable "DB_PASSWORD" is not set
+ log.Fatal(err)
+}
+```
- log.Fatalln(err)
+### Complete Working Example
+```go
+package main
+
+import (
+ "fmt"
+ "log"
+ "os"
+
+ "github.com/yuseferi/envyaml"
+)
+
+type DatabaseConfig struct {
+ Host string `yaml:"host" env:"DB_HOST"`
+ Port int `yaml:"port" env:"DB_PORT"`
+ Username string `yaml:"username" env:"DB_USER"`
+ Password string `yaml:"password" env:"DB_PASSWORD,required"`
+ Database string `yaml:"database" env:"DB_NAME"`
}
-fmt.Println(cfg)
-```
-Expected output:
-```
-{localhost 3606 envyaml_pass}
+type Config struct {
+ Database DatabaseConfig `yaml:"database"`
+ Debug bool `yaml:"debug" env:"DEBUG"`
+}
+
+func main() {
+ // Set environment variables (in production, these come from your environment)
+ os.Setenv("DB_PASSWORD", "super_secret_password")
+
+ var cfg Config
+ if err := envyaml.LoadConfig("config.yml", &cfg); err != nil {
+ log.Fatalf("Failed to load config: %v", err)
+ }
+
+ fmt.Printf("Database: %s@%s:%d/%s\n",
+ cfg.Database.Username,
+ cfg.Database.Host,
+ cfg.Database.Port,
+ cfg.Database.Database,
+ )
+}
```
-## Development
+With this `config.yml`:
-This project uses [Task](https://taskfile.dev) for managing development tasks. Make sure you have Task installed on your system.
+```yaml
+database:
+ host: localhost
+ port: 5432
+ username: admin
+ password: ${DB_PASSWORD}
+ database: myapp
-### Available Tasks
+debug: false
+```
-- `task build`: Build the project
-- `task test`: Run tests
-- `task test-coverage`: Run tests with coverage and generate a coverage report
-- `task clean`: Clean up generated files
-- `task all`: Run all tasks (build, test, and coverage)
+**Output:**
+```
+Database: admin@localhost:5432/myapp
+```
-To run a task, use the `task` command followed by the task name. For example:
+## ποΈ How It Works
```
-task build
+βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
+β YAML File β β Environment β β Go Struct β
+β β β Variables β β β
+β host: localhostβ β β β Host: localhostβ
+β port: 3606 β βββΊ β DB_PASSWORD= β βββΊ β Port: 3606 β
+β password: ${..}β β "secret123" β β Password: ... β
+βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
+ β β β
+ βββββββββββββββββββββββββ΄ββββββββββββββββββββββββ
+ envYaml
```
-### Running Tests
+1. **Read** - Parse your YAML configuration file
+2. **Merge** - Overlay environment variables using struct tags
+3. **Validate** - Ensure required variables are present
+4. **Return** - Provide a fully populated, type-safe config struct
-To run tests:
+## π οΈ Development
-```
-task test
-```
+This project uses [Task](https://taskfile.dev) for managing development tasks.
-To run tests with coverage:
+```bash
+# Build the project
+task build
-```
+# Run tests
+task test
+
+# Run tests with coverage
task test-coverage
+
+# Clean generated files
+task clean
+
+# Run all tasks
+task all
```
-This will generate a coverage report in HTML format (`coverage.html`).
+## π€ Contributing
+
+We love contributions! β€οΈ
+
+1. π΄ Fork the repository
+2. πΏ Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. πΎ Commit your changes (`git commit -m 'Add amazing feature'`)
+4. π€ Push to the branch (`git push origin feature/amazing-feature`)
+5. π Open a Pull Request
+
+Please feel free to:
+- π Report bugs
+- π‘ Suggest new features
+- π Improve documentation
+- β Star the project if you find it useful!
+
+## π License
+
+This project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](LICENSE) file for details.
-## Contributing
+---
-We strongly believe in open-source β€οΈπ. Please feel free to contribute by raising issues and submitting pull requests to make envYaml even better!
+
-## License
+**Made with β€οΈ by [Yusef Mohamadi](https://github.com/yuseferi)**
-Released under the [GNU GENERAL PUBLIC LICENSE](LICENSE).
+If this project helped you, consider giving it a β!
+[](https://github.com/yuseferi/envyaml/stargazers)
+[](https://github.com/yuseferi/envyaml/network/members)
+
diff --git a/go.mod b/go.mod
index a81563f..0786aae 100644
--- a/go.mod
+++ b/go.mod
@@ -1,10 +1,10 @@
module github.com/yuseferi/envyaml
-go 1.22.0
+go 1.25
require (
- github.com/caarlos0/env/v11 v11.2.2
- github.com/stretchr/testify v1.9.0
+ github.com/caarlos0/env/v11 v11.3.1
+ github.com/stretchr/testify v1.11.1
gopkg.in/yaml.v3 v3.0.1
)
diff --git a/go.sum b/go.sum
index 042c1e1..1b1a4b7 100644
--- a/go.sum
+++ b/go.sum
@@ -1,11 +1,15 @@
github.com/caarlos0/env/v11 v11.2.2 h1:95fApNrUyueipoZN/EhA8mMxiNxrBwDa+oAZrMWl3Kg=
github.com/caarlos0/env/v11 v11.2.2/go.mod h1:JBfcdeQiBoI3Zh1QRAWfe+tpiNTmDtcCj/hHHHMx0vc=
+github.com/caarlos0/env/v11 v11.3.1 h1:cArPWC15hWmEt+gWk7YBi7lEXTXCvpaSdCiZE2X5mCA=
+github.com/caarlos0/env/v11 v11.3.1/go.mod h1:qupehSf/Y0TUTsxKywqRt/vJjN5nz6vauiYEUUr8P4U=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=