feat: Implement Env generic function that returns error (#95)

* feat: Implement Env generic function that returns error

* chore: Refactor makefile

* docs: Update README

* chore: Fix linter warings

* chore: Fix sonar bugs

* docs: Update README

Author: obalunenko

Makefile

@@ -1,3 +1,4 @@
+.PHONY: help, test-cover, prepare-cover-report, open-cover-report, update-readme-cover, update-readme-doc, test, test-regression, configure, sync-vendor, imports, fmt, format-project, install-tools, vet, lint-full, lint-pipeline, lint-sonar, release, release-local-snapshot, check-releaser, new-version
 BIN_DIR=./bin
 
 SHELL := env VERSION=$(VERSION) $(SHELL)
@@ -38,103 +39,84 @@ help:
 ## Test coverage report.
 test-cover:
 	./scripts/tests/coverage.sh
-.PHONY: test-cover
 
 prepare-cover-report: test-cover
 	$(COMPOSE_TOOLS_CMD_UP) prepare-cover-report prepare-cover-report
-.PHONY: prepare-cover-report
 
 ## Open coverage report.
 open-cover-report: prepare-cover-report
 	./scripts/open-coverage-report.sh
-.PHONY: open-cover-report
 
 ## Update readme coverage.
 update-readme-cover: prepare-cover-report
 	$(COMPOSE_TOOLS_CMD_UP) update-readme-coverage update-readme-coverage
-.PHONY: update-readme-cover
 
 ## Update readme doc.
 update-readme-doc:
 	$(COMPOSE_TOOLS_CMD_UP) update-readme-doc update-readme-doc
-.PHONY: update-readme-doc
 
 ## Run tests.
 test:
 	$(COMPOSE_TOOLS_CMD_UP) run-tests run-tests
-.PHONY: test
 
 ## Run regression tests.
 test-regression: test
-.PHONY: test-regression
 
 ## Sync vendor and install needed tools.
 configure: sync-vendor install-tools
 
 ## Sync vendor with go.mod.
 sync-vendor:
 	./scripts/sync-vendor.sh
-.PHONY: sync-vendor
 
 ## Fix imports sorting.
 imports:
 	$(COMPOSE_TOOLS_CMD_UP) fix-imports fix-imports
-.PHONY: imports
 
 ## Format code with go fmt.
 fmt:
 	$(COMPOSE_TOOLS_CMD_UP) fix-fmt fix-fmt
-.PHONY: fmt
 
 ## Format code and sort imports.
 format-project: fmt imports
-.PHONY: format-project
 
 ## Installs vendored tools.
 install-tools:
 	echo "Installing ${GOTOOLS_IMAGE_TAG}"
 	$(COMPOSE_TOOLS_CMD_PULL)
-.PHONY: install-tools
 
 ## vet project
 vet:
 	./scripts/linting/run-vet.sh
-.PHONY: vet
 
 ## Run full linting
 lint-full:
 	$(COMPOSE_TOOLS_CMD_UP) lint-full lint-full
-.PHONY: lint-full
 
 ## Run linting for build pipeline
 lint-pipeline:
 	$(COMPOSE_TOOLS_CMD_UP) lint-pipeline lint-pipeline
-.PHONY: lint-pipeline
 
 ## Run linting for sonar report
 lint-sonar:
 	$(COMPOSE_TOOLS_CMD_UP) lint-sonar lint-sonar
-.PHONY: lint-sonar
 
 ## Release
 release:
 	./scripts/release/release.sh
-.PHONY: release
 
 ## Release local snapshot
 release-local-snapshot:
 	./scripts/release/local-snapshot-release.sh
-.PHONY: release-local-snapshot
 
 ## Check goreleaser config.
 check-releaser:
 	./scripts/release/check.sh
-.PHONY: check-releaser
 
 ## Issue new release.
 new-version: vet test-regression
 	./scripts/release/new-version.sh
-.PHONY: new-release
+
 
 .DEFAULT_GOAL := help
 

README.md

@@ -56,6 +56,150 @@ Types supported:
 
 ## Examples
 
+### Env
+
+Env retrieves the value of the environment variable named by the key.
+If the variable is present in the environment the value will be parsed and returned.
+Otherwise, an error will be returned.
+
+```golang
+package main
+
+import (
+	"fmt"
+	"net"
+	"net/url"
+	"os"
+	"time"
+
+	"github.com/obalunenko/getenv"
+	"github.com/obalunenko/getenv/option"
+)
+
+func main() {
+	const (
+		key = "GH_GETENV_TEST"
+	)
+
+	var (
+		val any
+		err error
+	)
+
+	defer func() {
+		if err = os.Unsetenv(key); err != nil {
+			panic(err)
+		}
+	}()
+
+	// string
+	if err = os.Setenv(key, "golly"); err != nil {
+		panic(err)
+	}
+
+	val, err = getenv.Env[string](key)
+	fmt.Printf("[%T]: %v; err: %v\n", val, val, err)
+
+	// int
+	if err = os.Setenv(key, "123"); err != nil {
+		panic(err)
+	}
+
+	val, err = getenv.Env[int](key)
+	fmt.Printf("[%T]: %v; err: %v\n", val, val, err)
+
+	// int conversion error
+	if err = os.Setenv(key, "123s4"); err != nil {
+		panic(err)
+	}
+
+	val, err = getenv.Env[int](key)
+	fmt.Printf("[%T]: %v; err: %v\n", val, val, err)
+
+	// time.Time
+	if err = os.Setenv(key, "2022-01-20"); err != nil {
+		panic(err)
+	}
+
+	val, err = getenv.Env[time.Time](key, option.WithTimeLayout("2006-01-02"))
+	fmt.Printf("[%T]: %v; err: %v\n", val, val, err)
+
+	// []float64
+	if err = os.Setenv(key, "26.89,0.67"); err != nil {
+		panic(err)
+	}
+
+	val, err = getenv.Env[[]float64](key, option.WithSeparator(","))
+	fmt.Printf("[%T]: %v; err: %v\n", val, val, err)
+
+	// time.Duration
+	if err = os.Setenv(key, "2h35m"); err != nil {
+		panic(err)
+	}
+
+	val, err = getenv.Env[time.Duration](key)
+	fmt.Printf("[%T]: %v; err: %v\n", val, val, err)
+
+	// url.URL
+	if err = os.Setenv(key, "https://test:abcd123@golangbyexample.com:8000/tutorials/intro?type=advance&compact=false#history"); err != nil {
+		panic(err)
+	}
+
+	val, err = getenv.Env[url.URL](key)
+	fmt.Printf("[%T]: %v; err: %v\n", val, val, err)
+
+	// net.IP
+	if err = os.Setenv(key, "2001:cb8::17"); err != nil {
+		panic(err)
+	}
+
+	val, err = getenv.Env[net.IP](key)
+	fmt.Printf("[%T]: %v; err: %v\n", val, val, err)
+
+	// []string
+	if err = os.Setenv(key, "a,b,c,d"); err != nil {
+		panic(err)
+	}
+
+	val, err = getenv.Env[[]string](key, option.WithSeparator(","))
+	fmt.Printf("[%T]: %v; err: %v\n", val, val, err)
+
+	// complex128
+	if err = os.Setenv(key, "1+2i"); err != nil {
+		panic(err)
+	}
+
+	val, err = getenv.Env[complex128](key)
+	fmt.Printf("[%T]: %v; err: %v\n", val, val, err)
+
+	// []complex64
+	if err = os.Setenv(key, "1+2i,3+4i"); err != nil {
+		panic(err)
+	}
+
+	val, err = getenv.Env[[]complex64](key, option.WithSeparator(","))
+	fmt.Printf("[%T]: %v; err: %v\n", val, val, err)
+
+}
+
+```
+
+Output:
+
+```
+[string]: golly; err: <nil>
+[int]: 123; err: <nil>
+[int]: 0; err: could not parse variable[GH_GETENV_TEST] value[123s4] to type[int]: invalid value
+[time.Time]: 2022-01-20 00:00:00 +0000 UTC; err: <nil>
+[[]float64]: [26.89 0.67]; err: <nil>
+[time.Duration]: 2h35m0s; err: <nil>
+[url.URL]: {https  test:abcd123 golangbyexample.com:8000 /tutorials/intro  false false type=advance&compact=false history }; err: <nil>
+[net.IP]: 2001:cb8::17; err: <nil>
+[[]string]: [a b c d]; err: <nil>
+[complex128]: (1+2i); err: <nil>
+[[]complex64]: [(1+2i) (3+4i)]; err: <nil>
+```
+
 ### EnvOrDefault
 
 EnvOrDefault retrieves the value of the environment variable named by the key.
@@ -78,10 +222,12 @@ import (
 )
 
 func main() {
-	key := "GH_GETENV_TEST"
+	const (
+		key = "GH_GETENV_TEST"
+	)
 
 	defer func() {
-		if err := os.Unsetenv("GH_GETENV_TEST"); err != nil {
+		if err := os.Unsetenv(key); err != nil {
 			panic(err)
 		}
 	}()

getenv.go

@@ -47,10 +47,45 @@
 package getenv
 
 import (
+	"errors"
+	"fmt"
+	"os"
+	"reflect"
+
 	"github.com/obalunenko/getenv/internal"
 	"github.com/obalunenko/getenv/option"
 )
 
+var (
+	// ErrNotSet is an error that is returned when the environment variable is not set.
+	ErrNotSet = errors.New("not set")
+	// ErrInvalidValue is an error that is returned when the environment variable is not valid.
+	ErrInvalidValue = errors.New("invalid value")
+)
+
+// Env retrieves the value of the environment variable named by the key.
+// If the variable is present in the environment the value will be parsed and returned.
+// Otherwise, an error will be returned.
+func Env[T internal.EnvParsable](key string, options ...option.Option) (T, error) {
+	// Create a default value of the same type as the value that we want to get.
+	var defVal T
+
+	val := EnvOrDefault(key, defVal, options...)
+
+	// If the value is equal to the default value, it means that the value was not parsed.
+	// This means that the environment variable was not set, or it was set to an invalid value.
+	if reflect.DeepEqual(val, defVal) {
+		v, ok := os.LookupEnv(key)
+		if !ok {
+			return val, fmt.Errorf("could not get variable[%s]: %w", key, ErrNotSet)
+		}
+
+		return val, fmt.Errorf("could not parse variable[%s] value[%v] to type[%T]: %w", key, v, defVal, ErrInvalidValue)
+	}
+
+	return val, nil
+}
+
 // EnvOrDefault retrieves the value of the environment variable named by the key.
 // If the variable is present in the environment the value will be parsed and returned.
 // Otherwise, the default value will be returned.