mirror of
https://github.com/apple/pkl.git
synced 2026-03-20 00:04:05 +01:00
Initial commit
This commit is contained in:
Peter Niederwieser
33
docs/modules/kotlin-binding/examples/KotlinConfigExample.kt
Normal file
33
docs/modules/kotlin-binding/examples/KotlinConfigExample.kt
Normal file
@@ -0,0 +1,33 @@
|
||||
@file:Suppress("UNUSED_VARIABLE")
|
||||
|
||||
import org.pkl.config.java.ConfigEvaluator
|
||||
import org.pkl.config.kotlin.forKotlin
|
||||
import org.pkl.config.kotlin.to
|
||||
import org.junit.jupiter.api.Test
|
||||
|
||||
// the pkl/pkl-examples repo has a similar example
|
||||
class KotlinConfigExample {
|
||||
@Test
|
||||
fun usage() {
|
||||
// tag::usage[]
|
||||
val evaluator = ConfigEvaluator.preconfigured().forKotlin() // <1>
|
||||
val config = evaluator.use { // <2>
|
||||
it.evaluateText("""pigeon { age = 5; diet = "Seeds" }""")
|
||||
}
|
||||
val pigeon = config["pigeon"] // <3>
|
||||
val age = pigeon["age"].to<Int>() // <4>
|
||||
val hobbies = pigeon["diet"].to<List<String>>() // <5>
|
||||
// end::usage[]
|
||||
}
|
||||
|
||||
@Test
|
||||
fun nullable() {
|
||||
// tag::nullable[]
|
||||
val evaluator = ConfigEvaluator.preconfigured().forKotlin()
|
||||
val config = evaluator.use {
|
||||
it.evaluateText("name = null") // <1>
|
||||
}
|
||||
val name = config["name"].to<String?>() // <2>
|
||||
// end::nullable[]
|
||||
}
|
||||
}
|
||||
130
docs/modules/kotlin-binding/pages/codegen.adoc
Normal file
130
docs/modules/kotlin-binding/pages/codegen.adoc
Normal file
@@ -0,0 +1,130 @@
|
||||
= Kotlin Code Generator
|
||||
include::ROOT:partial$component-attributes.adoc[]
|
||||
:uri-pkl-codegen-kotlin-maven-module: {uri-maven-docsite}/artifact/org.pkl-lang/pkl-codegen-kotlin
|
||||
|
||||
The Kotlin source code generator reads Pkl classes and generates corresponding Kotlin classes with equally named properties.
|
||||
|
||||
Together with xref:java-binding:pkl-config-java.adoc#object-mapping[Object Mapping], code generation provides a complete solution for consuming Pkl configuration as statically typed Kotlin objects.
|
||||
Kotlin code never drifts from the configuration structure defined in Pkl, and the entire configuration tree can be code-completed in Kotlin IDEs.
|
||||
|
||||
== Installation
|
||||
|
||||
The code generator is offered as Gradle plugin, Java library, and CLI.
|
||||
|
||||
=== Gradle Plugin
|
||||
|
||||
See xref:pkl-gradle:index.adoc#installation[Installation] in the Gradle plugin chapter.
|
||||
|
||||
[[install-library]]
|
||||
=== Java Library
|
||||
|
||||
The `pkl-codegen-kotlin` library is available {uri-pkl-codegen-kotlin-maven-module}[from Maven Central].
|
||||
It requires Java 8 or higher and Kotlin 1.3 or higher.
|
||||
|
||||
==== Gradle
|
||||
|
||||
To use the library in a Gradle project, declare the following dependency:
|
||||
|
||||
[tabs]
|
||||
====
|
||||
Groovy::
|
||||
+
|
||||
.build.gradle
|
||||
[source,groovy,subs="+attributes"]
|
||||
----
|
||||
dependencies {
|
||||
compile "org.pkl-lang:pkl-config-kotlin:{pkl-artifact-version}"
|
||||
}
|
||||
|
||||
ifndef::is-release-build[]
|
||||
repositories {
|
||||
maven { url "{uri-sonatype}" }
|
||||
}
|
||||
endif::[]
|
||||
----
|
||||
|
||||
Kotlin::
|
||||
+
|
||||
.build.gradle.kts
|
||||
[source,kotlin,subs="+attributes"]
|
||||
----
|
||||
dependencies {
|
||||
compile("org.pkl-lang:pkl-config-kotlin:{pkl-artifact-version}")
|
||||
}
|
||||
|
||||
ifndef::is-release-build[]
|
||||
repositories {
|
||||
maven { url = uri("{uri-sonatype}") }
|
||||
}
|
||||
endif::[]
|
||||
----
|
||||
====
|
||||
|
||||
==== Maven
|
||||
|
||||
To use the library in a Maven project, declare the following dependency:
|
||||
|
||||
.pom.xml
|
||||
[source,xml,subs="+attributes"]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.pkl-lang</groupId>
|
||||
<artifactId>pkl-codegen-kotlin</artifactId>
|
||||
<version>{pkl-artifact-version}</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
[[install-cli]]
|
||||
=== CLI
|
||||
|
||||
The CLI is bundled with the library.
|
||||
As we do not currently ship the CLI as a self-contained Jar, we recommend to provision it with a Maven compatible build tool as shown in <<install-library>>.
|
||||
|
||||
[[usage]]
|
||||
== Usage
|
||||
|
||||
The code generator is offered as Gradle plugin, Java library, and CLI.
|
||||
|
||||
=== Gradle Plugin
|
||||
|
||||
See xref:pkl-gradle:index.adoc#kotlin-code-gen[Kotlin Code Generation] in the Gradle plugin chapter.
|
||||
|
||||
=== Java Library
|
||||
|
||||
The library offers two APIs: a high-level API that corresponds to the CLI, and a lower-level API that provides additional features and control.
|
||||
The entry points for these APIs are `org.pkl.codegen.kotlin.CliKotlinCodeGenerator` and `org.pkl.codegen.kotlin.KotlinCodeGenerator`, respectively.
|
||||
For more information, refer to the KDoc documentation.
|
||||
|
||||
=== CLI
|
||||
|
||||
As mentioned in <<install-cli,Installation>>, the CLI is bundled with the library.
|
||||
To run the CLI, execute the library Jar or its `org.pkl.codegen.kotlin.Main` main class.
|
||||
|
||||
*Synopsis:* `java -cp <classpath> -jar pkl-codegen-kotlin.jar [<options>] <modules>`
|
||||
|
||||
`<modules>`::
|
||||
The absolute or relative URIs of the modules to generate classe for.
|
||||
Relative URIs are resolved against the working directory.
|
||||
|
||||
==== Options
|
||||
|
||||
.--generate-kdoc
|
||||
[%collapsible]
|
||||
====
|
||||
Default: (flag not set) +
|
||||
Flag that indicates to generate Kdoc based on doc comments for Pkl modules, classes, and properties.
|
||||
====
|
||||
|
||||
Common code generator options:
|
||||
|
||||
include::../../java-binding/partials/cli-codegen-options.adoc[]
|
||||
|
||||
Common CLI options:
|
||||
|
||||
include::../../pkl-cli/partials/cli-common-options.adoc[]
|
||||
|
||||
[[full-example]]
|
||||
== Full Example
|
||||
|
||||
For a ready-to-go example with full source code,
|
||||
see link:{uri-codegen-kotlin-example}[codegen-kotlin] in the _pkl/pkl-examples_ repository.
|
||||
3
docs/modules/kotlin-binding/pages/index.adoc
Normal file
3
docs/modules/kotlin-binding/pages/index.adoc
Normal file
@@ -0,0 +1,3 @@
|
||||
= Integration with Kotlin
|
||||
|
||||
Pkl provides rich integration with Kotlin. Our integration allows you to embed the Pkl runtime into your Kotlin application, and also provides code generation for from Pkl source code.
|
||||
117
docs/modules/kotlin-binding/pages/pkl-config-kotlin.adoc
Normal file
117
docs/modules/kotlin-binding/pages/pkl-config-kotlin.adoc
Normal file
@@ -0,0 +1,117 @@
|
||||
= pkl-config-kotlin Library
|
||||
include::ROOT:partial$component-attributes.adoc[]
|
||||
:uri-pkl-config-kotlin-maven-module: {uri-maven-docsite}/artifact/org.pkl-lang/pkl-config-kotlin
|
||||
:uri-pkl-config-kotlin-main-sources: {uri-github-tree}/pkl-config-kotlin/src/main/kotlin/org/pkl/kotlin
|
||||
:uri-pkl-config-kotlin-test-sources: {uri-github-tree}/pkl-config-kotlin/src/test/kotlin/org/pkl/kotlin
|
||||
:uri-pkl-config-kotlin-ConverterFactories: {uri-pkl-config-kotlin-main-sources}/ConverterFactories.kt
|
||||
:uri-pkl-config-kotlin-ConfigExtensions: {uri-pkl-config-kotlin-main-sources}/ConfigExtensions.kt
|
||||
|
||||
The _pkl-config-kotlin_ library extends xref:java-binding:pkl-config-java.adoc[pkl-config-java] with Kotlin specific extension methods and object converters.
|
||||
We recommend that Kotlin projects depend on this library instead of _pkl-config-java_.
|
||||
|
||||
== Installation
|
||||
|
||||
The _pkl-config-kotlin_ library is available {uri-pkl-config-kotlin-maven-module}[from Maven Central].
|
||||
It requires Java 11 or higher and Kotlin 1.5 or higher.
|
||||
|
||||
=== Gradle
|
||||
|
||||
To use the library in a Gradle project, declare the following dependency:
|
||||
|
||||
[tabs]
|
||||
====
|
||||
Groovy::
|
||||
+
|
||||
.build.gradle
|
||||
[source,groovy,subs="+attributes"]
|
||||
----
|
||||
dependencies {
|
||||
compile "org.pkl-lang:pkl-config-kotlin:{pkl-artifact-version}"
|
||||
}
|
||||
|
||||
ifndef::is-release-build[]
|
||||
repositories {
|
||||
maven { url "{uri-sonatype}" }
|
||||
}
|
||||
endif::[]
|
||||
----
|
||||
|
||||
Kotlin::
|
||||
+
|
||||
.build.gradle.kts
|
||||
[source,kotlin,subs="+attributes"]
|
||||
----
|
||||
dependencies {
|
||||
compile("org.pkl-lang:pkl-config-kotlin:{pkl-artifact-version}")
|
||||
}
|
||||
|
||||
ifndef::is-release-build[]
|
||||
repositories {
|
||||
maven { url = uri("{uri-sonatype}") }
|
||||
}
|
||||
endif::[]
|
||||
----
|
||||
====
|
||||
|
||||
=== Maven
|
||||
|
||||
To use the library in a Maven project, declare the following dependency:
|
||||
|
||||
.pom.xml
|
||||
[source,xml,subs="+attributes"]
|
||||
----
|
||||
<project>
|
||||
<dependency>
|
||||
<groupId>org.pkl-lang</groupId>
|
||||
<artifactId>pkl-config-kotlin</artifactId>
|
||||
<version>{pkl-artifact-version}</version>
|
||||
</dependency>
|
||||
ifndef::is-release-build[]
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>sonatype-s01</id>
|
||||
<name>Sonatype S01</name>
|
||||
<url>{uri-sonatype}</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
endif::[]
|
||||
</project>
|
||||
----
|
||||
|
||||
== Usage
|
||||
|
||||
Below is the Kotlin version of the Java xref:java-binding:pkl-config-java.adoc#config-evaluator-java-example[ConfigEvaluator] example.
|
||||
Differences to the Java version are called out.
|
||||
|
||||
[source,kotlin,indent=0]
|
||||
----
|
||||
include::{examplesdir}/KotlinConfigExample.kt[tags=usage]
|
||||
----
|
||||
<1> Use the `forKotlin()` method to preconfigure the builder with Kotlin specific conversions.
|
||||
In particular, `forKotlin()` eliminates the need to annotate constructor parameters of Kotlin classes and Kotlin data classes with `@Named`.
|
||||
<2> The evaluator should be closed once it is no longer needed.
|
||||
Here this is done with a Kotlin `use {}` expression.
|
||||
Any data returned by the evaluator before calling `close()` remains valid.
|
||||
<3> Navigate to the `"pigeon"` child.
|
||||
The subscript notation is shorthand for `config.get("pigeon")`.
|
||||
<4> Convert `"age"` to `Int` with the `Config.to()` extension method.
|
||||
The target type is provided as a type argument.
|
||||
Always use `Config.to()` instead of `Config.as()` in Kotlin.
|
||||
<5> `Config.to()` makes conversions to parameterized types straightforward:
|
||||
`to<List<String>>()` instead of `as(JavaType.listOf(String::class.java))`.
|
||||
|
||||
For properties that are allowed to be `null`, convert to a nullable type:
|
||||
|
||||
[source,kotlin,indent=0]
|
||||
----
|
||||
include::{examplesdir}/KotlinConfigExample.kt[tags=nullable]
|
||||
----
|
||||
<1> To indicate that `null` is an allowed value, convert to the nullable type `String?`.
|
||||
Converting to `String` would result in a `ConversionException`.
|
||||
|
||||
For a ready-to-go example with full source code,
|
||||
see link:{uri-config-kotlin-example}[config-kotlin] in the _pkl/pkl-examples_ repository.
|
||||
|
||||
== Further Information
|
||||
|
||||
Refer to the Javadoc and sources published with the library, or browse the library's {uri-pkl-config-kotlin-main-sources}[main] and {uri-pkl-config-kotlin-test-sources}[test] sources.
|
||||
Reference in New Issue
Block a user