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
dependencies {
implementation("org.pkl-lang:pkl-core:0.26.3")
}
repositories {
mavenCentral()
}
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:
<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.