configloader

func WithDefaultTag ¶

func WithDefaultTag(tag string) Option

WithDefaultTag sets the struct tag used for specifying default values. If an environment variable is not found, the value of this tag will be used instead.

Example:

type Config struct {
    Port int `default:"8080"`  // Will use 8080 if PORT is not set
}
configloader.Load(&cfg, WithDefaultTag("default"))

func WithEnv ¶

func WithEnv(env func(string) (string, bool)) Option

WithEnv sets a custom function for looking up environment variables. This is primarily useful for testing or when environment variables need to be sourced from somewhere other than os.LookupEnv.

The function should return the value and a boolean indicating whether the variable was found, similar to os.LookupEnv.

func WithEnvTag ¶

func WithEnvTag(tag string) Option

WithEnvTag sets the struct tag used to completely override the environment variable name for a field. When a field has this tag, its value is used as-is for the environment variable name, bypassing all other name construction rules including prefixes and path building.

Example with WithEnvTag("env"):

type Config struct {
    Database struct {
        // Despite nesting, looks directly for "DB_HOST"
        Host string `env:"DB_HOST"`
    }
}
configloader.Load(&cfg)

Example showing prefix is ignored with env tag:

type Config struct {
    Database struct {
        // Still only looks for "DB_HOST", prefix is not applied
        Host string `env:"DB_HOST"`
    }
}
configloader.Load(&cfg, WithPrefix("APP"))

func WithNameTag ¶

func WithNameTag(tag string) Option

WithNameTag sets the struct tag used to override a field's name in the environment variable path. The tag value replaces just the field's name segment while still following the normal path construction rules (prefix + path + name).

Example with WithNameTag("name"):

type Config struct {
    Database struct {
        Host string `name:"HOSTNAME"` // Looks for DATABASE_HOSTNAME
    }
}
configloader.Load(&cfg)

Example with both prefix and name tag:

type Config struct {
    Database struct {
        Host string `name:"HOSTNAME"` // Looks for APP_DATABASE_HOSTNAME
    }
}
configloader.Load(&cfg, WithPrefix("APP"))

func WithOptionalTag ¶ added in v1.1.0

func WithOptionalTag(tag string) Option

WithOptionalTag configures the struct tag name for marking fields as optional. Optional fields will not return an error if their environment variable is missing and no default value is provided. They remain at their zero value instead.

The tag value can be:

• Empty string for optional: `optional:""`
• Explicit boolean: `optional:"true"` or `optional:"false"`

If a field has both optional and default tags, the default value is used when the environment variable is missing.

Example:

type Config struct {
    Required    string              // Error if REQUIRED not set
    Optional    string `optional:""` // OK if OPTIONAL not set, remains ""
    OptionalURL *url.URL `optional:"true"` // OK if not set, remains nil
    WithDefault string `optional:"" default:"fallback"` // Uses fallback
}

err := configloader.Load(&cfg)

func WithPrefix ¶

func WithPrefix(prefix string) Option

WithPrefix sets a prefix that will be prepended to all environment variable names. The prefix and field name will be joined with an underscore.

Example:

type Config struct {
    Port int  // Will look for "APP_PORT" environment variable
}
configloader.Load(&cfg, WithPrefix("APP"))

func WithTypeHandler ¶

func WithTypeHandler[T any](f func(string) (T, error)) Option

WithTypeHandler registers a custom type conversion function for a specific type T. The function should convert a string environment value to type T, returning an error if the conversion fails.

Example:

configloader.Load(&cfg, WithTypeHandler(func(s string) (time.Duration, error) {
    return time.ParseDuration(s)
}))