pkl-core Library

The pkl-core library contains the Pkl parser, evaluator, REPL server, and Standard Library. It is the foundation for most of Pkl’s other libraries and tools. The library can also be used to embed Pkl in Java libraries and applications.

Installation

The pkl-core library is available from Maven Central. It requires Java 17 or higher.

Gradle

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

Kotlin
Groovy

build.gradle.kts

dependencies {
  implementation("org.pkl-lang:pkl-core:0.26.3")
}

repositories {
  mavenCentral()
}

build.gradle

dependencies {
  implementation "org.pkl-lang:pkl-core:0.26.3"
}

repositories {
  mavenCentral()
}

Maven

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

pom.xml

<project>
  <dependency>
    <groupId>org.pkl-lang</groupId>
    <artifactId>pkl-core</artifactId>
    <version>0.26.3</version>
  </dependency>
</project>

Usage

Evaluator is the core evaluator that exposes multiple methods of evaluation.

The main evaluation method is evaluate, which returns a Java representation of the Pkl module object. If evaluation succeeds, a PModule object representing the fully evaluated module is returned. Otherwise, an PklException with error details is thrown.

Let’s look at an example:

PModule module;
try (var evaluator =
  Evaluator.preconfigured()) { (1)
  module = evaluator.evaluate(
    ModuleSource.text("pigeon { age = 30; hobbies = List(\"swimming\", \"surfing\") }")); (2)
}
var pigeon = (PObject) module.get("pigeon"); (3)
var className = pigeon.getClassInfo().getQualifiedName(); (4)
var hobbies = (List<String>) pigeon.get("hobbies"); (5)

1	Build an `Evaluator` with default configuration. The evaluator should be closed once it is no longer needed. In this example, this is done with a try-with-resources statement. Note that objects returned by the evaluator remain valid after calling `close()`.
2	Build a `ModuleSource` using the given text as the module’s contents. Evaluate the given module source. Alternatively, it’s possible to build a `ModuleSource` from a file, path, uri, and other sources.
3	Get the module’s `"pigeon"` property, which is represented as `PObject` in Java.
4	Get the class name for this object. In this example, the class name is `pkl.base#Dynamic`.
5	Get pigeon’s `"diet"` property, which is represented as `List<String>` in Java.

Often, ValueVisitor is a better way to process a module. See PcfRenderer, JsonRenderer, YamlRenderer and PListRenderer for examples.

The (Pkl, not Java) security manager can be configured and customized using SecurityManagers and related classes.

Module loaders can be configured and customized using ModuleKeyFactories and related classes.

Further Information

Refer to the Javadoc and sources published with the library, or browse the library’s main and test sources.