Use a separate Knit tool (#1486)
* Use a separate Knit tool version 0.1.2
* Hierarchical knit.properties files are introduced which are
gathered while walking up the directory tree with the properties
in knit resources being top-level ones.
* Freemarker templates for "knit.include" (top-level of example files)
and "test.template" (test template) are introduced with locations that
are resolved from properties.
* KNIT and TEST_OUT directives are not supported anymore.
- Knitting is controlled by "knit.dir" and "knit.pattern" props.
- "test.name" prop or TEST_NAME directive drives test gen.
* All markdown files are now clean of top-level knit-related boilerplate
(only TEST_NAME directive is remaining in some)
* All example files are renumbered. It affects example-basic-xx,
which had the legacy numbering with later insertions.
* All auto-generated files now have the correct source-file name
specified at their beginning, due to consistent use of template
substitution.
* No need to customize knit.pattern anymore (works out-of-the box)
* "knit.name" is automatically generated based on example's file name
"example-basic-01" -> "exampleBasic01"
* Not match-pattern-group woodoo anymore, "knit.pattern" cannot have any
user-defined match groups.
* No need to look for "package xxx" in knitted sources, as the
example's package is always ${knit.package}.${knit.name}
* Simpler test names:
testKotlinxCoroutinesGuideBasic01 -> testExampleBasic01
* Replaced END_TOC with END directive
* Build-scripts are improved:
- Consistent code to use mavenLocal when snapshots versions are used.
- Proper substitution logic to use Android AAR files so that Dokka has correct links to Google APIs.
- Google repository is added to all projects.
diff --git a/docs/basics.md b/docs/basics.md
index 6c3c0ca..c5e931c 100644
--- a/docs/basics.md
+++ b/docs/basics.md
@@ -1,20 +1,4 @@
-<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
-/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.$$1$$2
--->
-<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
-<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/BasicsGuideTest.kt
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.test
-
-import org.junit.Test
-
-class BasicsGuideTest {
--->
+<!--- TEST_NAME BasicsGuideTest -->
**Table of contents**
@@ -30,8 +14,7 @@
* [Coroutines ARE light-weight](#coroutines-are-light-weight)
* [Global coroutines are like daemon threads](#global-coroutines-are-like-daemon-threads)
-<!--- END_TOC -->
-
+<!--- END -->
## Coroutine Basics
@@ -142,7 +125,7 @@
</div>
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-02b.kt).
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-03.kt).
<!--- TEST
Hello,
@@ -197,7 +180,7 @@
</div>
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-03.kt).
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-04.kt).
<!--- TEST
Hello,
@@ -242,7 +225,7 @@
</div>
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-03s.kt).
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-05.kt).
<!--- TEST
Hello,
@@ -288,7 +271,7 @@
</div>
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-04.kt).
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-06.kt).
<!--- TEST
Task from coroutine scope
@@ -327,7 +310,7 @@
</div>
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-05.kt).
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-07.kt).
<!--- TEST
Hello,
@@ -364,7 +347,7 @@
</div>
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-06.kt).
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-08.kt).
<!--- TEST lines.size == 1 && lines[0] == ".".repeat(100_000) -->
@@ -396,7 +379,7 @@
</div>
-> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-07.kt).
+> You can get full code [here](../kotlinx-coroutines-core/jvm/test/guide/example-basic-09.kt).
You can run and see that it prints three lines and terminates:
diff --git a/docs/cancellation-and-timeouts.md b/docs/cancellation-and-timeouts.md
index ef4a9c9..b51c45c 100644
--- a/docs/cancellation-and-timeouts.md
+++ b/docs/cancellation-and-timeouts.md
@@ -1,20 +1,5 @@
-<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
-/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
+<!--- TEST_NAME CancellationGuideTest -->
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.$$1$$2
--->
-<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
-<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/CancellationTimeOutsGuideTest.kt
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.test
-
-import org.junit.Test
-
-class CancellationTimeOutsGuideTest {
--->
**Table of contents**
<!--- TOC -->
@@ -27,7 +12,7 @@
* [Run non-cancellable block](#run-non-cancellable-block)
* [Timeout](#timeout)
-<!--- END_TOC -->
+<!--- END -->
## Cancellation and Timeouts
diff --git a/docs/channels.md b/docs/channels.md
index 5550759..1d41774 100644
--- a/docs/channels.md
+++ b/docs/channels.md
@@ -1,20 +1,5 @@
-<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
-/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
+<!--- TEST_NAME ChannelsGuideTest -->
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.$$1$$2
--->
-<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
-<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/ChannelsGuideTest.kt
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.test
-
-import org.junit.Test
-
-class ChannelsGuideTest {
--->
**Table of contents**
<!--- TOC -->
@@ -31,7 +16,7 @@
* [Channels are fair](#channels-are-fair)
* [Ticker channels](#ticker-channels)
-<!--- END_TOC -->
+<!--- END -->
## Channels
diff --git a/docs/compatibility.md b/docs/compatibility.md
index e56fc1b..8dafae7 100644
--- a/docs/compatibility.md
+++ b/docs/compatibility.md
@@ -1,9 +1,3 @@
-<!---
-/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
---->
-
<!--- TOC -->
* [Compatibility](#compatibility)
@@ -19,7 +13,7 @@
* [Gradle](#gradle)
* [Maven](#maven)
-<!--- END_TOC -->
+<!--- END -->
## Compatibility
This document describes the compatibility policy of `kotlinx.coroutines` library since version 1.0.0 and semantics of compatibility-specific annotations.
diff --git a/docs/composing-suspending-functions.md b/docs/composing-suspending-functions.md
index 0cd0276..6a95d75 100644
--- a/docs/composing-suspending-functions.md
+++ b/docs/composing-suspending-functions.md
@@ -1,20 +1,4 @@
-<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
-/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.$$1$$2
--->
-<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
-<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/ComposingGuideTest.kt
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.test
-
-import org.junit.Test
-
-class ComposingGuideTest {
--->
+<!--- TEST_NAME ComposingGuideTest -->
**Table of contents**
@@ -27,7 +11,7 @@
* [Async-style functions](#async-style-functions)
* [Structured concurrency with async](#structured-concurrency-with-async)
-<!--- END_TOC -->
+<!--- END -->
## Composing Suspending Functions
diff --git a/docs/coroutine-context-and-dispatchers.md b/docs/coroutine-context-and-dispatchers.md
index 558b039..e379842 100644
--- a/docs/coroutine-context-and-dispatchers.md
+++ b/docs/coroutine-context-and-dispatchers.md
@@ -1,20 +1,4 @@
-<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
-/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.$$1$$2
--->
-<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
-<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/DispatcherGuideTest.kt
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.test
-
-import org.junit.Test
-
-class DispatchersGuideTest {
--->
+<!--- TEST_NAME DispatcherGuideTest -->
**Table of contents**
@@ -33,7 +17,7 @@
* [Coroutine scope](#coroutine-scope)
* [Thread-local data](#thread-local-data)
-<!--- END_TOC -->
+<!--- END -->
## Coroutine Context and Dispatchers
diff --git a/docs/debugging.md b/docs/debugging.md
index e2c7ec1..d3caa9a 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -9,8 +9,7 @@
* [Debug agent](#debug-agent)
* [Debug agent and Android](#debug-agent-and-android)
-<!--- END_TOC -->
-
+<!--- END -->
## Debugging coroutines
Debugging asynchronous programs is challenging, because multiple concurrent coroutines are typically working at the same time.
diff --git a/docs/exception-handling.md b/docs/exception-handling.md
index 178f528..08e63ea 100644
--- a/docs/exception-handling.md
+++ b/docs/exception-handling.md
@@ -1,20 +1,5 @@
-<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
-/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
+<!--- TEST_NAME ExceptionsGuideTest -->
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.$$1$$2
--->
-<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
-<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/ExceptionsGuideTest.kt
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.test
-
-import org.junit.Test
-
-class ExceptionsGuideTest {
--->
**Table of contents**
<!--- TOC -->
@@ -29,7 +14,7 @@
* [Supervision scope](#supervision-scope)
* [Exceptions in supervised coroutines](#exceptions-in-supervised-coroutines)
-<!--- END_TOC -->
+<!--- END -->
## Exception Handling
@@ -260,7 +245,6 @@
<!--- INCLUDE
-
import kotlinx.coroutines.exceptions.*
-->
diff --git a/docs/flow.md b/docs/flow.md
index ce4e80f..705f338 100644
--- a/docs/flow.md
+++ b/docs/flow.md
@@ -1,20 +1,4 @@
-<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
-/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.$$1$$2
--->
-<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*-##\.kt -->
-<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/FlowGuideTest.kt
-// This file was automatically generated from flow.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.test
-
-import org.junit.Test
-
-class FlowGuideTest {
--->
+<!--- TEST_NAME FlowGuideTest -->
**Table of contents**
@@ -60,7 +44,7 @@
* [Launching flow](#launching-flow)
* [Flow and Reactive Streams](#flow-and-reactive-streams)
-<!--- END_TOC -->
+<!--- END -->
## Asynchronous Flow
diff --git a/docs/knit.code.include b/docs/knit.code.include
new file mode 100644
index 0000000..42f2b50
--- /dev/null
+++ b/docs/knit.code.include
@@ -0,0 +1,6 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from ${file.name} by Knit tool. Do not edit.
+package ${knit.package}.${knit.name}
\ No newline at end of file
diff --git a/docs/knit.properties b/docs/knit.properties
new file mode 100644
index 0000000..ab2508a
--- /dev/null
+++ b/docs/knit.properties
@@ -0,0 +1,22 @@
+#
+# Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+#
+
+knit.package=kotlinx.coroutines.guide
+knit.dir=../kotlinx-coroutines-core/jvm/test/guide/
+knit.pattern=example-[a-zA-Z0-9-]+-##\\.kt
+knit.include=knit.code.include
+
+test.package=kotlinx.coroutines.guide.test
+test.dir=../kotlinx-coroutines-core/jvm/test/guide/test/
+test.template=knit.test.template
+
+# Various test validation modes and their corresponding methods from TestUtil
+test.mode.=verifyLines
+test.mode.STARTS_WITH=verifyLinesStartWith
+test.mode.ARBITRARY_TIME=verifyLinesArbitraryTime
+test.mode.FLEXIBLE_TIME=verifyLinesFlexibleTime
+test.mode.FLEXIBLE_THREAD=verifyLinesFlexibleThread
+test.mode.LINES_START_UNORDERED=verifyLinesStartUnordered
+test.mode.LINES_START=verifyLinesStart
+test.mode.EXCEPTION=verifyExceptions
\ No newline at end of file
diff --git a/docs/knit.test.template b/docs/knit.test.template
new file mode 100644
index 0000000..a912555
--- /dev/null
+++ b/docs/knit.test.template
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from ${file.name} by Knit tool. Do not edit.
+package ${test.package}
+
+import org.junit.Test
+
+class ${test.name} {
+<#list cases as case><#assign method = test["mode.${case.param}"]!"custom">
+ @Test
+ fun test${case.name}() {
+ test("${case.name}") { ${case.knit.package}.${case.knit.name}.main() }<#if method != "custom">.${method}(
+<#list case.lines as line>
+ "${line?j_string}"<#sep>,</#sep>
+</#list>
+ )
+<#else>.also { lines ->
+ check(${case.param})
+ }
+</#if>
+ }
+<#sep>
+
+</#list>
+}
\ No newline at end of file
diff --git a/docs/select-expression.md b/docs/select-expression.md
index f36fa09..5809e7b 100644
--- a/docs/select-expression.md
+++ b/docs/select-expression.md
@@ -1,21 +1,4 @@
-<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
-/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.$$1$$2
--->
-<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
-<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/SelectGuideTest.kt
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.test
-
-import org.junit.Test
-
-class SelectGuideTest {
--->
-
+<!--- TEST_NAME SelectGuideTest -->
**Table of contents**
@@ -28,9 +11,7 @@
* [Selecting deferred values](#selecting-deferred-values)
* [Switch over a channel of deferred values](#switch-over-a-channel-of-deferred-values)
-<!--- END_TOC -->
-
-
+<!--- END -->
## Select Expression (experimental)
diff --git a/docs/shared-mutable-state-and-concurrency.md b/docs/shared-mutable-state-and-concurrency.md
index 30d7334..1a3c406 100644
--- a/docs/shared-mutable-state-and-concurrency.md
+++ b/docs/shared-mutable-state-and-concurrency.md
@@ -1,20 +1,5 @@
-<!--- INCLUDE .*/example-([a-z]+)-([0-9a-z]+)\.kt
-/*
- * Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
- */
-
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.$$1$$2
--->
-<!--- KNIT ../kotlinx-coroutines-core/jvm/test/guide/.*\.kt -->
-<!--- TEST_OUT ../kotlinx-coroutines-core/jvm/test/guide/test/SharedStateGuideTest.kt
-// This file was automatically generated from coroutines-guide.md by Knit tool. Do not edit.
-package kotlinx.coroutines.guide.test
-
-import org.junit.Test
-
-class SharedStateGuideTest {
--->
+<!--- TEST_NAME SharedStateGuideTest -->
+
**Table of contents**
<!--- TOC -->
@@ -28,7 +13,7 @@
* [Mutual exclusion](#mutual-exclusion)
* [Actors](#actors)
-<!--- END_TOC -->
+<!--- END -->
## Shared mutable state and concurrency