mirror of
https://github.com/apple/pkl.git
synced 2026-03-17 23:03:54 +01:00
b5208a2b5b
* Swap Kotlin/Groovy tab order in documentation * Use Kotlin DSL repository extension function
134 lines
4.7 KiB
Plaintext
134 lines
4.7 KiB
Plaintext
= pkl-core Library
|
|
include::ROOT:partial$component-attributes.adoc[]
|
|
:uri-pkl-core-maven-module: {uri-maven-docsite}/artifact/org.pkl-lang/pkl-core
|
|
:uri-pkl-core-main-sources: {uri-github-tree}/pkl-core/src/main/java/org/pkl/core
|
|
:uri-pkl-core-test-sources: {uri-github-tree}/pkl-core/src/test/kotlin/org/pkl/core
|
|
:uri-pkl-core-Evaluator: {uri-pkl-core-main-sources}/Evaluator.java
|
|
:uri-pkl-core-PModule: {uri-pkl-core-main-sources}/PModule.java
|
|
:uri-pkl-core-PklException: {uri-pkl-core-main-sources}/PklException.java
|
|
:uri-pkl-core-ValueVisitor: {uri-pkl-core-main-sources}/ValueVisitor.java
|
|
:uri-pkl-core-JsonRenderer: {uri-pkl-core-main-sources}/JsonRenderer.java
|
|
:uri-pkl-core-PcfRenderer: {uri-pkl-core-main-sources}/PcfRenderer.java
|
|
:uri-pkl-core-PListRenderer: {uri-pkl-core-main-sources}/PListRenderer.java
|
|
:uri-pkl-core-YamlRenderer: {uri-pkl-core-main-sources}/YamlRenderer.java
|
|
:uri-pkl-core-SecurityManagers: {uri-pkl-core-main-sources}/SecurityManagers.java
|
|
:uri-pkl-core-ModuleKeyFactories: {uri-pkl-core-main-sources}/module/ModuleKeyFactories.java
|
|
|
|
The _pkl-core_ library contains the Pkl parser, evaluator, REPL server, and xref:ROOT:standard-library.adoc[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.
|
|
|
|
[[pkl-core-installation]]
|
|
== Installation
|
|
|
|
The _pkl-core_ library is available {uri-pkl-core-maven-module}[from Maven Central].
|
|
It requires Java 17 or higher.
|
|
|
|
=== Gradle
|
|
|
|
To use the library in a Gradle project, declare the following dependency:
|
|
|
|
[tabs]
|
|
====
|
|
Kotlin::
|
|
+
|
|
.build.gradle.kts
|
|
[source,kotlin,subs="+attributes"]
|
|
----
|
|
dependencies {
|
|
implementation("org.pkl-lang:pkl-core:{pkl-artifact-version}")
|
|
}
|
|
|
|
repositories {
|
|
ifdef::is-release-version[]
|
|
mavenCentral()
|
|
endif::[]
|
|
ifndef::is-release-version[]
|
|
maven(url = "{uri-sonatype}")
|
|
endif::[]
|
|
}
|
|
----
|
|
|
|
Groovy::
|
|
+
|
|
.build.gradle
|
|
[source,groovy,subs="+attributes"]
|
|
----
|
|
dependencies {
|
|
implementation "org.pkl-lang:pkl-core:{pkl-artifact-version}"
|
|
}
|
|
|
|
repositories {
|
|
ifdef::is-release-version[]
|
|
mavenCentral()
|
|
endif::[]
|
|
ifndef::is-release-version[]
|
|
maven { url "{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-core</artifactId>
|
|
<version>{pkl-artifact-version}</version>
|
|
</dependency>
|
|
ifndef::is-release-version[]
|
|
<repositories>
|
|
<repository>
|
|
<id>sonatype-s01</id>
|
|
<name>Sonatype S01</name>
|
|
<url>{uri-sonatype}</url>
|
|
</repository>
|
|
</repositories>
|
|
endif::[]
|
|
</project>
|
|
----
|
|
|
|
== Usage
|
|
|
|
{uri-pkl-core-Evaluator}[`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 {uri-pkl-core-PModule}[`PModule`] object representing the fully evaluated module is returned.
|
|
Otherwise, an {uri-pkl-core-PklException}[`PklException`] with error details is thrown.
|
|
|
|
Let's look at an example:
|
|
|
|
[[config-evaluator-core-example]]
|
|
[source,java,indent=0]
|
|
----
|
|
include::{examplesdir}/CoreEvaluatorExample.java[tags=usage]
|
|
----
|
|
<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.
|
|
|
|
[[value-visitor]]
|
|
Often, {uri-pkl-core-ValueVisitor}[`ValueVisitor`] is a better way to process a module.
|
|
See {uri-pkl-core-PcfRenderer}[`PcfRenderer`], {uri-pkl-core-JsonRenderer}[`JsonRenderer`], {uri-pkl-core-YamlRenderer}[`YamlRenderer`] and {uri-pkl-core-PListRenderer}[`PListRenderer`] for examples.
|
|
|
|
[[security-manager-spi]]
|
|
The (Pkl, not Java) security manager can be configured and customized using {uri-pkl-core-SecurityManagers}[`SecurityManagers`] and related classes.
|
|
|
|
[[module-loader-spi]]
|
|
Module loaders can be configured and customized using {uri-pkl-core-ModuleKeyFactories}[`ModuleKeyFactories`] and related classes.
|
|
|
|
== Further Information
|
|
|
|
Refer to the Javadoc and sources published with the library, or browse the library's {uri-pkl-core-main-sources}[main] and {uri-pkl-core-test-sources}[test] sources.
|