docs: more examples

caarlos0 · Aug 7, 2024 · 19de57d · 19de57d
1 parent d7efb64
commit 19de57d
Show file tree

Hide file tree

Showing 2 changed files with 143 additions and 64 deletions.
diff --git a/env_examples_test.go b/env_examples_test.go
@@ -0,0 +1,143 @@
+package env
+
+import (
+	"fmt"
+	"log"
+	"os"
+)
+
+func ExampleParse() {
+	type Config struct {
+		Home string `env:"HOME"`
+	}
+	os.Setenv("HOME", "/tmp/fakehome")
+	var cfg Config
+	if err := Parse(&cfg); err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("%+v", cfg)
+	// Output:  {Home:/tmp/fakehome}
+}
+
+func ExampleParseAs() {
+	type Config struct {
+		Home string `env:"HOME"`
+	}
+	os.Setenv("HOME", "/tmp/fakehome")
+	cfg, err := ParseAs[Config]()
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("%+v", cfg)
+	// Output:  {Home:/tmp/fakehome}
+}
+
+func ExampleParse_required() {
+	type Config struct {
+		Nope string `env:"NOPE,required"`
+	}
+	var cfg Config
+	if err := Parse(&cfg); err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("%+v", cfg)
+	// Output: env: required environment variable "NOPE" is not set
+	// {Nope:}
+}
+
+func ExampleParse_notEmpty() {
+	type Config struct {
+		Nope string `env:"NOPE,notEmpty"`
+	}
+	os.Setenv("NOPE", "")
+	var cfg Config
+	if err := Parse(&cfg); err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("%+v", cfg)
+	// Output: env: environment variable "NOPE" should not be empty
+	// {Nope:}
+}
+
+func ExampleParse_unset() {
+	type Config struct {
+		Secret string `env:"SECRET,unset"`
+	}
+	os.Setenv("SECRET", "1234")
+	var cfg Config
+	if err := Parse(&cfg); err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("%+v - %s", cfg, os.Getenv("SECRET"))
+	// Output: {Secret:1234} -
+}
+
+func ExampleParse_expand() {
+	type Config struct {
+		Expand1 string `env:"EXPAND_1,expand"`
+		Expand2 string `env:"EXPAND_2,expand" envDefault:"ABC_${EXPAND_1}"`
+	}
+	os.Setenv("EXPANDING", "HI")
+	os.Setenv("EXPAND_1", "HELLO_${EXPANDING}")
+	var cfg Config
+	if err := Parse(&cfg); err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("%+v", cfg)
+	// Output: {Expand1:HELLO_HI Expand2:ABC_HELLO_HI}
+}
+
+func ExampleParse_init() {
+	type Inner struct {
+		A string `env:"OLA" envDefault:"HI"`
+	}
+	type Config struct {
+		NilInner  *Inner
+		InitInner *Inner `env:",init"`
+	}
+	var cfg Config
+	if err := Parse(&cfg); err != nil {
+		log.Fatal(err)
+	}
+	fmt.Print(cfg.NilInner, cfg.InitInner)
+	// Output: <nil> &{HI}
+}
+
+func ExampleParse_setDefaults() {
+	type Config struct {
+		Foo string `env:"FOO"`
+		Bar string `env:"BAR" envDefault:"bar"`
+	}
+	cfg := Config{
+		Foo: "foo",
+	}
+	if err := Parse(&cfg); err != nil {
+		fmt.Println(err)
+	}
+	fmt.Printf("%+v", cfg)
+	// Output: {Foo:foo Bar:bar}
+}
+
+func ExampleParse_onSet() {
+	type config struct {
+		Home         string `env:"HOME,required"`
+		Port         int    `env:"PORT" envDefault:"3000"`
+		IsProduction bool   `env:"PRODUCTION"`
+		NoEnvTag     bool
+		Inner        struct{} `envPrefix:"INNER_"`
+	}
+	os.Setenv("HOME", "/tmp/fakehome")
+	var cfg config
+	if err := ParseWithOptions(&cfg, Options{
+		OnSet: func(tag string, value interface{}, isDefault bool) {
+			fmt.Printf("Set %s to %v (default? %v)\n", tag, value, isDefault)
+		},
+	}); err != nil {
+		fmt.Println("failed:", err)
+	}
+	fmt.Printf("%+v", cfg)
+	// Output: Set HOME to /tmp/fakehome (default? false)
+	// Set PORT to 3000 (default? true)
+	// Set PRODUCTION to  (default? false)
+	// {Home:/tmp/fakehome Port:3000 IsProduction:false NoEnvTag:false Inner:{}}
+}
diff --git a/env_test.go b/env_test.go
@@ -1354,70 +1354,6 @@ func TestParseInvalidURL(t *testing.T) {
 	isTrue(t, errors.Is(err, ParseError{}))
 }
 
-func ExampleParse() {
-	type inner struct {
-		Foo string `env:"FOO" envDefault:"foobar"`
-	}
-	type config struct {
-		Home         string         `env:"HOME,required"`
-		Port         int            `env:"PORT" envDefault:"3000"`
-		IsProduction bool           `env:"PRODUCTION"`
-		TempFolder   string         `env:"TEMP_FOLDER,expand" envDefault:"${HOME}/.tmp"`
-		StringInts   map[string]int `env:"MAP_STRING_INT" envDefault:"k1:1,k2:2"`
-		Inner        inner
-	}
-	os.Setenv("HOME", "/tmp/fakehome")
-	var cfg config
-	if err := Parse(&cfg); err != nil {
-		fmt.Println("failed:", err)
-	}
-	fmt.Printf("%+v", cfg)
-	// Output:  {Home:/tmp/fakehome Port:3000 IsProduction:false TempFolder:/tmp/fakehome/.tmp StringInts:map[k1:1 k2:2] Inner:{Foo:foobar}}
-}
-
-func ExampleParse_onSet() {
-	type config struct {
-		Home         string `env:"HOME,required"`
-		Port         int    `env:"PORT" envDefault:"3000"`
-		IsProduction bool   `env:"PRODUCTION"`
-		NoEnvTag     bool
-		Inner        struct{} `envPrefix:"INNER_"`
-	}
-	os.Setenv("HOME", "/tmp/fakehome")
-	var cfg config
-	if err := ParseWithOptions(&cfg, Options{
-		OnSet: func(tag string, value interface{}, isDefault bool) {
-			fmt.Printf("Set %s to %v (default? %v)\n", tag, value, isDefault)
-		},
-	}); err != nil {
-		fmt.Println("failed:", err)
-	}
-	fmt.Printf("%+v", cfg)
-	// Output: Set HOME to /tmp/fakehome (default? false)
-	// Set PORT to 3000 (default? true)
-	// Set PRODUCTION to  (default? false)
-	// {Home:/tmp/fakehome Port:3000 IsProduction:false NoEnvTag:false Inner:{}}
-}
-
-func ExampleParse_defaults() {
-	type config struct {
-		A string `env:"FOO" envDefault:"foo"`
-		B string `env:"FOO"`
-	}
-
-	// env FOO is not set
-
-	cfg := config{
-		A: "A",
-		B: "B",
-	}
-	if err := Parse(&cfg); err != nil {
-		fmt.Println("failed:", err)
-	}
-	fmt.Printf("%+v", cfg)
-	// Output: {A:foo B:B}
-}
-
 func TestIgnoresUnexported(t *testing.T) {
 	type unexportedConfig struct {
 		home  string `env:"HOME"`