enviro

README

Enviro

Enviro is a Go library designed to simplify the process of loading and parsing environment variables into Go structs. It supports a wide range of field types, nested structs, custom types, and more, with an emphasis on convenience and ease of use.

Disclaimer

Enviro is currently in a very early stage of development. As such, the API is not yet stabilized, and breaking changes may occur before we reach v1.0.0.

Features

• Automatic Parsing: Automatically parse environment variables into Go structs.
• Nested Structs: Support for nested structs to organize your configuration logically.
• Custom Types: Easily handle custom types with the ParseField interface.
• Flexible Tagging: Use struct tags to specify environment variable names and options.
• Built-in Type Support: Out-of-the-box support for common Go types and parsing of complex types like URLs, times, and files.

Installation

To install Enviro, use the following go get command:

go get -u github.com/tigerwill90/enviro

Usage

Here's a quick example to show how you can use Enviro to load environment variables into a struct:

package main

import (
	"github.com/tigerwill90/enviro"
	"log"
	"net/url"
	"time"
)

type Config struct {
	Port  int            `enviro:"port" envdefault:"8080"` // MYAPP_PORT=8080
	Host  string         `enviro:"host,required"`          // MYAPP_HOST=localhost
	Local *time.Location `enviro:"tz,required,omitprefix"` // TZ=America/New_York
	Debug bool           `enviro:"debug"`                  // MYAPP_DEBUG=true
	Proxy struct {
		Url     url.URL       `enviro:"url"`     // MYAPP_PROXY_URL=https://example.com
		Timeout time.Duration `enviro:"timeout"` // MYAPP_PROXY_TIMEOUT=5s
	} `enviro:"nested:proxy"`
}

func main() {
	env := enviro.New()
	env.SetEnvPrefix("MYAPP")
	cfg := Config{
		// Port: 8080, or set a default value directly in the struct
	}
	if err := env.ParseEnv(&cfg); err != nil {
		log.Fatalf("Error loading config: %s", err)
	}

	log.Printf("Loaded config: %+v", cfg)
}

Struct Tags

• enviro: Specifies the name of the environment variable and options (e.g., required).
• envopt: Provides additional parsing options for complex types (e.g., file permissions).

Supported Types

Enviro supports all basic Go types (int, string, bool, etc.), slices, maps, and any type implementing the ParseField interface for custom parsing logic.

Contributing

We welcome contributions! Please feel free to submit a pull request or create an issue for bugs, feature requests, or documentation improvements.

License

Enviro is released under the MIT License. See the bundled LICENSE file for details.

Documentation

Index

• type Enviro
  • func New() *Enviro
  • func (e *Enviro) MustParseEnv(config any)
  • func (e *Enviro) ParseEnv(config any) error
  • func (e *Enviro) ParseEnvWithPrefix(config any, prefix string) error
  • func (e *Enviro) SetEnvPrefix(prefix string)
• type ParseField

Types

type Enviro

type Enviro struct {
	// contains filtered or unexported fields
}

Enviro facilitates the loading and parsing of environment variables into Go structs. It supports custom prefixes for environment variables, nested struct parsing, and fields of various types.

func New

func New() *Enviro

New creates and returns a new instance of the Enviro parser.

func (*Enviro) MustParseEnv

func (e *Enviro) MustParseEnv(config any)

MustParseEnv is a convenience method that calls ParseEnv and panics if an error occurs.

func (*Enviro) ParseEnv

func (e *Enviro) ParseEnv(config any) error

ParseEnv is a convenience method that calls ParseEnvWithPrefix with the base prefix set on the Enviro instance.

func (*Enviro) ParseEnvWithPrefix

func (e *Enviro) ParseEnvWithPrefix(config any, prefix string) error

ParseEnvWithPrefix parses environment variables into the provided struct based on struct tags. It uses the specified prefix to look up environment variables, allowing for nested struct parsing and the application of custom parsing logic for specific fields. The function returns an error if parsing fails for any field, or if the provided `config` is not a pointer to a struct.

The `config` parameter should be a pointer to the struct you wish to populate with environment variable values. If the struct contains nested structs and the tag `enviro:"nested:your_prefix"`, the prefix is concatenated with "_" and the nested struct's tag to form the complete environment variable name.

func (*Enviro) SetEnvPrefix

func (e *Enviro) SetEnvPrefix(prefix string)

SetEnvPrefix sets a custom prefix that will be prepended to all environment variable names when parsing. Fields with the `enviro:your_var_name,omitprefix` will ignore the prefix.

type ParseField

type ParseField interface {
	// ParseField parses the provided string value and sets the receiver accordingly.
	// It returns an error if the value cannot be parsed into the expected type.
	ParseField(value string) error
}

ParseField is an interface that defines how to parse environment variable values. Types that implement ParseField can define their own logic to parse the string representation of an environment variable into the appropriate Go type.