{"id":15297599,"url":"https://github.com/npryce/konfig","last_synced_at":"2025-04-05T09:06:56.652Z","repository":{"id":2705450,"uuid":"47224380","full_name":"npryce/konfig","owner":"npryce","description":"Simple config properties API for Kotlin","archived":false,"fork":false,"pushed_at":"2022-06-05T11:15:13.000Z","size":263,"stargazers_count":282,"open_issues_count":16,"forks_count":38,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-29T08:06:41.481Z","etag":null,"topics":["command-line-parser","configuration","environment-variables","jvm","kotlin","properties"],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npryce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-12-01T23:39:23.000Z","updated_at":"2025-01-15T06:11:51.000Z","dependencies_parsed_at":"2022-09-05T22:00:46.306Z","dependency_job_id":null,"html_url":"https://github.com/npryce/konfig","commit_stats":null,"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npryce%2Fkonfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npryce%2Fkonfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npryce%2Fkonfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npryce%2Fkonfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npryce","download_url":"https://codeload.github.com/npryce/konfig/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247312077,"owners_count":20918344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line-parser","configuration","environment-variables","jvm","kotlin","properties"],"created_at":"2024-09-30T19:18:26.748Z","updated_at":"2025-04-05T09:06:56.610Z","avatar_url":"https://github.com/npryce.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Konfig - A Type Safe Configuration API for Kotlin\n\n[![Kotlin](https://img.shields.io/badge/kotlin-1.0.0-blue.svg)](http://kotlinlang.org)\n[![Build Status](https://travis-ci.org/npryce/konfig.svg?branch=master)](https://travis-ci.org/npryce/konfig)\n[![Maven Central](https://img.shields.io/maven-central/v/com.natpryce/konfig.svg)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.natpryce%22%20AND%20a%3A%22konfig%22)\n\nKonfig provides an extensible, type-safe API for configuration\nproperties gathered from multiple sources — built in resources, system\nproperties, property files, environment variables, command-line\narguments, etc.\n\nA secondary goal of Konfig is to make configuration \"self explanatory”.\n\nMisconfiguration errors are reported with the location and “true name”\nof the badly configured property. E.g. a program may look up a key\ndefined as `Key(\"http.port\", intType)`. At runtime, it will be parsed\nfrom an environment variable named `HTTP_PORT`. So the error message\nreports the name of the environment variable, so that the user can\neasily find and fix the error.\n\nConfiguration can be inspected and listed.  For example, it can be\nexposed by HTTP to a network management system to help site\nreliability engineers understand the current configuration of a\nrunning application.\n\n\n\nGetting Started\n---------------\n\nTo get started, add `com.natpryce:konfig:\u003cversion\u003e` as a dependency, import `com.natpryce.konfig.*` and then:\n\n1. Define typed property keys\n\n    ```kotlin\n    val server_port = Key(\"server.port\", intType)\n    val server_host = Key(\"server.host\", stringType)\n    ```\n\n2. Build a Configuration object that loads properties:\n\n    ```kotlin\n    val config = systemProperties() overriding\n                 EnvironmentVariables() overriding\n                 ConfigurationProperties.fromFile(File(\"/etc/myservice.properties\")) overriding\n                 ConfigurationProperties.fromResource(\"defaults.properties\")\n    ```\n\n3. Define some properties.  For example, in `defaults.properties`:\n\n    ```properties\n    server.port=8080\n    server.host=0.0.0.0\n    ```\n    \n4. Look up properties by key. They are returned as typed values, not strings, and so can be used directly:\n\n    ```kotlin\n    val server = Server(config[server_port], config[server_host])\n    server.start()\n    ```\n\nKonfig can load properties from:\n\n* Java property files and resources\n* Java system properties\n* Environment variables\n* Hard-coded maps (with convenient syntax)\n* Command-line parameters (with long and short option syntax)\n\nKonfig can easily be extended with new property types and sources of configuration data.\n\nKonfig can report where configuration properties are searched for and where they were found.\n\n# Naming of Properties\n\nKonfig's Configuration objects expect property names to follow Java property name conventions: dots to represent hierarchy, lower-case identifiers within the hierarchy, hyphens to separate words in those identifiers. \n\nFor example: `servers.file-storage.s3-api-key`, `servers.file-storage.s3-bucket`.\n\nEach Configuration implementation maps from that naming convention to the convention used by the underlying configuration store. E.g. the `EnvironmentVariables` implementation maps Java property name convention to the upper-case-and-underscores convention used for Unix environment variables.\n\nConfiguration is an interface and Key\u003cT\u003e is a data class. This makes it straight forward to write an implementation of Configuration that translates the names of keys to different naming conventions, if your configuration follows an unusual convention.\n\n\n# Reflectomagic key definition\n\nKonfig has a few ways to reduce boilerplate code when defining configuration keys.\n\n1) You can use Kotlin's delgated property protocol to name keys after the constants that hold them:\n\n    ```\n    val host by stringType // defines a key named \"host\"\n    val port by intType    // defines a key named \"port\"\n    \n    ...\n    \n    val client = TcpClient(configuration[host], configuration[port])\n    ```\n\n2) You can declare objects that extend PropertyGroup to define hierarchies of property keys that follow the Konfig naming conventions described above:\n\n    ```\n    object server : PropertyGroup() {\n        val base_uri by uriType   // defines a key named \"server.base-uri\"\n        val api_key by stringType // defines a key named \"server.api-key\"\n    }\n\n    ...\n\n    val client = HttpClient(configuration[server.base_uri], configuration[server.api_key])\n    ```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpryce%2Fkonfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpryce%2Fkonfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpryce%2Fkonfig/lists"}