refactor!: reimplement Usage as a separate function (#33)

Author: tmzane

README.md

@@ -31,7 +31,7 @@ go get go-simpler.org/env
 * Dependency-free
 * Per-variable options: [required](#required), [expand](#expand)
 * Global options: [source](#source), [prefix](#prefix), [slice separator](#slice-separator)
-* Auto-generated [usage message](#usage-on-error)
+* Auto-generated [usage message](#usage-message)
 
 ## 📋 Usage
 
@@ -48,10 +48,11 @@ var cfg struct {
     Port int `env:"PORT"`
 }
 if err := env.Load(&cfg); err != nil {
-    // handle error
+    fmt.Println(err)
 }
 
-fmt.Println(cfg.Port) // 8080
+fmt.Println(cfg.Port)
+// Output: 8080
 ```
 
 ### Supported types
@@ -78,34 +79,31 @@ var cfg struct {
     }
 }
 if err := env.Load(&cfg); err != nil {
-    // handle error
+    fmt.Println(err)
 }
 
-fmt.Println(cfg.HTTP.Port) // 8080
+fmt.Println(cfg.HTTP.Port)
+// Output: 8080
 ```
 
 ### Default values
 
-Default values can be specified either using the `default` struct tag (has a
-higher priority) or by initializing the struct fields directly.
+Default values can be specified using the `default` struct tag:
 
 ```go
-cfg := struct {
-    Host string `env:"HOST" default:"localhost"` // either use the `default` tag...
-    Port int    `env:"PORT"`
-}{
-    Port: 8080, // ...or initialize the struct field directly.
+os.Unsetenv("PORT")
+
+var cfg struct {
+    Port int `env:"PORT" default:"8080"`
 }
 if err := env.Load(&cfg); err != nil {
-    // handle error
+    fmt.Println(err)
 }
 
-fmt.Println(cfg.Host) // localhost
-fmt.Println(cfg.Port) // 8080
+fmt.Println(cfg.Port)
+// Output: 8080
 ```
 
-## 🔧 Options
-
 ### Per-variable options
 
 The name of the environment variable can be followed by comma-separated options
@@ -117,8 +115,8 @@ Use the `required` option to mark the environment variable as required. In case
 no such variable is found, an error of type `NotSetError` will be returned.
 
 ```go
-// os.Setenv("HOST", "localhost")
-// os.Setenv("PORT", "8080")
+os.Unsetenv("HOST")
+os.Unsetenv("PORT")
 
 var cfg struct {
     Host string `env:"HOST,required"`
@@ -127,9 +125,11 @@ var cfg struct {
 if err := env.Load(&cfg); err != nil {
     var notSetErr *env.NotSetError
     if errors.As(err, &notSetErr) {
-        fmt.Println(notSetErr.Names) // [HOST PORT]
+        fmt.Println(notSetErr.Names)
     }
 }
+
+// Output: [HOST PORT]
 ```
 
 #### Expand
@@ -142,13 +142,14 @@ os.Setenv("PORT", "8080")
 os.Setenv("ADDR", "localhost:${PORT}")
 
 var cfg struct {
-	Addr string `env:"ADDR,expand"`
+    Addr string `env:"ADDR,expand"`
 }
 if err := env.Load(&cfg); err != nil {
-	// handle error
+    fmt.Println(err)
 }
 
-fmt.Println(cfg.Addr) // localhost:8080
+fmt.Println(cfg.Addr)
+// Output: localhost:8080
 ```
 
 ### Global options
@@ -177,10 +178,11 @@ var cfg struct {
     Port int `env:"PORT"`
 }
 if err := env.Load(&cfg, env.WithSource(m)); err != nil {
-    // handle error
+    fmt.Println(err)
 }
 
-fmt.Println(cfg.Port) // 8080
+fmt.Println(cfg.Port)
+// Output: 8080
 ```
 
 #### Prefix
@@ -195,10 +197,11 @@ var cfg struct {
     Port int `env:"PORT"`
 }
 if err := env.Load(&cfg, env.WithPrefix("APP_")); err != nil {
-    // handle error
+    fmt.Println(err)
 }
 
-fmt.Println(cfg.Port) // 8080
+fmt.Println(cfg.Port)
+// Output: 8080
 ```
 
 #### Slice separator
@@ -213,45 +216,35 @@ var cfg struct {
     Ports []int `env:"PORTS"`
 }
 if err := env.Load(&cfg, env.WithSliceSeparator(";")); err != nil {
-    // handle error
+    fmt.Println(err)
 }
 
-fmt.Println(cfg.Ports[0]) // 8080
-fmt.Println(cfg.Ports[1]) // 8081
-fmt.Println(cfg.Ports[2]) // 8082
+fmt.Println(cfg.Ports)
+// Output: [8080 8081 8082]
 ```
 
-#### Usage on error
+### Usage message
 
-`env` supports printing an auto-generated usage message the same way the `flag`
-package does it. It will be printed if the `WithUsageOnError` option is
-provided and an error occurs while loading environment variables:
+`env` supports printing an auto-generated usage message the same way the `flag` package does it.
 
 ```go
-// os.Setenv("DB_HOST", "localhost")
-// os.Setenv("DB_PORT", "5432")
-
-cfg := struct {
+var cfg struct {
     DB struct {
         Host string `env:"DB_HOST,required" desc:"database host"`
         Port int    `env:"DB_PORT,required" desc:"database port"`
     }
-    HTTPPort int             `env:"HTTP_PORT" desc:"http server port"`
-    Timeouts []time.Duration `env:"TIMEOUTS" desc:"timeout steps"`
-}{
-    HTTPPort: 8080,
-    Timeouts: []time.Duration{1 * time.Second, 2 * time.Second, 3 * time.Second},
+    HTTPPort int `env:"HTTP_PORT" default:"8080" desc:"http server port"`
 }
-if err := env.Load(&cfg, env.WithUsageOnError(os.Stdout)); err != nil {
-    // handle error
+if err := env.Load(&cfg); err != nil {
+    fmt.Println(err)
+    env.Usage(&cfg, os.Stdout)
 }
 
-// Output:
+// Output: env: [DB_HOST DB_PORT] are required but not set
 // Usage:
-//   DB_HOST    string           required            database host
-//   DB_PORT    int              required            database port
-//   HTTP_PORT  int              default 8080        http server port
-//   TIMEOUTS   []time.Duration  default [1s 2s 3s]  timeout steps
+//   DB_HOST    string  required      database host
+//   DB_PORT    int     required      database port
+//   HTTP_PORT  int     default 8080  http server port
 ```
 
 [1]: https://12factor.net/config

env.go

@@ -3,7 +3,6 @@ package env
 
 import (
 	"fmt"
-	"io"
 	"os"
 	"reflect"
 	"strings"
@@ -76,13 +75,6 @@ func WithSliceSeparator(sep string) Option {
 	return func(l *loader) { l.sliceSep = sep }
 }
 
-// WithUsageOnError configures [Load] to write an auto-generated usage message to the provided [io.Writer],
-// if an error occurs while loading environment variables.
-// The message format can be changed by assigning the global [Usage] variable to a custom implementation.
-func WithUsageOnError(w io.Writer) Option {
-	return func(l *loader) { l.usageOutput = w }
-}
-
 // NotSetError is returned when environment variables are marked as required but not set.
 type NotSetError struct {
 	// Names is a slice of the names of the missing required environment variables.
@@ -95,37 +87,30 @@ func (e *NotSetError) Error() string {
 }
 
 type loader struct {
-	source      Source
-	prefix      string
-	sliceSep    string
-	usageOutput io.Writer
+	source   Source
+	prefix   string
+	sliceSep string
 }
 
 func newLoader(opts []Option) *loader {
 	l := loader{
-		source:      OS,
-		prefix:      "",
-		sliceSep:    " ",
-		usageOutput: nil,
+		source:   OS,
+		prefix:   "",
+		sliceSep: " ",
 	}
 	for _, opt := range opts {
 		opt(&l)
 	}
 	return &l
 }
 
-func (l *loader) loadVars(cfg any) (err error) {
+func (l *loader) loadVars(cfg any) error {
 	v := reflect.ValueOf(cfg)
 	if !structPtr(v) {
-		panic("env: argument must be a non-nil struct pointer")
+		panic("env: cfg must be a non-nil struct pointer")
 	}
 
 	vars := l.parseVars(v.Elem())
-	defer func() {
-		if err != nil && l.usageOutput != nil {
-			Usage(l.usageOutput, vars)
-		}
-	}()
 
 	// accumulate missing required variables to return NotSetError after the loop is finished.
 	var notset []string
@@ -142,6 +127,7 @@ func (l *loader) loadVars(cfg any) (err error) {
 			value = v.Default
 		}
 
+		var err error
 		if kindOf(v.field, reflect.Slice) && !implements(v.field, unmarshalerIface) {
 			err = setSlice(v.field, strings.Split(value, l.sliceSep))
 		} else {

env_test.go

@@ -19,10 +19,9 @@ func TestLoad(t *testing.T) {
 	t.Run("invalid argument", func(t *testing.T) {
 		test := func(name string, cfg any) {
 			t.Run(name, func(t *testing.T) {
-				assert.Panics[E](t,
-					func() { _ = env.Load(cfg, env.WithSource(env.Map{})) },
-					"env: argument must be a non-nil struct pointer",
-				)
+				const v = "env: cfg must be a non-nil struct pointer"
+				assert.Panics[E](t, func() { _ = env.Load(cfg, env.WithSource(env.Map{})) }, v)
+				assert.Panics[E](t, func() { env.Usage(cfg, io.Discard) }, v)
 			})
 		}
 
@@ -184,23 +183,6 @@ func TestLoad(t *testing.T) {
 		assert.Equal[E](t, cfg.Ports, []int{8080, 8081, 8082})
 	})
 
-	t.Run("with usage on error", func(t *testing.T) {
-		usage := env.Usage
-		defer func() { env.Usage = usage }()
-
-		var called bool
-		env.Usage = func(w io.Writer, vars []env.Var) {
-			called = true
-		}
-
-		var cfg struct {
-			Port int `env:"PORT,required"`
-		}
-		err := env.Load(&cfg, env.WithSource(env.Map{}), env.WithUsageOnError(io.Discard))
-		assert.AsErr[F](t, err, new(*env.NotSetError))
-		assert.Equal[E](t, called, true)
-	})
-
 	t.Run("all supported types", func(t *testing.T) {
 		m := env.Map{
 			"INT": "-1", "INTS": "-1 0",