refactor!: replace LoadFrom and MultiSource with WithSource (#35)

Author: tmzane

README.md

@@ -29,9 +29,8 @@ go get go-simpler.org/env
 
 * Simple API
 * Dependency-free
-* Custom [sources](#source)
 * Per-variable options: [required](#required), [expand](#expand)
-* Global options: [prefix](#prefix), [slice separator](#slice-separator)
+* Global options: [source](#source), [prefix](#prefix), [slice separator](#slice-separator)
 * Auto-generated [usage message](#usage-on-error)
 
 ## 📋 Usage
@@ -105,60 +104,7 @@ fmt.Println(cfg.Host) // localhost
 fmt.Println(cfg.Port) // 8080
 ```
 
-## 🔧 Configuration
-
-### Source
-
-`Load` retrieves environment variables values directly from OS. To use a
-different source, try `LoadFrom` that accepts an implementation of the
-`Source` interface as the first argument.
-
-```go
-// Source represents a source of environment variables.
-type Source interface {
-    // LookupEnv retrieves the value of the environment variable named by the key.
-    LookupEnv(key string) (value string, ok bool)
-}
-```
-
-`Map` is a built-in `Source` implementation that might be useful in tests.
-
-```go
-m := env.Map{"PORT": "8080"}
-
-var cfg struct {
-    Port int `env:"PORT"`
-}
-if err := env.LoadFrom(m, &cfg); err != nil {
-    // handle error
-}
-
-fmt.Println(cfg.Port) // 8080
-```
-
-Multiple sources can be combined into a single one using `MultiSource`. The
-order of the given sources matters: if the same key is found in several
-sources, the value from the last one takes the precedence.
-
-```go
-os.Setenv("HOST", "localhost")
-
-src := env.MultiSource(
-    env.OS,
-    env.Map{"PORT": "8080"},
-)
-
-var cfg struct {
-    Host string `env:"HOST,required"`
-    Port int    `env:"PORT,required"`
-}
-if err := env.LoadFrom(src, &cfg); err != nil {
-    // handle error
-}
-
-fmt.Println(cfg.Host) // localhost
-fmt.Println(cfg.Port) // 8080
-```
+## 🔧 Options
 
 ### Per-variable options
 
@@ -207,8 +153,35 @@ fmt.Println(cfg.Addr) // localhost:8080
 
 ### Global options
 
-In addition to the per-variable options, `env` also supports global options that
-apply to all variables.
+`Load` also accepts global options that apply to all environment variables.
+
+#### Source
+
+By default, `Load` retrieves environment variables values directly from OS.
+To use a different source, provide an implementation of the `Source` interface via the `WithSource` option.
+
+```go
+// Source represents a source of environment variables.
+type Source interface {
+    // LookupEnv retrieves the value of the environment variable named by the key.
+    LookupEnv(key string) (value string, ok bool)
+}
+```
+
+Here's an example of using `Map`, a builtin `Source` implementation useful in tests:
+
+```go
+m := env.Map{"PORT": "8080"}
+
+var cfg struct {
+    Port int `env:"PORT"`
+}
+if err := env.Load(&cfg, env.WithSource(m)); err != nil {
+    // handle error
+}
+
+fmt.Println(cfg.Port) // 8080
+```
 
 #### Prefix
 

env.go

@@ -10,7 +10,6 @@ import (
 )
 
 // Load loads environment variables into the provided struct using the [OS] [Source].
-// To specify a custom [Source], use the [LoadFrom] function.
 // cfg must be a non-nil struct pointer, otherwise Load panics.
 //
 // The struct fields must have the `env:"VAR"` struct tag, where VAR is the name of the corresponding environment variable.
@@ -45,39 +44,39 @@ import (
 //
 // # Global options
 //
-// In addition to the per-variable options, [env] also supports global options that apply to all variables:
-//
-//   - [WithPrefix]: sets prefix for each environment variable
-//   - [WithSliceSeparator]: sets custom separator to parse slice values
-//   - [WithUsageOnError]: enables a usage message printing when an error occurs
-//
-// See their documentation for details.
+// Load also accepts global options that apply to all environment variables, see the With* functions for details.
 func Load(cfg any, opts ...Option) error {
-	return newLoader(OS, opts...).loadVars(cfg)
-}
-
-// LoadFrom loads environment variables into the provided struct using the specified [Source].
-// See [Load] documentation for more details.
-func LoadFrom(src Source, cfg any, opts ...Option) error {
-	return newLoader(src, opts...).loadVars(cfg)
+	return newLoader(opts).loadVars(cfg)
 }
 
-// Option allows to configure the behaviour of the [Load]/[LoadFrom] functions.
+// Option allows to configure the behaviour of the [Load] function.
 type Option func(*loader)
 
-// WithPrefix configures [Load]/[LoadFrom] to automatically add the provided prefix to each environment variable.
+// WithSource configures [Load] to retrieve environment variables from the provided [Source].
+// If multiple sources are provided, they will be merged into a single one containing the union of all environment variables.
+// The order of the sources matters: if the same key occurs more than once, the later value takes precedence.
+// The default source is [OS].
+func WithSource(src Source, srcs ...Source) Option {
+	// reverse the slice first, since the later value should take precedence.
+	for i, j := 0, len(srcs)-1; i < j; i, j = i+1, j-1 {
+		srcs[i], srcs[j] = srcs[j], srcs[i]
+	}
+	return func(l *loader) { l.source = multiSource(append(srcs, src)) }
+}
+
+// WithPrefix configures [Load] to automatically add the provided prefix to each environment variable.
 // By default, no prefix is configured.
 func WithPrefix(prefix string) Option {
 	return func(l *loader) { l.prefix = prefix }
 }
 
-// WithSliceSeparator configures [Load]/[LoadFrom] to use the provided separator when parsing slice values.
-// The default one is space.
+// WithSliceSeparator configures [Load] to use the provided separator when parsing slice values.
+// The default separator is space.
 func WithSliceSeparator(sep string) Option {
 	return func(l *loader) { l.sliceSep = sep }
 }
 
-// WithUsageOnError configures [Load]/[LoadFrom] to write an auto-generated usage message to the provided [io.Writer],
+// 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 {
@@ -102,9 +101,9 @@ type loader struct {
 	usageOutput io.Writer
 }
 
-func newLoader(src Source, opts ...Option) *loader {
+func newLoader(opts []Option) *loader {
 	l := loader{
-		source:      src,
+		source:      OS,
 		prefix:      "",
 		sliceSep:    " ",
 		usageOutput: nil,

env_test.go

@@ -15,12 +15,12 @@ import (
 
 //go:generate go run -tags=copier go-simpler.org/assert/cmd/copier@v0.6.0 internal
 
-func TestLoadFrom(t *testing.T) {
+func TestLoad(t *testing.T) {
 	t.Run("invalid argument", func(t *testing.T) {
-		test := func(name string, dst any) {
+		test := func(name string, cfg any) {
 			t.Run(name, func(t *testing.T) {
 				assert.Panics[E](t,
-					func() { _ = env.LoadFrom(env.Map{}, dst) },
+					func() { _ = env.Load(cfg, env.WithSource(env.Map{})) },
 					"env: argument must be a non-nil struct pointer",
 				)
 			})
@@ -37,7 +37,7 @@ func TestLoadFrom(t *testing.T) {
 			Port string `env:""`
 		}
 		assert.Panics[E](t,
-			func() { _ = env.LoadFrom(env.Map{}, &cfg) },
+			func() { _ = env.Load(&cfg, env.WithSource(env.Map{})) },
 			"env: empty tag name is not allowed",
 		)
 	})
@@ -49,7 +49,7 @@ func TestLoadFrom(t *testing.T) {
 			Port complex64 `env:"PORT"`
 		}
 		assert.Panics[E](t,
-			func() { _ = env.LoadFrom(m, &cfg) },
+			func() { _ = env.Load(&cfg, env.WithSource(m)) },
 			"env: unsupported type `complex64`",
 		)
 	})
@@ -64,7 +64,7 @@ func TestLoadFrom(t *testing.T) {
 			unexported string `env:"UNEXPORTED"`
 			MissingTag string
 		}
-		err := env.LoadFrom(m, &cfg)
+		err := env.Load(&cfg, env.WithSource(m))
 		assert.NoErr[F](t, err)
 		assert.Equal[E](t, cfg.unexported, "")
 		assert.Equal[E](t, cfg.MissingTag, "")
@@ -77,7 +77,7 @@ func TestLoadFrom(t *testing.T) {
 		}{
 			Port: 8000, // must be overridden with 8080 (from the `default` tag).
 		}
-		err := env.LoadFrom(env.Map{}, &cfg)
+		err := env.Load(&cfg, env.WithSource(env.Map{}))
 		assert.NoErr[F](t, err)
 		assert.Equal[E](t, cfg.Host, "localhost")
 		assert.Equal[E](t, cfg.Port, 8080)
@@ -97,7 +97,7 @@ func TestLoadFrom(t *testing.T) {
 				Port int `env:"HTTP_PORT"`
 			}
 		}
-		err := env.LoadFrom(m, &cfg)
+		err := env.Load(&cfg, env.WithSource(m))
 		assert.NoErr[F](t, err)
 		assert.Equal[E](t, cfg.DB.Port, 5432)
 		assert.Equal[E](t, cfg.HTTP.Port, 8080)
@@ -110,7 +110,7 @@ func TestLoadFrom(t *testing.T) {
 			Host string `env:"HOST,required"`
 			Port int    `env:"PORT,required"`
 		}
-		err := env.LoadFrom(env.Map{}, &cfg)
+		err := env.Load(&cfg, env.WithSource(env.Map{}))
 		assert.AsErr[F](t, err, &notSetErr)
 		assert.Equal[E](t, notSetErr.Names, []string{"HOST", "PORT"})
 
@@ -128,7 +128,7 @@ func TestLoadFrom(t *testing.T) {
 		var cfg struct {
 			Addr string `env:"ADDR,expand"`
 		}
-		err := env.LoadFrom(m, &cfg)
+		err := env.Load(&cfg, env.WithSource(m))
 		assert.NoErr[F](t, err)
 		assert.Equal[E](t, cfg.Addr, "localhost:8080")
 	})
@@ -140,18 +140,35 @@ func TestLoadFrom(t *testing.T) {
 			}
 		}
 		assert.Panics[E](t,
-			func() { _ = env.LoadFrom(env.Map{}, &cfg) },
+			func() { _ = env.Load(&cfg, env.WithSource(env.Map{})) },
 			"env: invalid tag option `foo`",
 		)
 	})
 
+	t.Run("with source", func(t *testing.T) {
+		m1 := env.Map{"FOO": "1", "BAR": "2"}
+		m2 := env.Map{"FOO": "2", "BAZ": "3"}
+		m3 := env.Map{"BAR": "3", "BAZ": "4"}
+
+		var cfg struct {
+			Foo int `env:"FOO,required"`
+			Bar int `env:"BAR,required"`
+			Baz int `env:"BAZ,required"`
+		}
+		err := env.Load(&cfg, env.WithSource(m1, m2, m3))
+		assert.NoErr[F](t, err)
+		assert.Equal[E](t, cfg.Foo, 2)
+		assert.Equal[E](t, cfg.Bar, 3)
+		assert.Equal[E](t, cfg.Baz, 4)
+	})
+
 	t.Run("with prefix", func(t *testing.T) {
 		m := env.Map{"APP_PORT": "8080"}
 
 		var cfg struct {
 			Port int `env:"PORT"`
 		}
-		err := env.LoadFrom(m, &cfg, env.WithPrefix("APP_"))
+		err := env.Load(&cfg, env.WithSource(m), env.WithPrefix("APP_"))
 		assert.NoErr[F](t, err)
 		assert.Equal[E](t, cfg.Port, 8080)
 	})
@@ -162,7 +179,7 @@ func TestLoadFrom(t *testing.T) {
 		var cfg struct {
 			Ports []int `env:"PORTS"`
 		}
-		err := env.LoadFrom(m, &cfg, env.WithSliceSeparator(";"))
+		err := env.Load(&cfg, env.WithSource(m), env.WithSliceSeparator(";"))
 		assert.NoErr[F](t, err)
 		assert.Equal[E](t, cfg.Ports, []int{8080, 8081, 8082})
 	})
@@ -179,7 +196,7 @@ func TestLoadFrom(t *testing.T) {
 		var cfg struct {
 			Port int `env:"PORT,required"`
 		}
-		err := env.LoadFrom(env.Map{}, &cfg, env.WithUsageOnError(io.Discard))
+		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)
 	})
@@ -238,7 +255,7 @@ func TestLoadFrom(t *testing.T) {
 			IP        net.IP          `env:"IP"`
 			IPs       []net.IP        `env:"IPS"`
 		}
-		err := env.LoadFrom(m, &cfg)
+		err := env.Load(&cfg, env.WithSource(m))
 		assert.NoErr[F](t, err)
 
 		test := func(name string, got, want any) {
@@ -297,7 +314,7 @@ func TestLoadFrom(t *testing.T) {
 					Unmarshaler net.IP        `env:"UNMARSHALER"`
 					Slice       []net.IP      `env:"SLICE"`
 				}
-				err := env.LoadFrom(m, &cfg)
+				err := env.Load(&cfg, env.WithSource(m))
 				assert.Equal[E](t, checkErr(err), true)
 			})
 		}

example_test.go

@@ -83,37 +83,35 @@ func ExampleLoad_expand() {
 	fmt.Println(cfg.Addr) // localhost:8080
 }
 
-func ExampleLoadFrom() {
+func ExampleWithSource() {
 	m := env.Map{"PORT": "8080"}
 
 	var cfg struct {
 		Port int `env:"PORT"`
 	}
-	if err := env.LoadFrom(m, &cfg); err != nil {
+	if err := env.Load(&cfg, env.WithSource(m)); err != nil {
 		// handle error
 	}
 
 	fmt.Println(cfg.Port) // 8080
 }
 
-func ExampleMultiSource() {
-	os.Setenv("HOST", "localhost")
+func ExampleWithSource_multiple() {
+	m := env.Map{"PORT": "8080"}
 
-	src := env.MultiSource(
-		env.OS,
-		env.Map{"PORT": "8080"},
-	)
+	os.Setenv("HOST", "localhost")
+	os.Setenv("PORT", "8081") // overrides PORT from m.
 
 	var cfg struct {
 		Host string `env:"HOST,required"`
 		Port int    `env:"PORT,required"`
 	}
-	if err := env.LoadFrom(src, &cfg); err != nil {
+	if err := env.Load(&cfg, env.WithSource(m, env.OS)); err != nil {
 		// handle error
 	}
 
 	fmt.Println(cfg.Host) // localhost
-	fmt.Println(cfg.Port) // 8080
+	fmt.Println(cfg.Port) // 8081
 }
 
 func ExampleWithPrefix() {