feat: ParseAs, ParseAsWithOptions, Must (#300)

* feat: ParseAs, ParseAsWithOptions, Must

closes #299

Signed-off-by: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>

* build: build with go 1.17 as well

Signed-off-by: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>

* feat: change min go version to 1.18

Signed-off-by: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>

---------

Signed-off-by: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>

Author: caarlos0

.github/workflows/build.yml

@@ -3,9 +3,9 @@ name: build
 on:
   push:
     branches:
-      - 'main'
+      - "main"
     tags:
-      - 'v*'
+      - "v*"
   pull_request:
 
 jobs:
@@ -18,8 +18,8 @@ jobs:
   build:
     strategy:
       matrix:
-        os: [ ubuntu-latest, macos-latest, windows-latest ]
-        go-version: [ oldstable, stable]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        go-version: [1.18, oldstable, stable]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4

env.go

@@ -191,6 +191,28 @@ func ParseWithOptions(v interface{}, opts Options) error {
 	return parseInternal(v, setField, customOptions(opts))
 }
 
+// ParseAs parses the given struct type containing `env` tags and loads its
+// values from environment variables.
+func ParseAs[T any]() (T, error) {
+	var t T
+	return t, Parse(&t)
+}
+
+// ParseWithOptions parses the given struct type containing `env` tags and
+// loads its values from environment variables.
+func ParseAsWithOptions[T any](opts Options) (T, error) {
+	var t T
+	return t, ParseWithOptions(&t, opts)
+}
+
+// Must panic is if err is not nil, and returns t otherwise.
+func Must[T any](t T, err error) T {
+	if err != nil {
+		panic(err)
+	}
+	return t
+}
+
 // GetFieldParams parses a struct containing `env` tags and returns information about
 // tags it found.
 func GetFieldParams(v interface{}) ([]FieldParams, error) {

env_test.go

@@ -1854,6 +1854,46 @@ func TestGetFieldParamsError(t *testing.T) {
 	isTrue(t, errors.Is(err, NotStructPtrError{}))
 }
 
+type Conf struct {
+	Foo string `env:"FOO" envDefault:"bar"`
+}
+
+func TestParseAs(t *testing.T) {
+	config, err := ParseAs[Conf]()
+	isNoErr(t, err)
+	isEqual(t, "bar", config.Foo)
+}
+
+func TestParseAsWithOptions(t *testing.T) {
+	config, err := ParseAsWithOptions[Conf](Options{
+		Environment: map[string]string{
+			"FOO": "not bar",
+		},
+	})
+	isNoErr(t, err)
+	isEqual(t, "not bar", config.Foo)
+}
+
+type ConfRequired struct {
+	Foo string `env:"FOO,required"`
+}
+
+func TestMust(t *testing.T) {
+	t.Run("error", func(t *testing.T) {
+		defer func() {
+			err := recover()
+			isErrorWithMessage(t, err.(error), `env: required environment variable "FOO" is not set`)
+		}()
+		conf := Must(ParseAs[ConfRequired]())
+		isEqual(t, "", conf.Foo)
+	})
+	t.Run("success", func(t *testing.T) {
+		t.Setenv("FOO", "bar")
+		conf := Must(ParseAs[ConfRequired]())
+		isEqual(t, "bar", conf.Foo)
+	})
+}
+
 func isTrue(tb testing.TB, b bool) {
 	tb.Helper()
 

go.mod

@@ -1,3 +1,3 @@
 module github.com/caarlos0/env/v10
 
-go 1.17
+go 1.18