YamlConfigManager

The main entry point for KConfig -- a type-safe, annotation-driven YAML configuration manager for Kotlin.

YamlConfigManager provides a complete lifecycle for managing YAML configuration files backed by Kotlin data classes:

1. Register custom serializers for types not natively supported.

2. Register migrations to upgrade configuration schemas across versions.

3. Load a configuration from a YAML file (creating it with defaults if absent).

4. Save a configuration back to YAML with comments and proper formatting.

5. Reload a configuration from disk on demand.

6. Watch a configuration file for changes and auto-reload.

Full lifecycle example:

// 1. Register custom serializers (optional)
YamlConfigManager.registerSerializer(Duration::class, DurationSerializer)

// 2. Register migrations (optional)
YamlConfigManager.registerMigration(MyConfig::class, MigrateV1ToV2)

// 3. Load configuration
val config = YamlConfigManager.load<MyConfig>(dataFolder.resolve("config.yml"))

// 4. Save configuration
YamlConfigManager.save(dataFolder.resolve("config.yml"), config)

// 5. Reload on demand
val fresh = YamlConfigManager.reload<MyConfig>(dataFolder.resolve("config.yml"))

// 6. Watch for file changes
YamlConfigManager.watch<MyConfig>(dataFolder.resolve("config.yml")) { newConfig ->
    println("Config reloaded: $newConfig")
}

// 7. Debug output with secret masking
println(YamlConfigManager.toDebugString(config))

// 8. Cleanup watchers on shutdown
YamlConfigManager.stopAllWatchers()

Built-in features:

• Automatic default generation from data class constructor defaults

• @Comment annotations rendered as YAML comments

• @Env annotations for environment variable overrides

• @Secret annotations for masking sensitive values in debug output

• @Transient annotations for excluding fields from serialization

• Schema versioning and migration with automatic backups

• File watching with debounced auto-reload

• Colored error reporting with field-level validation details

Built-in serializers: The manager automatically registers serializers for common types including SecretString. Additional Bukkit serializers are available via club.skidware.kconfig.bukkit.BukkitSerializers.registerAll.

See also