phase 6: comprehensive tests (93% coverage), examples, README with migration guide

Author: mtingers

README.md

@@ -8,6 +8,115 @@ A Go library that populates struct fields from environment variables. Drop-in re
 go get github.com/agentine/envstruct
 ```
 
+## Quick Start
+
+```go
+package main
+
+import (
+    "fmt"
+    "log"
+
+    "github.com/agentine/envstruct"
+)
+
+type Config struct {
+    Host  string `default:"localhost" desc:"Server hostname"`
+    Port  int    `default:"8080"     desc:"Server port"`
+    Debug bool   `                   desc:"Enable debug mode"`
+}
+
+func main() {
+    var c Config
+    if err := envstruct.Process("APP", &c); err != nil {
+        log.Fatal(err)
+    }
+    fmt.Printf("Listening on %s:%d\n", c.Host, c.Port)
+}
+```
+
+Set environment variables and run:
+
+```
+APP_HOST=0.0.0.0 APP_PORT=9090 go run main.go
+# Listening on 0.0.0.0:9090
+```
+
+## Supported Types
+
+| Type | Example env value |
+|------|-------------------|
+| `string` | `hello` |
+| `bool` | `true`, `false`, `1`, `0` |
+| `int`, `int8`..`int64` | `42`, `-1` |
+| `uint`, `uint8`..`uint64` | `42` |
+| `float32`, `float64` | `3.14` |
+| `time.Duration` | `5s`, `100ms` |
+| `url.URL` / `*url.URL` | `https://example.com` |
+| `[]T` (any scalar T) | `a,b,c` |
+| `map[string]T` | `key1=val1,key2=val2` |
+| Custom `Decoder` | User-defined |
+| Custom `Setter` | envconfig compat |
+| `encoding.TextUnmarshaler` | User-defined |
+
+## Struct Tags
+
+| Tag | Description |
+|-----|-------------|
+| `env:"VAR_NAME"` | Override env var name |
+| `env:"VAR_NAME,required"` | Mark field as required |
+| `env:"-"` | Skip field |
+| `envconfig:"VAR_NAME"` | envconfig compat tag |
+| `default:"value"` | Default if env var unset |
+| `desc:"description"` | Description for Usage() |
+
+## Nested Structs
+
+Nested struct fields are flattened with `_` separators:
+
+```go
+type DB struct {
+    Host string
+    Port int
+}
+type Config struct {
+    Database DB
+}
+// Reads APP_DATABASE_HOST, APP_DATABASE_PORT
+```
+
+Embedded structs are flattened without adding a prefix segment.
+
+## Usage Text
+
+```go
+envstruct.Usage("APP", &Config{}, os.Stderr)
+```
+
+Outputs:
+
+```
+  APP_HOST   string  [default: localhost]  Server hostname
+  APP_PORT   int     [default: 8080]       Server port
+  APP_DEBUG  bool                          Enable debug mode
+```
+
+## Migration from envconfig
+
+envstruct is a drop-in replacement. The function signatures are identical:
+
+```go
+// Before
+envconfig.Process("APP", &config)
+envconfig.MustProcess("APP", &config)
+
+// After
+envstruct.Process("APP", &config)
+envstruct.MustProcess("APP", &config)
+```
+
+Both `env` and `envconfig` struct tags are supported for smooth migration.
+
 ## License
 
 MIT

decoder_test.go

@@ -358,3 +358,98 @@ func TestDecodeBoolParseError(t *testing.T) {
 		t.Fatalf("expected ParseError, got %T", err)
 	}
 }
+
+type testTextUnmarshaler struct{ val string }
+
+func (u *testTextUnmarshaler) UnmarshalText(text []byte) error {
+	u.val = "unmarshaled:" + string(text)
+	return nil
+}
+
+func TestDecodeTextUnmarshaler(t *testing.T) {
+	type C struct{ TU testTextUnmarshaler }
+	t.Setenv("TU", "hello")
+	var c C
+	if err := Process("", &c); err != nil {
+		t.Fatal(err)
+	}
+	if c.TU.val != "unmarshaled:hello" {
+		t.Fatalf("got %q", c.TU.val)
+	}
+}
+
+func TestParseErrorString(t *testing.T) {
+	pe := &ParseError{
+		FieldName: "Port",
+		EnvVar:    "APP_PORT",
+		Value:     "abc",
+		TypeName:  "int",
+		Err:       errors.New("invalid syntax"),
+	}
+	s := pe.Error()
+	if s == "" {
+		t.Fatal("empty error string")
+	}
+	if pe.Unwrap() == nil {
+		t.Fatal("expected non-nil unwrap")
+	}
+}
+
+func TestRequiredErrorString(t *testing.T) {
+	re := &RequiredError{
+		FieldName: "Host",
+		EnvVar:    "APP_HOST",
+	}
+	s := re.Error()
+	if s == "" {
+		t.Fatal("empty error string")
+	}
+}
+
+func TestDecodeMapBadFormat(t *testing.T) {
+	type C struct{ Labels map[string]string }
+	t.Setenv("LABELS", "noequals")
+	var c C
+	err := Process("", &c)
+	if err == nil {
+		t.Fatal("expected error for bad map format")
+	}
+}
+
+func TestDecodeFloatParseError(t *testing.T) {
+	type C struct{ Val float64 }
+	t.Setenv("VAL", "not-a-float")
+	var c C
+	err := Process("", &c)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+}
+
+func TestDecodeUintParseError(t *testing.T) {
+	type C struct{ Val uint }
+	t.Setenv("VAL", "-1")
+	var c C
+	err := Process("", &c)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+}
+
+func TestDecodeDurationParseError(t *testing.T) {
+	type C struct{ Val time.Duration }
+	t.Setenv("VAL", "not-a-duration")
+	var c C
+	err := Process("", &c)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+}
+
+func TestProcessNonStructPointer(t *testing.T) {
+	s := "hello"
+	err := Process("", &s)
+	if err == nil {
+		t.Fatal("expected error for non-struct pointer")
+	}
+}

example_test.go

@@ -2,11 +2,17 @@ package envstruct_test
 
 import (
 	"fmt"
+	"os"
 
 	"github.com/agentine/envstruct"
 )
 
 func ExampleProcess() {
+	os.Setenv("APP_HOST", "localhost")
+	os.Setenv("APP_PORT", "8080")
+	defer os.Unsetenv("APP_HOST")
+	defer os.Unsetenv("APP_PORT")
+
 	type Config struct {
 		Host string
 		Port int
@@ -17,6 +23,56 @@ func ExampleProcess() {
 		fmt.Println("error:", err)
 		return
 	}
-	fmt.Println("ok")
-	// Output: ok
+	fmt.Printf("Host=%s Port=%d\n", c.Host, c.Port)
+	// Output: Host=localhost Port=8080
+}
+
+func ExampleProcess_nested() {
+	os.Setenv("APP_DATABASE_HOST", "db.local")
+	os.Setenv("APP_DATABASE_PORT", "5432")
+	defer os.Unsetenv("APP_DATABASE_HOST")
+	defer os.Unsetenv("APP_DATABASE_PORT")
+
+	type DB struct {
+		Host string
+		Port int
+	}
+	type Config struct {
+		Database DB
+	}
+	var c Config
+	err := envstruct.Process("APP", &c)
+	if err != nil {
+		fmt.Println("error:", err)
+		return
+	}
+	fmt.Printf("DB=%s:%d\n", c.Database.Host, c.Database.Port)
+	// Output: DB=db.local:5432
+}
+
+func ExampleProcess_required() {
+	type Config struct {
+		Secret string `env:"SECRET,required"`
+	}
+	var c Config
+	err := envstruct.Process("APP", &c)
+	if err != nil {
+		fmt.Println("got expected error")
+		return
+	}
+	fmt.Println("unexpected success")
+	// Output: got expected error
+}
+
+func ExampleUsage() {
+	type Config struct {
+		Host  string `default:"localhost" desc:"Server hostname"`
+		Port  int    `default:"8080" desc:"Server port"`
+		Debug bool   `desc:"Enable debug mode"`
+	}
+	envstruct.Usage("APP", &Config{}, os.Stdout)
+	// Output:
+	//   APP_HOST   string  [default: localhost]  Server hostname
+	//   APP_PORT   int     [default: 8080]       Server port
+	//   APP_DEBUG  bool                          Enable debug mode
 }