Type-Safe Getters

Confy provides type-safe getter methods for all common Go types. Every getter accepts optional default values using variadic arguments.

Basic Getters01

All basic getters follow the pattern Get<Type>(key, ...defaults):

cfg := confy.New()
cfg.LoadFrom(source)

// String
host := cfg.GetString("database.host", "localhost")
name := cfg.GetString("app.name") // returns "" if missing

// Integers
port := cfg.GetInt("server.port", 8080)
workers := cfg.GetInt64("pool.workers", 4)

// Floats
rate := cfg.GetFloat64("rate_limit", 1.5)

// Boolean
debug := cfg.GetBool("debug", false)

// Duration (parses "30s", "5m", "1h")
timeout := cfg.GetDuration("timeout", 30*time.Second)

// Time
expiry := cfg.GetTime("token.expiry")

// Size in bytes (parses "10MB", "1GB")
maxSize := cfg.GetSizeInBytes("upload.max_size", 1024*1024)

Complete Type Reference02

Scalar Types

Method	Return Type	Zero Value
`GetString`	`string`	`""`
`GetInt`	`int`	`0`
`GetInt8`	`int8`	`0`
`GetInt16`	`int16`	`0`
`GetInt32`	`int32`	`0`
`GetInt64`	`int64`	`0`
`GetUint`	`uint`	`0`
`GetUint8`	`uint8`	`0`
`GetUint16`	`uint16`	`0`
`GetUint32`	`uint32`	`0`
`GetUint64`	`uint64`	`0`
`GetFloat32`	`float32`	`0.0`
`GetFloat64`	`float64`	`0.0`
`GetBool`	`bool`	`false`
`GetDuration`	`time.Duration`	`0`
`GetTime`	`time.Time`	zero time
`GetSizeInBytes`	`uint64`	`0`

Collection Types

Method	Return Type
`GetStringSlice`	`[]string`
`GetIntSlice`	`[]int`
`GetInt64Slice`	`[]int64`
`GetFloat64Slice`	`[]float64`
`GetBoolSlice`	`[]bool`
`GetStringMap`	`map[string]string`
`GetStringMapStringSlice`	`map[string][]string`

Collection Examples

// Slices
hosts := cfg.GetStringSlice("cluster.hosts", []string{"localhost"})
ports := cfg.GetIntSlice("service.ports")

// Maps
headers := cfg.GetStringMap("http.headers", map[string]string{
    "X-Request-ID": "auto",
})

tags := cfg.GetStringMapStringSlice("service.tags")

Untyped Getter03

The generic Get method returns any for dynamic access:

value := cfg.Get("some.key")

switch v := value.(type) {
case string:
    fmt.Println("string:", v)
case int:
    fmt.Println("int:", v)
case map[string]any:
    fmt.Println("map:", v)
}

Advanced Getters with Options04

For more control, use the WithOptions variants that return both a value and an error:

port, err := cfg.GetIntWithOptions("server.port",
    confy.WithDefault(8080),
    confy.WithRequired(),
    confy.WithValidator(func(v any) error {
        if p, ok := v.(int); ok && (p < 1 || p > 65535) {
            return fmt.Errorf("port must be 1-65535, got %d", p)
        }
        return nil
    }),
)
if err != nil {
    log.Fatal(err)
}

Available Get Options

Option	Description
`WithDefault(value)`	Set a default value
`WithRequired()`	Error if key is missing
`WithValidator(fn)`	Validate the retrieved value
`WithTransform(fn)`	Transform the value after retrieval
`WithOnMissing(fn)`	Callback when key is missing
`AllowEmpty()`	Allow empty string/zero values
`WithCacheKey(key)`	Custom cache key for the result

Validation on Get

level, err := cfg.GetStringWithOptions("log.level",
    confy.WithDefault("info"),
    confy.WithValidator(func(v any) error {
        valid := map[string]bool{"debug": true, "info": true, "warn": true, "error": true}
        if s, ok := v.(string); ok && !valid[s] {
            return fmt.Errorf("invalid log level: %s", s)
        }
        return nil
    }),
)

Transform on Get

url, err := cfg.GetStringWithOptions("api.url",
    confy.WithTransform(func(v any) any {
        if s, ok := v.(string); ok {
            return strings.TrimRight(s, "/")
        }
        return v
    }),
)

Missing Key Callback

value, err := cfg.GetWithOptions("feature.flag",
    confy.WithOnMissing(func(key string) any {
        log.Printf("WARN: key %q not found, using fallback", key)
        return false
    }),
)

Key Paths05

Configuration keys use dot notation for nested access:

# config.yaml
database:
  primary:
    host: localhost
    port: 5432
  pool:
    max_connections: 20

host := cfg.GetString("database.primary.host")      // "localhost"
port := cfg.GetInt("database.primary.port")          // 5432
maxConns := cfg.GetInt("database.pool.max_connections") // 20

Introspection06

Check key existence and query metadata:

// Check if a key exists
if cfg.HasKey("database.host") {
    // key is present in the configuration
}

// Same as HasKey
if cfg.IsSet("feature.enabled") {
    // ...
}

// Get all keys
keys := cfg.GetKeys()

// Get a section as a map
dbConfig := cfg.GetSection("database")

// Get total number of keys
count := cfg.Size()

Type Conversion07

Confy automatically converts between compatible types. For example:

String "42" → int 42
String "true" → bool true
String "30s" → time.Duration of 30 seconds
String "10MB" → uint64 of 10485760 bytes
Int 8080 → string "8080"
Float 3.14 → int 3

Warning

If type conversion fails, the getter returns the zero value for the requested type (or the default if provided). Use the WithOptions variants to detect conversion errors.

← Previous

Configuration Sources

Struct Binding