Merge pull request #26 from aPureBase/v3.1.0

jeggy · web-flow · commit bd78a64dab56 · 2019-11-12T21:58:58.000Z
Feature branch for v3.1.0
diff --git a/arkenv/src/main/kotlin/com/apurebase/arkenv/Arkenv.kt b/arkenv/src/main/kotlin/com/apurebase/arkenv/Arkenv.kt
@@ -23,14 +23,16 @@ abstract class Arkenv(
         defaultValue = { programName }
     }
 
-    internal fun parseArguments(args: Array<out String>) {
-        if (configuration.clearInputBeforeParse) clear()
+    internal fun parseArguments(args: Array<out String>) = with(configuration) {
+        if (clearInputBeforeParse) clear()
         argList.addAll(args)
-        configuration.features.forEach { it.onLoad(this) }
+        features.forEach { it.onLoad(this@Arkenv) }
+        features.forEach { it.postLoad(this@Arkenv) }
         process()
-        parse()
-        configuration.features.forEach { it.finally(this) }
-        if (configuration.clearInputAfterParse) clear()
+        parse(delegates)
+        features.forEach { it.finally(this@Arkenv) }
+        modules.forEach { parse(it.delegates) }
+        if (clearInputAfterParse) clear()
     }
 
     /**
@@ -98,7 +100,7 @@ abstract class Arkenv(
         else names.filterNot(String::isSimpleName).mapNotNull(::getOrNull)
     }
 
-    private fun parse() = delegates
+    private fun parse(delegates: Collection<ArgumentDelegate<*>>) = delegates
         .sortedBy { it.argument.isMainArg }
         .forEach {
             configuration.features.forEach { feature ->
diff --git a/arkenv/src/main/kotlin/com/apurebase/arkenv/ArkenvBuilder.kt b/arkenv/src/main/kotlin/com/apurebase/arkenv/ArkenvBuilder.kt
@@ -21,6 +21,7 @@ class ArkenvBuilder(installAdvancedFeatures: Boolean = true) {
 
     internal val features: MutableList<ArkenvFeature> = mutableListOf()
     internal val processorFeatures: MutableList<ProcessorFeature> = mutableListOf()
+    internal val modules: MutableList<Arkenv> = mutableListOf()
 
     /**
      * Installs the [feature] into [Arkenv].
@@ -73,3 +74,10 @@ class ArkenvBuilder(installAdvancedFeatures: Boolean = true) {
  * @param block Arkenv configuration logic.
  */
 inline fun configureArkenv(block: (ArkenvBuilder.() -> Unit)) = ArkenvBuilder().apply(block)
+
+/**
+ * Registers the [module] as a sub module that will be automatically parsed after the super Arkenv.
+ * It will be parsed using the configuration of its root.
+ * @param module the sub module to add to this [Arkenv]
+ */
+fun <T: Arkenv> Arkenv.module(module: T): T = module.also { configuration.modules.add(it) }
diff --git a/arkenv/src/main/kotlin/com/apurebase/arkenv/feature/ArkenvFeature.kt b/arkenv/src/main/kotlin/com/apurebase/arkenv/feature/ArkenvFeature.kt
@@ -16,6 +16,13 @@ interface ArkenvFeature {
     fun onLoad(arkenv: Arkenv) {
     }
 
+    /**
+     * Executed after all features have been loaded.
+     * Can be used for reactive loading, where one feature is enabled by another one.
+     */
+    fun postLoad(arkenv: Arkenv) {
+    }
+
     /**
      * Used to assign a value to the [Argument] represented by [delegate].
      */
@@ -26,6 +33,7 @@ interface ArkenvFeature {
     /**
      * Applies configuration to every [argument].
      */
+    @Deprecated("Will be removed in future major version")
     fun configure(argument: Argument<*>) {
     }
 
diff --git a/arkenv/src/main/kotlin/com/apurebase/arkenv/feature/EnvironmentVariableFeature.kt b/arkenv/src/main/kotlin/com/apurebase/arkenv/feature/EnvironmentVariableFeature.kt
@@ -19,9 +19,13 @@ class EnvironmentVariableFeature(
     private val dotEnvFilePath: String? = null
 ) : ArkenvFeature {
 
+    private var isLoaded = false
+
     override fun onLoad(arkenv: Arkenv) {
-        loadEnvironmentVariables(arkenv.getOrNull("ARKENV_DOT_ENV_FILE"))
-            ?.let(arkenv::putAll)
+        loadEnvironmentVariables(arkenv.getOrNull("ARKENV_DOT_ENV_FILE"))?.let {
+            arkenv.putAll(it)
+            isLoaded = true
+        }
     }
 
     override fun onParse(arkenv: Arkenv, delegate: ArgumentDelegate<*>): String? = with(delegate) {
@@ -30,6 +34,10 @@ class EnvironmentVariableFeature(
         getEnvValue(argument, envSecrets, setEnvPrefix)
     }
 
+    override fun postLoad(arkenv: Arkenv) {
+        if (!isLoaded) onLoad(arkenv)
+    }
+
     /**
      * Loop over all argument names and pick the first one that matches
      */
diff --git a/arkenv/src/test/kotlin/com/apurebase/arkenv/ModuleTests.kt b/arkenv/src/test/kotlin/com/apurebase/arkenv/ModuleTests.kt
@@ -0,0 +1,33 @@
+package com.apurebase.arkenv
+
+import com.apurebase.arkenv.feature.ProfileFeature
+import com.apurebase.arkenv.feature.PropertyFeature
+import com.apurebase.arkenv.test.expectThat
+import com.apurebase.arkenv.test.parse
+import org.junit.jupiter.api.Test
+import strikt.assertions.isEqualTo
+
+internal class ModuleTests {
+
+    private inner class DatabaseConfig : Arkenv("Database") {
+        val port: Int by argument()
+    }
+
+    private inner class Ark : Arkenv("Root", configureArkenv {
+        uninstall(ProfileFeature())
+        install(PropertyFeature("application-prod")) // load a specific file to test feature propagation
+    }) {
+        val name: String by argument()
+        val database = module(DatabaseConfig())
+    }
+
+    @Test fun `modules should be parsed by super`() {
+        val myApp = "production"
+        val port = 443
+        Ark().parse()
+            .expectThat {
+                get { name }.isEqualTo(myApp)
+                get { database.port }.isEqualTo(port)
+            }
+    }
+}
diff --git a/arkenv/src/test/kotlin/com/apurebase/arkenv/feature/EnvFileTests.kt b/arkenv/src/test/kotlin/com/apurebase/arkenv/feature/EnvFileTests.kt
@@ -3,17 +3,19 @@ package com.apurebase.arkenv.feature
 import com.apurebase.arkenv.Arkenv
 import com.apurebase.arkenv.argument
 import com.apurebase.arkenv.configureArkenv
+import com.apurebase.arkenv.test.dotEnvPath
 import com.apurebase.arkenv.test.expectThat
 import com.apurebase.arkenv.test.getTestResourcePath
 import com.apurebase.arkenv.test.parse
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.assertThrows
+import strikt.api.Assertion
 import strikt.assertions.isEqualTo
 import java.io.FileNotFoundException
 
 class EnvFileTests {
 
-    private class EnvFileArk(dotEnvFilePath: String? = null) : Arkenv("Test", configureArkenv {
+    private inner class EnvFileArk(dotEnvFilePath: String? = null) : Arkenv("Test", configureArkenv {
         uninstall(EnvironmentVariableFeature())
         install(EnvironmentVariableFeature(dotEnvFilePath = dotEnvFilePath))
     }) {
@@ -30,22 +32,32 @@ class EnvFileTests {
     }
 
     @Test fun `should load values from dot env file`() {
-        val path = getTestResourcePath(".env")
-        EnvFileArk(path).parse().expectThat {
-            get { mysqlPassword }.isEqualTo("this_is_expected")
-            get { port }.isEqualTo(5050)
-            get { connectionString }.isEqualTo("localhost:5050;database=testdb;user=testuser;")
-        }
+        EnvFileArk(dotEnvPath).parse().expectThat { verify() }
     }
 
     @Test fun `dot env file can be specified via argument`() {
-        val path = getTestResourcePath(".env-alt")
         EnvFileArk()
-            .parse("ARKENV_DOT_ENV_FILE", path)
-            .expectThat {
-                get { mysqlPassword }.isEqualTo("alternative")
-                get { port }.isEqualTo(8080)
-                get { connectionString }.isEqualTo("localhost")
-            }
+            .parse("ARKENV_DOT_ENV_FILE", altPath)
+            .expectThat { verifyAlt() }
     }
+
+    @Test fun `dot env file can be specified via profile`() {
+        EnvFileArk()
+            .parse("--arkenv-profile", "placeholder")
+            .expectThat { verify() }
+    }
+
+    private fun Assertion.Builder<EnvFileArk>.verify() {
+        get { mysqlPassword }.isEqualTo("this_is_expected")
+        get { port }.isEqualTo(5050)
+        get { connectionString }.isEqualTo("localhost:5050;database=testdb;user=testuser;")
+    }
+
+    private fun Assertion.Builder<EnvFileArk>.verifyAlt() {
+        get { mysqlPassword }.isEqualTo("alternative")
+        get { port }.isEqualTo(8080)
+        get { connectionString }.isEqualTo("localhost")
+    }
+
+    private val altPath = getTestResourcePath(".env-alt")
 }
diff --git a/arkenv/src/test/kotlin/com/apurebase/arkenv/feature/PlaceholderTests.kt b/arkenv/src/test/kotlin/com/apurebase/arkenv/feature/PlaceholderTests.kt
@@ -1,14 +1,12 @@
 package com.apurebase.arkenv.feature
 
 import com.apurebase.arkenv.*
-import com.apurebase.arkenv.test.MockSystem
-import com.apurebase.arkenv.test.expectThat
-import com.apurebase.arkenv.test.getTestResourcePath
-import com.apurebase.arkenv.test.parse
+import com.apurebase.arkenv.test.*
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.TestInstance
 import org.junit.jupiter.api.assertThrows
 import strikt.assertions.isEqualTo
+import java.io.File
 
 @TestInstance(TestInstance.Lifecycle.PER_CLASS)
 class PlaceholderTests {
@@ -19,8 +17,8 @@ class PlaceholderTests {
     }
 
     @Test fun `can refer to previously defined arg in properties`() {
-        val ark = Ark { install(PropertyFeature("placeholders.properties")) }
-        ark.parse()
+        Ark { install(PropertyFeature("placeholders.properties")) }
+            .parse()
             .verify()
     }
 
@@ -82,15 +80,19 @@ class PlaceholderTests {
         val testValue = "this_is_expected"
         val expected = "$testValue is not declared"
 
-        val ark = Ark {
-            install(EnvironmentVariableFeature(dotEnvFilePath = getTestResourcePath(".env")))
-        }
-        ark.parse(appNameArg, appName, appDescArg, "\${mysql_password} is not declared")
+        Ark { install(EnvironmentVariableFeature(dotEnvFilePath = dotEnvPath)) }
+            .parse(appNameArg, appName, appDescArg, "\${mysql_password} is not declared")
             .expectThat {
                 get { description }.isEqualTo(expected)
             }
     }
 
+    @Test fun `refer to env from profile`() {
+
+        Ark().parse("--arkenv-profile", "placeholder")
+            .verify()
+    }
+
     @Test fun `should throw when placeholder is not found`() {
         val ark = Ark()
         assertThrows<MissingArgumentException> {
diff --git a/arkenv/src/test/kotlin/com/apurebase/arkenv/feature/ProfileFeatureTest.kt b/arkenv/src/test/kotlin/com/apurebase/arkenv/feature/ProfileFeatureTest.kt
@@ -3,15 +3,11 @@ package com.apurebase.arkenv.feature
 import com.apurebase.arkenv.Arkenv
 import com.apurebase.arkenv.argument
 import com.apurebase.arkenv.configureArkenv
-import com.apurebase.arkenv.test.DEPRECATED
 import com.apurebase.arkenv.test.MockSystem
 import com.apurebase.arkenv.test.expectThat
 import com.apurebase.arkenv.test.parse
-import org.amshove.kluent.shouldNotBeNull
-import org.junit.jupiter.api.Disabled
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.TestInstance
-import org.junit.jupiter.api.assertThrows
 import strikt.api.Assertion
 import strikt.assertions.isEqualTo
 
diff --git a/arkenv/src/test/kotlin/com/apurebase/arkenv/test/TestUtil.kt b/arkenv/src/test/kotlin/com/apurebase/arkenv/test/TestUtil.kt
@@ -15,4 +15,4 @@ fun <T : Arkenv> T.parse(vararg arguments: String) = apply { parseArguments(argu
 
 fun getTestResource(name: String) = MockSystem::class.java.classLoader.getResource(name)!!.readText()
 
-const val DEPRECATED = "Property files are no longer required, can be null."
+val dotEnvPath = getTestResourcePath(".env")
diff --git a/arkenv/src/test/resources/.env b/arkenv/src/test/resources/.env
@@ -6,3 +6,5 @@ DATABASE_PORT=5050
 # Everywhere
 
 CONNECTION_STRING=localhost:${DATABASE_PORT};database=testdb;user=testuser;
+
+APP_NAME=MyApp
diff --git a/arkenv/src/test/resources/application-placeholder.properties b/arkenv/src/test/resources/application-placeholder.properties
@@ -0,0 +1,2 @@
+APP_DESCRIPTION     = ${APP_NAME} is a Arkenv application
+ARKENV_DOT_ENV_FILE = src/test/resources/.env
diff --git a/docs/features/features.md b/docs/features/features.md
@@ -47,8 +47,9 @@ This means that by default command line arguments have the highest order and wil
 To create a new feature from scratch, simply implement the `ArkenvFeature`
 interface. 
 
-It has 3 overridable methods:
+It has 4 overridable methods:
 * `onLoad` is used to read data from a source and store it for parsing. 
+* `postLoad` is used to react to configuration after all features have been loaded.
 * `onParse` is used on each argument property when parsing to obtain a value.
 * `finally` can be used for clean up. 
 
diff --git a/docs/features/sub-modules.md b/docs/features/sub-modules.md
@@ -0,0 +1,44 @@
+---
+layout: default
+title: Sub Modules
+parent: Features
+nav_order: 11
+---
+
+# Sub Modules
+
+**Since v3.1.0**
+
+Arkenv definitions can be organized by using sub modules.
+
+A common scenario for sub modules is when you want your configuration 
+split into multiple files.
+
+For example, you may want to define your database configuration 
+in a different class / file. 
+
+```kotlin
+class DatabaseConfig : Arkenv() {
+    val port: Int by argument()
+}
+
+class Ark : Arkenv() {
+    val name: String by argument()
+    val database = module(DatabaseConfig())
+}
+```
+The above example shows how to use the `module` function to register 
+another Arkenv instance as a module, which will then be parsed together 
+with the root module that it is defined in.   
+
+The sub module's properties can then be accessed after parsing. 
+```kotlin
+fun main(args: Array<String>) {
+    val ark = Ark().parse(args)
+    println(ark.database.port) 
+}
+```
+
+The sub modules will be parsed using the root module's features.
+
+Recursive modules are not supported and will lead to a stack overflow.
diff --git a/docs/features/yaml.md b/docs/features/yaml.md
@@ -1,8 +1,8 @@
 ---
 layout: default
-title: Validation
-parent: Yaml
-nav_order: 11
+title: Yaml
+parent: Features
+nav_order: 12
 ---
 
 # Yaml

Original file line number	Diff line number	Diff line change
`@@ -15,4 +15,4 @@ fun <T : Arkenv> T.parse(vararg arguments: String) = apply { parseArguments(argu`
`15`	`15`
`16`	`16`	`fun getTestResource(name: String) = MockSystem::class.java.classLoader.getResource(name)!!.readText()`
`17`	`17`
`18`		`-const val DEPRECATED = "Property files are no longer required, can be null."`
	`18`	`+val dotEnvPath = getTestResourcePath(".env")`