Kotlin Code Generator

The Kotlin source code generator reads Pkl classes and generates corresponding Kotlin classes with equally named properties.

Together with 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 Installation in the Gradle plugin chapter.

Java Library

The pkl-codegen-kotlin library is available from Maven Central. It requires Java 11 or higher and Kotlin 1.3 or higher.

Gradle

To use the library in a Gradle project, declare the following dependency:

Groovy
Kotlin

build.gradle

dependencies {
  compile "org.pkl-lang:pkl-codegen-kotlin:0.25.3"
}

repositories {
  mavenCentral()
}

build.gradle.kts

dependencies {
  compile("org.pkl-lang:pkl-codegen-kotlin:0.25.3")
}

repositories {
  mavenCentral()
}

Maven

To use the library in a Maven project, declare the following dependency:

pom.xml

<dependency>
  <groupId>org.pkl-lang</groupId>
  <artifactId>pkl-codegen-kotlin</artifactId>
  <version>0.25.3</version>
</dependency>

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 Java Library.

Usage

The code generator is offered as Gradle plugin, Java library, and CLI.

Gradle Plugin

See 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 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

Default: (flag not set)
Flag that indicates to generate Kdoc based on doc comments for Pkl modules, classes, and properties.

Common code generator options:

--indent

Default: " " (two spaces)
Example: "\t" (one tab)
The characters to use for indenting generated source code.

-o, --output-dir

Default: (not set)
Example: generated/
The directory where generated source code is placed. Relative paths are resolved against the working directory.

--generate-spring-boot

Default: (not set)
Flag that indicates to generate config classes for use with Spring Boot.

Common CLI options:

--allowed-modules

Default: pkl:,file:,modulepath:,https:,repl:,package:,projectpackage:
Comma-separated list of URI patterns that determine which modules can be loaded and evaluated. Patterns are matched against the beginning of module URIs. (File paths have been converted to file: URLs at this stage.) At least one pattern needs to match for a module to be loadable. Both source modules and transitive modules are subject to this check.

--allowed-resources

Default: env:,prop:,package:,projectpackage:
Comma-separated list of URI patterns that determine which external resources can be read. Patterns are matched against the beginning of resource URIs. At least one pattern needs to match for a resource to be readable.

--cache-dir

Default: ~/.pkl/cache
Example: /path/to/module/cache/
The cache directory for storing packages.

--no-cache

Disable cacheing of packages.

-e, --env-var

Default: OS environment variables for the current process
Example: MY_VAR=myValue
Sets an environment variable that can be read by Pkl code with read("env:<envVarName>"). Repeat this option to set multiple environment variables.

-h, --help

Display help information.

--module-path

Default: (empty)
Example: dir1:zip1.zip:jar1.jar
Directories, ZIP archives, or JAR archives to search when resolving modulepath: URIs. Paths are separated by the platform-specific path separator (: on *nix, ; on Windows). Relative paths are resolved against the working directory.

-p, --property

Default: (none)
Example: myProp=myValue
Sets an external property that can be read by Pkl code with read("prop:<propertyName>"). Repeat this option to set multiple external properties.

--root-dir

Default: (none)
Example: /some/path
Root directory for file: modules and resources. If set, access to file-based modules and resources is restricted to those located under the specified root directory. Any symlinks are resolved before this check is performed.

--settings

Default: (none)
Example: mySettings.pkl
File path of the Pkl settings file to use. If not set, ~/.pkl/settings.pkl or defaults specified in the pkl.settings standard library module are used.

-t, --timeout

Default: (none)
Example: 30
Duration, in seconds, after which evaluation of a source module will be timed out. Note that a timeout is treated the same as a program error in that any subsequent source modules will not be evaluated.

-v, --version

Display version information.

-w, --working-dir

Base path that relative module paths passed as command-line arguments are resolved against. Defaults to the current working directory.

--ca-certificates

Default: (none)
Example: /some/path/certificates.pem
Path to a file containing CA certificates to be used for TLS connections.

Setting this option replaces the existing set of CA certificates bundled into the CLI. Certificates need to be X.509 certificates in PEM format.

For other methods of configuring certificates, see CA Certificates.

Full Example

For a ready-to-go example with full source code, see codegen-kotlin in the pkl/pkl-examples repository.