cleanenv

To allow a custom type to be populated from an environment variable, implement the Setter interface. The SetValue method should handle the conversion from a string to your custom type.

type MyField string

func (f *MyField) SetValue(s string) error  {
    if s == "" {
        return fmt.Errorf("field value can't be empty")
    }
    *f = MyField("my field is: " + s)
    return nil
}

type Config struct {
    Field MyField `env="MY_VALUE"`
}

To execute custom logic (like loading from a remote source) when calling UpdateEnv, implement the Updater interface on your configuration structure. The Update method is called to refresh the fields.

type Config struct {
    Field string
}

func (c *Config) Update() error {
    newField, err := SomeCustomUpdate()
    c.Field = newField
    return err
}

To install the cleanenv package, run the following command:

go get -u github.com/ilyakaznacheev/cleanenv

You can implement custom logic to transform environment variable strings into complex types (like slices or custom structs) by defining a SetValue method on your configuration field's type.

When cleanenv populates your configuration struct, it will call the SetValue method on the field if it exists. This is useful when an environment variable provides a single delimited string (e.g., "admin owner member") but your struct requires a slice (e.g., []string{"admin", "owner", "member"}).

You can use cleanenv.FUsage to wrap the usage output of the standard Go flag package, allowing you to include environment variable descriptions in your CLI help text.

// create some config structure
var cfg config 

// create flag set using `flag` package
fset := flag.NewFlagSet("Example", flag.ContinueOnError)

// get config usage with wrapped flag usage
fset.Usage = cleanenv.FUsage(fset.Output(), &cfg, nil, fset.Usage)

fset.Parse(os.Args[1:])

Use cleanenv.ReadConfig to parse a configuration file (e.g., YAML) and then overwrite those values with any matching environment variables. If neither a file nor an environment variable provides a value, the field will use the value specified in the env-default tag.

import "github.com/ilyakaznacheev/cleanenv"

type ConfigDatabase struct {
    Port     string `yaml:"port" env:"PORT" env-default:"5432"`
    Host     string `yaml:"host" env:"HOST" env-default:"localhost"`
    Name     string `yaml:"name" env:"NAME" env-default:"postgres"`
    User     string `yaml:"user" env:"USER" env-default:"user"`
    Password string `yaml:"password" env:"PASSWORD"`
}

var cfg ConfigDatabase

err := cleanenv.ReadConfig("config.yml", &cfg)
if err != nil {
    // handle error
}

To allow certain configuration fields to be refreshed from environment variables while the application is running, mark them with the env-upd tag. You can then call cleanenv.UpdateEnv to update only those specific fields.

import "github.com/ilyakaznacheev/cleanenv"

type ConfigRemote struct {
    Port     string `env:"PORT" env-upd`
    Host     string `env:"HOST" env-upd`
    UserName string `env:"USERNAME"`
}

var cfg ConfigRemote

cleanenv.ReadEnv(&cfg)

// ... some actions in-between

err := cleanenv.UpdateEnv(&cfg)
if err != nil {
    // handle error
}

If you do not want to use configuration files, use cleanenv.ReadEnv to populate your configuration structure directly from environment variables.

import "github.com/ilyakaznacheev/cleanenv"

type ConfigDatabase struct {
    Port     string `env:"PORT" env-default:"5432"`
    Host     string `env:"HOST" env-default:"localhost"`
    Name     string `env:"NAME" env-default:"postgres"`
    User     string `env:"USER" env-default:"user"`
    Password string `env:"PASSWORD"`
}

var cfg ConfigDatabase

err := cleanenv.ReadEnv(&cfg)
if err != nil {
    // handle error
}