This makes various improvements to the handling of frame slot vars, and
includes some bug fixes introduced by
https://github.com/apple/pkl/pull/1622
* Refactor SymbolTable to track for-generator and parameter slots in
each scope
* Execute let expressions in their own root node in some places
* Unify how frame slots are managed; they are all represented as
`FrameSlotVariable`, created in `AstBuilder`, and passed into
`SymbolTable`.
* Fix how let expressions are executed in custom this scopes (introduce
a new root node when needed)
Fixes#1614.
## Context
A non-abstract `class` (or `module`) was allowed to declare `abstract`
properties and methods.
Because such an enclosing type is instantiable, an `abstract` member
there can never be guaranteed
an implementation — so the contradiction surfaced only as a runtime
error when the member was
accessed (`Cannot invoke abstract method`), or not at all.
This makes it a compile-time error to declare an `abstract` member
unless its enclosing class or
module is also `abstract`. This is consistent with how Pkl already
rejects instantiating an abstract
class, and mirrors how Java and Kotlin treat abstract members.
## Before
```pkl
class Foo {
abstract bar: Int
}
res = new Foo { bar = 5 } // evaluated successfully (should fail)
```
```pkl
class Foo {
abstract function bar(): Int
}
res = new Foo {} // evaluated successfully; res.bar() failed only at runtime
```
## After
```
–– Pkl Error ––
Cannot define an abstract member in a non-abstract class.
2 | abstract bar: Int
^^^^^^^^
at Foo
A member can only be `abstract` if its enclosing class is also `abstract`.
```
## Implementation
- `AstBuilder` now validates, while building the AST, that a
non-abstract class/module declares no
`abstract` members. The check runs in both `visitClass` and
`visitModule`, and the error points at
the `abstract` keyword.
- Adds the `abstractMemberInNonAbstractClass` error message.
## Scope: classes and modules
The issue describes classes; I applied the same rule to modules as well,
since a module is a class
in Pkl and a non-abstract module is likewise directly evaluatable. Happy
to narrow this to classes
only if you'd prefer — it's a one-line change either way.
The `moduleMethodModifiers` pkl-doc test fixture declared an abstract
method at non-abstract module
level (relying on the old behavior); it's updated to an `abstract
module`, and its expected
documentation output is regenerated.
## Tests
- New `LanguageSnippetTests` error cases: abstract property in a class,
abstract method in a class,
and abstract member in a module.
- `./gradlew build` passes (`pkl-core` and `pkl-doc` included).
---------
Co-authored-by: Vinayak <vinayak@vama.app>
Co-authored-by: Daniel Chao <daniel.h.chao@gmail.com>
This implements HTTP redirect following ourselves.
The goal is:
1. All I/O is checked against `--allowed-resources` and
`--allowed-modules`, including HTTP redirects
2. HTTP rewrite rules can affect redirect following
3. HTTP headers can affect redirect following
---------
Co-authored-by: Islon Scherer <islonscherer@gmail.com>
This reverts the commits that enabled Gradle's configuration cache
feature.
IMO: this feature is too hard to use. We don't know if a task is valid
for the configuration cache until it runs, and it's very hard to tell if
something is safe when authoring Gradle code.
For example, our publish tasks are currently failing; I don't know how I
would fix this without running the publish task again on my dev machine.
Also, some of our build scripts become more brittle because of this; for
example, see
https://github.com/apple/pkl/blob/bb07589eae0b3195a589559a3245cbc12c29b394/build-logic/src/main/kotlin/BuildInfo.kt#L291-L296
The added snippet test originally produced error "A value of type
`Function2` cannot be exported."
This PR actually fixes the bug twice:
* By marking `ConvertProperty.render` as `hidden` so that it is skipped
when the enclosing object is exported. This broke any attempts to obtain
the module schema because this requires exporting all annotations on all
class properties.
* By changing the way that `VmUndefinedValueException.fillInHint()`
obtains the module URI to avoid obtaining the module schema (and
triggering the more expensive module schema generation process).
It also makes function-typed annotation properties in `pkl:Command` hidden to avoid similar issues there.
Bumps `shadowPlugin` from 9.4.1 to 9.4.2.
Updates `com.gradleup.shadow:com.gradleup.shadow.gradle.plugin` from
9.4.1 to 9.4.2
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/GradleUp/shadow/releases">com.gradleup.shadow:com.gradleup.shadow.gradle.plugin's
releases</a>.</em></p>
<blockquote>
<h2>9.4.2</h2>
<h3>Changed</h3>
<ul>
<li>Update jdependency to support Java 27. (<a
href="https://redirect.github.com/GradleUp/shadow/pull/2033">#2033</a>)</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/GradleUp/shadow/commit/29c432a7b6824b6fef23d46dc067e5c14112ff90"><code>29c432a</code></a>
Prepare version 9.4.2</li>
<li><a
href="https://github.com/GradleUp/shadow/commit/8aa8e6c1fb2ac0c17f0ff77e521cbe599cf64245"><code>8aa8e6c</code></a>
Update dependency org.vafer:jdependency to v2.16 (<a
href="https://redirect.github.com/GradleUp/shadow/issues/2033">#2033</a>)</li>
<li>See full diff in <a
href="https://github.com/GradleUp/shadow/compare/9.4.1...9.4.2">compare
view</a></li>
</ul>
</details>
<br />
Updates `com.gradleup.shadow` from 9.4.1 to 9.4.2
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/GradleUp/shadow/releases">com.gradleup.shadow's
releases</a>.</em></p>
<blockquote>
<h2>9.4.2</h2>
<h3>Changed</h3>
<ul>
<li>Update jdependency to support Java 27. (<a
href="https://redirect.github.com/GradleUp/shadow/pull/2033">#2033</a>)</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="https://github.com/GradleUp/shadow/commit/29c432a7b6824b6fef23d46dc067e5c14112ff90"><code>29c432a</code></a>
Prepare version 9.4.2</li>
<li><a
href="https://github.com/GradleUp/shadow/commit/8aa8e6c1fb2ac0c17f0ff77e521cbe599cf64245"><code>8aa8e6c</code></a>
Update dependency org.vafer:jdependency to v2.16 (<a
href="https://redirect.github.com/GradleUp/shadow/issues/2033">#2033</a>)</li>
<li>See full diff in <a
href="https://github.com/GradleUp/shadow/compare/9.4.1...9.4.2">compare
view</a></li>
</ul>
</details>
<br />
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)
</details>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
This introduces breaking changes for external readers are loaded:
1. In PklProject, relative paths are resolved relative to the enclosing
PklProject file (make behavior consistent with how other settings work)
2. Make CLI flags blow away any settings set on a PklProject
3. Introduce a new `workingDir` property, which defaults to the
PklProject dir
The overall goal is to make this behavior consistent with how other
settings work.
For example, relative paths for other evaluator settings are already
relative to the project directory.
Additionally, in every other case, CLI flags will overwrite any setting
set within PklProject.
Previously, `VmDynamic.isHiddenOrLocalProperty` didn't correctly
identify locals whose cache key is an `ObjectMember` instead of an
`Identifier`, causing `VmDynamic. getRegularMemberCount` to return an
incorrect value. This caused some renderers to produce incorrect output.
Resolves#1631
This introduces an optimization to write let expressions to frame slots
of the current frame, rather than transforming them into lambdas. As a
result, let expressions are _much_ faster to execute.
Fixes the following error:
```
A problem was found with the configuration of task ':pkl-core:sourcesJar' (type 'Jar').
Deprecated Gradle features were used in this build, making it incompatible with Gradle 10.
- Gradle detected a problem with the following location: '/home/runner/work/pkl/pkl/pkl-core/build/generated/sources/baseModuleMembers'.
You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.
Reason: Task ':pkl-core:sourcesJar' uses this output of task ':pkl-core:generateBaseModuleMembers' without declaring an explicit or implicit dependency. This can lead to incorrect results being produced, depending on what order the tasks are executed.
For more on this, please refer to https://docs.gradle.org/9.5.1/userguide/command_line_interface.html#sec:command_line_warnings in the Gradle documentation.
Possible solutions:
94 actionable tasks: 76 executed, 18 from cache
1. Declare task ':pkl-core:generateBaseModuleMembers' as an input of ':pkl-core:sourcesJar'.
2. Declare an explicit dependency on ':pkl-core:generateBaseModuleMembers' from ':pkl-core:sourcesJar' using Task#dependsOn.
3. Declare an explicit dependency on ':pkl-core:generateBaseModuleMembers' from ':pkl-core:sourcesJar' using Task#mustRunAfter.
```
This replaces `ResolveVariableNode` and `ResolveMethodNode` with their resolution.
When we build the truffle node tree, we determine whether names resolve to:
* lexical scope
* base module
* implicit this
Then, we use this information to directly construct the underlying nodes (`ReadPropertyNode`, `ReadLocalPropertyNode`, etc).
Additionally, `AstBuilder` determines whether the property access must be const or not.
This introduces a `BaseModuleMembers` registry, which gets generated as part of Java compilation.
Use Locale.ROOT to apply the lowecase format. For URI scheme and host
locale-neutral casing is the semantically the correct choice. Added a
unit test that sets the default locale to tr-TR and that would fail
without the fix.
- Remove single usage of @immutable without replacement
- Remove HttpClient's usages of @threadsafe without replacement
- Replace javax.annotation.concurrent.GuardedBy
with com.google.errorprone.annotations.concurrent.GuardedBy
Also:
- Remove redundant final modifiers from members of a final class
---------
Co-authored-by: odenix <self@odenix.org>
With JSpecify now a dependency of pkl-config-java, this moves the
non-null annotation to jspecify's.
This makes it simpler for users to do nullness checks, as tooling
already understands JSpecify nullness annotations.
* Relax forbidden headers constraints
- remove restriction on browser-related headers
- allow any glob pattern (no need to end with `/` or `*`, because glob
patterns already require users to explicitly declare prefix matches if
that's the intention)
* Replace `List<Pair<, ...>>`; use `Map<String, ...>` instead
* Use glob pattern strings as an API throughout, instead of `Pattern`
(e.g. in `HttpClientBuilder`)
* Add HTTP headers to message passing API
* Add HTTP headers to executor API (introduces `ExecutorSpiOptions4`)
* Add tests for Gradle, CLI, and pkl-executor invocations
* Improve documentation
* Add `isGlobPattern` API to class `String` for in-language validation
of http headers
* Behavior change: make sure explicitly configured `User-Agent` in
`HttpClientBuilder` can be shadowed by headers (allows users to set
`--http-header "**=User-Agent: My User Agent"` and for this to be the
only user agent).
CC @kyokuping
IntelliJ can understand that some annotations on fields mean that they
are implicitly initialized, which means we don't get the "field XXX is
not initialized" warning for `@LateInit` fields.
This setting, unfortunately, is recorded into `.idea/misc.xml`, which
contains a bunch of arbitrary stuff that we don't want to check into
source control
This adds some logic to touch up that file to mark `@LateInit` as
implicitly initialized fields, so we don't get any editor warnings.
Also, suppress some warnings.
Replace pkl-core's local nullness annotations with JSpecify annotations.
Enable NullAway checking for pkl-core packages except org.pkl.core.ast
and org.pkl.core.stdlib.
Notable code changes:
- Add a dedicated late-init constructor to VmTyped
- Move VmExceptionBuilder's fallback message derivation from withCause()
to build()
- Split VmException rendering between builder-provided messages and
string-backed messages
- Initialize MessageTransport handlers with default throwing handlers
- Update JSON helper collection types to allow nullable values JSON
arrays and objects can contain JSON null,
so the Java Map/List element types need to model nullable elements
explicitly
- Make public command transform APIs accept nullable transformed values
Command transforms can produce null for optional/default handling,
so the BiFunction and options-map element types now model that
explicitly
- Make ExecutorSpiException accept nullable message and cause
Existing call sites can pass nullable causes from Throwable.getCause()
- Remove JSR-305 semantics from `@LateInit`
JSpecify does not support the same type-qualifier-nickname pattern,
so `@LateInit` is now documentation plus a NullAway
constructor-initialization exemption
Out of scope:
- NullAway checking of org.pkl.core.ast and org.pkl.core.stdlib
- IntelliJ warnings related to `@LateInit` fields
- Removing the JSR-305 dependency, since concurrency annotations are
still in use
Motivation:
Config.as() causes nullness warnings when its result is intentionally assigned
to a non-null variable
Changes:
* Introduce Config.asNullable(Class<T>), asNullable(JavaType<T>), and
asNullable(Type) to explicitly opt into nullable values
* Keep the signatures of Config.as(Class<T>) and Config.as(JavaType<T>)
unchanged from 0.31 by adding @NullUnmarked
* This gives users time to migrate from as() to asNullable() where appropriate
* Avoids introducing new spurious warnings
* Change `<T> T Config.as(Type)` to `<T extends @nullable Object> T Config.as(Type)`
* This overload is typically used by reflective code such as
pkl-config-kotlin's Config.to() rather than directly by user code
* Clarify that JavaType<T> represents a non-null top-level type whose type arguments may be nullable
* Restricting <T> to non-null keeps method signatures understandable for humans and tools
* Enables full symmetry between Class<T> and JavaType<T> overloads in Config and JavaType
* Enables future non-null runtime checks in both Config.as() overloads
* Simplify construction of `JavaType`s with nullable type arguments
* Add ofNullable() variants for most factory methods, e.g., JavaType.listOfNullable()
* Overhaul Javadoc of Config and JavaType
Result:
* Clear separation between accessing nullable and non-null values
* Config.as() is used for the common non-null case
* Config.as() can perform non-null runtime checks in a future release (breaking change)
* More ergonomic construction of types with nullable type arguments
* More detailed and consistent documentation
* Fix error message when an invalid test reporter is supplied in Gradle
* Fix Gradle property name in docs
* Fix Gradle property name in tasks
* Introduce `TestReporter.default`, and use it in places where default
is applied
* Remove calls to `convention()`; this is not required because the input
is optional anyways.
When a docsite has only one package name and no DocsiteInfo.overview,
treat it like Javadoc's single-module output: redirect the top-level
index to the package page and omit the site-title breadcrumb segment
from generated pages.
Add src/test/files/SinglePackageTest fixtures to cover multiple package
versions, redirect behavior, breadcrumb behavior, and unchanged site
structure.
Also:
- Shut down Executor used in test.
- Declare expected output fixtures of DocGenerator as test inputs, not
outputs.
- Fix IntelliJ warning by using a Set for the right-hand side of
collection subtraction.
The version of local project dependencies should _always_ exactly match
up with what's declared in a PklProject.deps.json; any package in the
transitive dependency tree should always be delcaring the same import
too.
Closes#1591
run() now creates and closes a default Executor per call. This is fine
because there is no good reason to call this method multiple times.
run(Executor) now lets callers provide their own Executor, which is
customary for a well-behaved library.
Also: Fix IntelliJ warning by calling toSet()
Closes#1583
This omission, in particular, prevents Gradle plugins (which rely on CLI
classes) from adding custom resource readers via the service loading
mechanism. This change seems benign, especially since this is already
done for module key factories.
Power assertions only work when the source section is available. If it
is unavailable, power assertions throw a ParserError (unexpected EOF on
an empty input) when re-parsing the expression for presentation.
This change allows `PklProject` files, usually loaded via the `Project`
static methods, to have references to external packages via `package://`
URIs.
This is helpful for centralizing and sharing common package
configuration via packages.
ktfmt has much improved how it formats Kotlin code. Unfortunately, this
means that whenever we touch a single line in a Kotlin file, we get a
_lot_ more changes thanks to ratcheting now picking up this file for
formatting.
This PR just reformats every single Kotlin file so we don't have to deal
with this churn in future PRs that touch Kotlin code.
This is a quality-of-life improvement; make our build logs more easy to
read through for the default case.
If we need more information, we can click on the "Enable debug logging"
checkbox when re-running a job, which then populates the `runner.debug`
context variable.
Modern versions of Gradle support configuration caching
to prevent the gradual increase of project size to affect
the overall developer experience of Gradle builds. To
prepare the PKL project, and specificall pkl-gradle, for
configuration support, we introduce an integration test to
vet configuration cache rules, and then perform the necessary
updates to provide configuration cache support.
Motivation:
- `Config` mixes configuration representation with decoding logic
- `Config.fromPklBinary()` does not scale as decoding gains options
(e.g., binary versions or formats)
- The decoding API is inconsistent with `ConfigEvaluator`
Changes:
- Introduce `ConfigDecoder` (with builder) and move
`Config.fromPklBinary()` logic into it
- Deprecate `Config.fromPklBinary()` methods for removal
- Add `ConfigDecoder.forKotlin()` extension function
- Update and improve tests
Result:
- Decoding is separated from `Config` and exposed via a dedicated API
- Decoding can evolve independently (e.g., adding options such as binary
versions or supporting new formats)
- Evaluation and decoding APIs follow a consistent design
Dependabot currently does not update lockfiles in multi-module projects
(see https://github.com/dependabot/dependabot-core/issues/14633)
To work around this issue, we will simply remove our lockfiles, and
change our version catalog to use fully specified versions.
The removal of lockfiles introduces two issues:
1. It is less visible what our dependency graph is
2. Our builds are potentially non-reproducible
To work around this, two mitigations are in place:
1. Enable `failOnDynamicVersions()`, which causes Gradle to fail the
build if any dependencies declare a version range
2. Enable GitHub dependency submission, which provides insight into the
project SBOM
Fixes the following pom.xml issues:
1. pkl-doc and pkl-codegen-java sets the wrong dependency scopes for
pkl-commons-cli/pkl-base
2. pkl-config-kotlin sets the wrong dependency scope for
pkl-config-java-all
Closes#1293Closes#1517
This doesn't really make sense as part of the `Config` API.
We can maybe make class `ConfigUtils` public, but, I don't know how useful it
is anyways; it's more of an implementation detail.
Motivation:
buildSrc is a special-case legacy mechanism.
Gradle recommends using an included build named build-logic instead:
https://docs.gradle.org/current/userguide/best_practices_structuring_builds.html#favor_composite_builds
Changes:
- Rename buildSrc/ to build-logic/
- triggers reformatting
- Replace occurrences of "buildSrc" with "build-logic"
- Include the build-logic build in the main build (via
settings.gradle.kts)
- Apply convention plugins via plugin IDs instead of type-safe accessors
- small tradeoff compared to buildSrc
Result:
- Faster and more isolated builds
- Build logic behaves like a normal build, making it easier to evolve
and reason about
---------
Co-authored-by: Daniel Chao <dan.chao@apple.com>
- Enforce Kotlin version via resolution rule (replaces BOM)
- fail if kotlin-stdlib/kotlin-reflect exceed target version
- Replace kotlin-stdlib-jdk8 with kotlin-stdlib (jdk7/8 are now shims)
- Port pkl-core annotation processor to Java (with Codex)
- removes kotlin-stdlib from its compile classpath for better dependency
hygiene (Java module)
- Downgrade clikt for Kotlin 2.2 compatibility
- Upgrade kotlinx-serialization
---------
Co-authored-by: Daniel Chao <dan.chao@apple.com>
Motivation
- Enable correct NullAway analysis
- Pick up toolchain fixes and improvements
Toolchains
- Require JDK 25 for JVM toolchain (keep Java 17 runtime compatibility)
- Require Kotlin 2.3.20 for Kotlin toolchain (keep Kotlin 2.2 runtime
compatibility)
- Require JDK 25 for Gradle daemon JVM (via
gradle-daemon-jvm.properties)
- Fix javac and kotlinc warnings from toolchain upgrades
CI
- Bump GitHub workflows to JDK 25
Building Kotlin
- Bump Kotlin language level to 2.2 to match stdlib version
- Consolidate build logic into pklKotlinBase.gradle.kts
- Adopt modern Kotlin plugin syntax
- Fix new kotlinc warnings
- Update ktfmt to 0.62
- first version compatible with Kotlin 2.3.20
- changes formatting compared to 0.61
- Replace dependency resolution rule with BOM alignment
- rule was too broad and interfered with toolchain/runtime separation
Testing
- Expand matrix to JDK 25 (LTS) and 26
- Ensure each matrix task can be run independently
- Fix KotlinCodeGeneratorsTest and EmbeddedExecutorsTest on affected
JDKs
- Disable one test in CliCommandTest on affected JDKs (failure cause
unknown)
Compatibility fixes
- Fix reflective access in DocGenerator on affected JDKs
Build fixes
- Fix misuse of `task.enabled` vs. `report.required`
- Fix `gradlew tasks` on Windows
- Downgrade Spotless to 8.3.0 to (hopefully) work around sporadic
NoClassDefFoundError
Result
- NullAway runs correctly
- Broader JDK test coverage
- More reproducible and potentially faster builds
This avoids an issue where, during the course of development, a file is
touched, thus modifying the copyright year.
Then, undoing the previous change does not undo the copyright year
change.
Motivation:
Facilitate the use of the NullAway checker as part of moving to
JSpecify.
Changes:
- represent "no children" as `List.of()` instead of null
- remove obsolete `children != null` assertions
- NullAway intentionally ignores such assertions
- remove "no children" special-casing where no longer necessary
Result:
- cleaner code with similar performance
- removed a barrier to using the NullAway checker
- Remove dependency org.fusesource.jansi:jansi
- In 4.x, org.fusesource.jansi:jansi was replaced with org.jline:jansi.
Instead of adding this new dependency, this commit replaces Pkl’s single
Jansi usage with custom code that preserves existing behavior. Fixing
existing ANSI quirks is left for a future PR.
- Replace jline-terminal-ansi with jline-terminal-jni
- In 4.x, only -jni and -ffm are available (-ffm requires Java 22+)
- Configure native-image build for jline-terminal-jni
As updating JLine is delicate, I manually tested `pkl repl` and `jpkl
repl` on Windows 11 (using Windows Terminal) and on Ubuntu, and found no
issues. However, I do not have access to a macOS machine.
- Make leaf AST classes final
- Make protected Lexer fields private and add getter
- Split Parser into Parser and ParserImpl
- Using a fresh ParserImpl instance per parse simplifies reasoning
(important) and makes the Parser API thread-safe (nice to have)
- Split GenericParser into GenericParser and GenericParserImpl
- Same motivation as for Parser
Some of these changes will facilitate the move to JSpecify, which has
proven challenging for this package.
- pass `GrammarVersion` to constructor instead of passing it to each
`format` method
- replace `format(Path): String` with `format(Reader, Appendable)`
- instead of picking which overloads besides `format(String): String`
might be useful, offer a single generalized method that streams input
and output
- add `@Throws(IOException::class)` to ensure that Java callers can
catch this exception
- deprecate old methods
Prior to this change, this code would activate powers assertions /
instrumentation permanently:
```pkl
foo: String(contains("a")) | String(contains("b")) = "boo"
```
This is because the `contains("a")` constraint would fail, triggering
power assertions, but the subsequent check of the union's
`contains("b")` branch would succeed.
As observed in #1419, once instrumentation is enabled, all subsequent
evaluation slows significantly.
As with #1419, the fix here is to disable power assertions via
`VmLocalContext` until we know that all union members failed type
checking; then, each member is re-executed with power assertions allowed
to provide the improved user-facing error.
Fixes broken links and grammar in DEVELOPMENT.adoc:
- Mailing list URL: openjdk.java.net → openjdk.org (old domain returns
301)
- Truffle FAQ link: old OpenJDK wiki is gone (404) — replaced with
current GraalVM Truffle docs
- Grammar: "enables to run" → "enables you to run"
- Grammar: "jenv use specific" → "jenv uses specific"
The loop unwraps nullables and constraints but breaks straight away
after a `typealias`. This means the nullable is missed. Removing the
`break` fixes it.
## Exception
```
org.pkl.core.PklException: –– Pkl Error ––
Command option property `foo` has unsupported type `String?`.
11 | foo: OptionalString
^^^^^^^^^^^^^^^^^^^
at <unknown> (file:///var/folders/xh/lmp1n6qj4m13t53cfmbqnkwh0000gn/T/junit-1378070630576324311/cmd.pkl)
Use a supported type or define a transformEach and/or transformAll function
```
The `choices` stream was consumed eagerly for metavar construction, then
captured in a lambda for later validation—which promptly fell over with
`IllegalStateException`. Materialise to a `List` straightaway.
* Forbid overlap of built-in and command-defined flag names
* Allow interleaving built-in and command-defined flags on the command
line
* List abbreviated flag names first, matching the behavior of built-in
flags
This enables defining declarative key and/or value transformations in
cases where neither `Class`- nor path-based converters can be applied
gracefully. It is also the only way to express transforming the
resulting property names in `Typed` objects without applying a converter
to the entire containing type, which is cumbersome at best.
SPICE: https://github.com/apple/pkl-evolution/pull/26
This adds power assertions to Pkl!
This implements the SPICE described in
https://github.com/apple/pkl-evolution/pull/29
This follows the power assertions style of reporting also found in
Groovy, Kotlin, and others.
* Literal values are not emitted in the diagram
* Stdlib constructors of literals like `List(1, 2)` are also considered
literals
Power assertions are added to:
* Failing type constraints
* Failing test facts
Power assertions are implemented as a truffle instrument to observe
execution.
When an assertion fails, the instrument is created and the assertion is
run again to observe facts.
This incurs runtime overhead to collect facts, but has no impact on code
in the non-error case.
---------
Co-authored-by: Islon Scherer <islonscherer@gmail.com>
Fixes#1309
The issue was that super calls were blocked inside let expressions
because:
1. The compiler's isClassMemberScope() check didn't skip over lambda
scopes created by let expressions
2. The runtime's findSupermethod() didn't traverse past VmFunction
owners to find the actual class prototype
Changes:
- SymbolTable.java: Updated isClassMemberScope() to skip lambda scopes
before checking if the parent is a class or module scope
- InvokeSuperMethodNode.java: Updated findSupermethod() to skip
VmFunction owners when looking for the class prototype
Added regression tests covering:
- Super method calls inside let expressions
- Super property access inside let expressions
- Nested let expressions with super calls
---------
Co-authored-by: Jen Basch <jbasch@apple.com>
Adds convenience methods `isNotEmpty` and `isNotBlank`. This borrows the
same methods from Kotlin.
This helps users write more fluent constraints, for example,
`foo.isNotEmpty.implies(bar)`.
Adds:
* List#isNotEmpty
* Map#isNotEmpty
* Set#isNotEmpty
* Mapping#isNotEmpty
* Listing#isNotEmpty
* String#isNotEmpty
* String#isNotBlank
This adds the setup-gradle action; which has the following improvements:
* Improved cacheing (compared to setup-java's Gradle cache)
* Validates the gradle wrapper jar
This adds syntax highlighting of Pkl code!
It adds highlighting for:
* Stack frames within error messages
* CLI REPL (highlights as you type, highlights error output)
* Power assertions (coming in https://github.com/apple/pkl/pull/1384)
This uses the lexer for highlighting. It will highlight strings,
numbers, keywords, but doesn't understand how to highlight nodes like
types, function params, etc.
The reason for this is because a single line of code by itself may not
be grammatically valid.
Fixes an issue where the executable is not built.
Haven't dug into why this broke; this was working just a little bit ago
(see
https://github.com/apple/pkl/actions/runs/19911073549/job/57079605641?pr=1342).
Nevertheless, the lifecycle job dependencies were a little wonky (test
should assemble first).
[native-pkl-doc]
This fixes an issue where URLs with schemes that contain `+`, `-`, and
`.` would not be parsed correctly.
For example, `foo+bar:///?baz.pkl` would turn into
`foo+bar:///%3Fbaz.pkl`. The query param is lost, and turned into the
path.
In order to preserve the folder hierarchy in our uploaded artifact,
we need to insert a wildcard in the root path.
Also, fix fan-in of tasks that lead to the publish test result task.
This switches our builds over to GitHub Actions!
TODO:
* Add macOS/amd64 native-image builds; this isn't working right now
* Patch musl with security patches
* Add benchmark jobs over time
As part of this build, PRBs will now only run `./gradlew check` on Linux,
but other jobs can be run using slash commands, e.g. `[windows]`
to run `./gradle check` on Windows.
This causes spotless to _always_ format Pkl files, instead of only
formatting them if there's a diff between the file and what's in main.
This means that formatting changes in pkl-formatter will be propagated
to the standard library.
This fixes several issues:
1. Leading/trailing line comments surrounding a lambda should make that
lambda not "trailing", because the formatting otherwise looks bad and
also isn't stable
2. Fix incorrect algorithm for detecting trailing lambda (currently,
any number of lambdas makes the alg return `true`)
If an operator chain or method call is multiline, keep those newlines
in the formatted output.
Help preserve code like:
```
foo
|> (it) -> it + 2
|> (it) -> it / 2
```
Also, fixes an issue where forced single-line formatting would break for if/else
and let expressions
---------
Co-authored-by: Islon Scherer <islonscherer@gmail.com>
This changes code so that multiple lambda arguments makes the whole
argument list wrap.
Improves the readability of code like:
```
foo
.toMap(
(it) -> makeSomeKey(it),
(it) -> makeSomeValue(it)
)
```
Fixes an issue where sentinel value (U+7FFF) occurring literally in the source could cause a premature termination of parsing, leading to potential EOF injection attacks.
---------
Co-authored-by: Dan Chao <dan.chao@apple.com>
This adds a spotless formatting step using the new pkl formatter.
This only formats Pkl sources in the stdlib, because other sources
are possibly test input and not meant to be formatted.
This forces iterpolated expressions to be single-line, so that newline
literals within the bounds of two string delimiters can be seen as
verbatime newlines in the resulting string.
Edge case: in the case of a line comment, it's not possible to keep
this as a single line expression.
These are kept as multi-line expressions.
Also:
* Remove `ForceWrap`, this node is not used.
* Rename `StringConstant` -> `StringChars`
This introduces an IntelliJ plugin that's meant to assist with development of the Pkl codebase itself.
The plugin adds a file editor that opens snippet tests in a split editor pane, showing the input on the left side and output on the right side.
Implements a binary renderer for Pkl values, which is a lossless capturing of Pkl data.
This follows the pkl binary format that is already used with `pkl server` calls, and is
made available as a Java API and also an in-language API.
Also, introduces a binary parser into the corresponding `PObject` types in Java.
This changes the formatter to only force line on call chains
with multiple lambdas
With this change, this is kept as a single line:
```
foo.bar.map((it) -> it + 1)
```
The current version of the kotlin-gradle plugin is not compatible with
Gradle 9.1, causing error `java.lang.NoSuchMethodError:
'org.gradle.api.Project org.gradle.api.artifacts.ProjectDependency.getDependencyProject()'`
Also, the Kotlin 2.0 language target is deprecated as of Kotlin 2.2.
* Bump Gradle to 9.1.0
* Bump foojay resolver to 1.0.0
* Fix build logic on windows
Also, remove support for kotlin gradle plugin less than 1.8.x, because:
* Class `org.gradle.api.plugins.Convention` is no longer available in the classpath in Gradle
* Continued support for legacy plugin would require heavy reflection, which is brittle and hard to verify
* Kotlin 1.7 is 3 years old and no longer updated
Currently, in order to update a pkl-doc documentation site,
almost the entire existing site is read in order to update metadata
like known versions, known subtypes, and more.
For example, adding a new version of a package requires that the
existing runtime data of all existing versions be updated.
Eventually, this causes the required storage size to balloon
exponentially to the number of versions.
This addresses these limitations by:
1. Updating the runtime data structure to move "known versions" metadata
to the package level (the same JSON file is used for all versions).
2. Eliminating known subtype and known usage information at a
cross-package level.
3. Generating the search index by consuming the previously generated
search index.
4. Generating the main page by consuming the search index.
Because this changes how runtime data is stored, an existing docsite
needs to be migrated.
This also introduces a new migration command, `pkl-doc --migrate`,
which transforms an older version of the website into a newer version.
In the original implementation the `org/pkl/commons/cli/PklCARoots.pem` resource is resolved relatively to the classloader associated with the class returned by `javaClass`. However, since this is an extension method for `HttpClient.Builder`, it means calling `javaClass` on the builder instance, which is actually defined in the system classpath.
Because of this, if the Pkl class is loaded by a different classloader compared to the one which contains JDK classes, which is totally possible in certain scenarios (e.g. with Gradle), then this resource resolution will fail.
The solution is to resolve `javaClass` against `this@CliCommand`, to use the classloader which loaded the jar with the `CliCommand` class to find the CA resource.
This fixes two issues:
1. Test mode is enabled in pkldoc without the ability to turn it off
2. Native pkldoc is missing required resources
This also adds tests for both `jpkldoc` and `pkldoc`.
The backslash needs to be escaped when rendering double-quoted YAML strings.
In addition, this escapes the following characters:
* next line (0x85)
* nbsp (0xa0)
* Snapshot repo has changed
* Fix a bug where pkl-codegen-java download link points to Sonatype instead of GitHub
Not in the PR: we also need to fix the snapshot download location;
but haven't figured out yet what the correct link is.
based on version information from https://search.maven.org, https://plugins.gradle.org, and GitHub repos
. Run `gw updateDependencyLocks`
. Validate changes with `gw build buildNative`
. Review and commit the updated dependency lock files
== Code Generation
@@ -90,20 +88,27 @@ This will listen on port 5005.
Example: `./gradlew test -Djvmdebug=true`
== Snippet Test Plugin
There is an IntelliJ plugin meant for development on the Pkl project itself located in https://github.com/apple/pkl-project-commons[pkl-project-commons].
See https://github.com/apple/pkl-project-commons?tab=readme-ov-file#internal-intellij-plugin[its readme] for instructions on how to set it up.
== Resources
For automated build setup examples see our https://github.com/apple/pkl/blob/main/.circleci/[CircleCI] jobs like our https://github.com/apple/pkl/blob/main/.circleci/jobs/BuildNativeJob.pkl[BuildNativeJob.pkl], where we build Pkl automatically.
For automated build setup examples see our https://github.com/apple/pkl/blob/main/.github/[GitHub Actions] jobs like our https://github.com/apple/pkl/blob/main/.github/jobs/BuildNativeJob.pkl[BuildNativeJob.pkl], where we build Pkl automatically.
* link:CONTRIBUTING.adoc[] for tips on pull requests and filing issues
* link:DEVELOPMENT.adoc[] for build instructions
* {uri-ci-artifacts}[Sonatype Repository] for the artifacts/binaries built by our {uri-ci-pipeline}[CI pipelines] (and those of our other tools and packages repositories).
Pkl values can be encoded into a binary format called "pkl-binary".
This format is a lossless serialization of the underlying Pkl values.
Pkl code can be rendered into this format using the {uri-stdlib-pklbinaryModule}[pkl:pklbinary] standard library module.
Alternatively, many language bindings also provide methods to evaluate into `pkl-binary`, such as the `evaluateExpressionPklBinary` method in link:{uri-pkl-core-Evaluator}[org.pkl.core.Evaluator].
The binary format is uses link:{uri-messagepack}[MessagePack] encoding.
@@ -36,7 +42,9 @@ For example, value `8` gets encoded as MessagePack `int8` format.
== Non-primitives
All non-primitive values are encoded as MessagePack arrays.
The first slot of the array designates the value's type. The remaining slots have fixed meanings depending on the type.
The first slot of the array designates the value's type.
The remaining slots have fixed meanings depending on the type.
Additional slots may be added to types in future Pkl releases. Decoders *must* be designed to defensively discard values beyond the number of known slots for a type or provide meaningful error messages.
The array's length is the number of slots that are filled. For example, xref:{uri-stdlib-List}[List] is encoded as an MessagePack array with two elements.
@@ -46,16 +54,16 @@ The array's length is the number of slots that are filled. For example, xref:{ur
@@ -64,7 +72,7 @@ The array's length is the number of slots that are filled. For example, xref:{ur
|
|link:{uri-stdlib-Mapping}[Mapping]
|`0x3`
|`0x03`
|link:{uri-messagepack-map}[map]
|Map of `<value>` to `<value>`
|
@@ -73,7 +81,7 @@ The array's length is the number of slots that are filled. For example, xref:{ur
|
|link:{uri-stdlib-List}[List]
|`0x4`
|`0x04`
|link:{uri-messagepack-array}[array]
|Array of `<value>`
|
@@ -82,7 +90,7 @@ The array's length is the number of slots that are filled. For example, xref:{ur
|
|link:{uri-stdlib-Listing}[Listing]
|`0x5`
|`0x05`
|link:{uri-messagepack-array}[array]
|Array of `<value>`
|
@@ -91,7 +99,7 @@ The array's length is the number of slots that are filled. For example, xref:{ur
|
|link:{uri-stdlib-Set}[Set]
|`0x6`
|`0x06`
|link:{uri-messagepack-array}[array]
|Array of `<value>`
|
@@ -100,7 +108,7 @@ The array's length is the number of slots that are filled. For example, xref:{ur
|
|link:{uri-stdlib-Duration}[Duration]
|`0x7`
|`0x07`
|{uri-messagepack-float}[float64]
|Duration value
|link:{uri-messagepack-str}[str]
@@ -109,7 +117,7 @@ The array's length is the number of slots that are filled. For example, xref:{ur
|
|link:{uri-stdlib-DataSize}[DataSize]
|`0x8`
|`0x08`
|link:{uri-messagepack-float}[float64]
|Value (float64)
|link:{uri-messagepack-str}[str]
@@ -118,7 +126,7 @@ The array's length is the number of slots that are filled. For example, xref:{ur
|
|link:{uri-stdlib-Pair}[Pair]
|`0x9`
|`0x09`
|`<value>`
|First value
|`<value>`
@@ -127,7 +135,7 @@ The array's length is the number of slots that are filled. For example, xref:{ur
|
|link:{uri-stdlib-IntSeq}[IntSeq]
|`0xA`
|`0x0A`
|link:{uri-messagepack-int}[int]
|Start
|link:{uri-messagepack-int}[int]
@@ -136,7 +144,7 @@ The array's length is the number of slots that are filled. For example, xref:{ur
|Step
|link:{uri-stdlib-Regex}[Regex]
|`0xB`
|`0x0B`
|link:{uri-messagepack-str}[str]
|Regex string representation
|
@@ -145,25 +153,25 @@ The array's length is the number of slots that are filled. For example, xref:{ur
|
|link:{uri-stdlib-Class}[Class]
|`0xC`
|
|
|
|
|`0x0C`
|link:{uri-messagepack-str}[str]
|<<type-name-encoding,Class name>>
|link:{uri-messagepack-str}[str]
|Module URI
|
|
|link:{uri-stdlib-TypeAlias}[TypeAlias]
|`0xD`
|
|
|
|
|`0x0D`
|link:{uri-messagepack-str}[str]
|<<type-name-encoding,TypeAlias name>>
|link:{uri-messagepack-str}[str]
|Module URI
|
|
|link:{uri-stdlib-Function}[Function]
|`0xE`
|`0x0E`
|
|
|
@@ -172,7 +180,7 @@ The array's length is the number of slots that are filled. For example, xref:{ur
|
|link:{uri-stdlib-Bytes}[Bytes]
|`0xF`
|`0x0F`
|link:{uri-messagepack-bin}[bin]
|Binary contents
|
@@ -181,6 +189,19 @@ The array's length is the number of slots that are filled. For example, xref:{ur
|
|===
[[type-name-encoding]]
[NOTE]
====
Type names have specific encoding rules:
* When the module URI is `pkl:base`:
** If the type name is `ModuleClass`, this type represents the module class of `pkl:base`.
** Otherwise, the type name corresponds to a type in `pkl:base`.
* For all other module URIs:
** When the type name contains `\#`, the string after the `#` character corresponds to a type in that module. The string before the `#` is the name of the module.
** Otherwise, the type name is the name of the module and represents the class of the module.
====
[[object-members]]
== Object Members
@@ -212,4 +233,3 @@ Like non-primitive values, object members are encoded as MessagePack arrays, whe
@@ -255,8 +255,7 @@ String literals are enclosed in double quotes:
"Hello, World!"
----
TIP: Except for a few minor differences footnote:[Pkl's string literals have fewer character escape sequences,
have stricter rules for line indentation in multiline strings, and do not have a line continuation character.],
TIP: Except for a few minor differences footnote:[Pkl's string literals have fewer character escape sequences and stricter rules for line indentation in multiline strings.],
String literals have the same syntax and semantics as in Swift 5. Learn one of them, know both of them!
Inside a string literal, the following character escape sequences have special meaning:
@@ -362,6 +361,23 @@ str = """
"""
----
To prevent line breaks from becoming part of the string's value, use a backslash (`\`) to end those lines.
[source%tested,{pkl}]
----
str = """
Although the Dodo is extinct, \
the species will be remembered.
"""
----
This multiline string is equivalent to the following single-line string:
[source%parsed,{pkl-expr}]
----
"Although the Dodo is extinct, the species will be remembered."
----
[[custom-string-delimiters]]
=== Custom String Delimiters
@@ -1423,7 +1439,7 @@ The recipe for transforming a listing is:
. Transform the list using ``List``'s link:{uri-stdlib-List}[rich API].
. If necessary, convert the list back to a listing.
TIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-ValueRenderer}[value renderer].
TIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-BaseValueRenderer}[value renderer].
Because most value renderers treat lists the same as listings, it is often not necessary to convert back to a listing.
Equipped with this knowledge, let's try to accomplish our objective:
@@ -1803,7 +1819,7 @@ The recipe for transforming a mapping is:
. Transform the map using ``Map``'s link:{uri-stdlib-Map}[rich API].
. If necessary, convert the map back to a mapping.
TIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-ValueRenderer}[value renderer].
TIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-BaseValueRenderer}[value renderer].
As most value renderers treat maps the same as mappings, it is often not necessary to convert back to a mapping.
Equipped with this knowledge, let's try to accomplish our objective:
@@ -2736,6 +2752,10 @@ output {
For more on path-based converters, see {uri-stdlib-PcfRenderer-converters}[PcfRenderer.converters].
Special <<annotations,Annotations>> may also be used to influence how class properties are rendered.
The `ConvertProperty` annotation (and subclasses of it) are automatically applied during.
For more on annotation-based converters, see link:{uri-stdlib-ConvertProperty}[ConvertProperty].
Sometimes it is useful to directly compute the final module output, bypassing `output.value` and `output.converters`.
To do so, set the link:{uri-stdlib-baseModule}/ModuleOutput#text[output.text] property to a String value:
@@ -3203,6 +3223,7 @@ This section discusses language features that are generally more relevant to tem
<1> equivalent to `email: String(contains("@"))` for type checking purposes
<2> equivalent to `emailList: List<String(contains("@"))>` for type checking purposes
[[nullable-types]]
==== Nullable Types
Class types such as `Bird` (see above) do not admit `null` values.
@@ -4916,7 +4938,7 @@ animals {
==== Receiver
The receiver is the bottom-most object in the <<prototype-chain>>.
That means that, within the context of an amending object, the reciever is the amending object.
That means that, within the context of an amending object, the receiver is the amending object.
Example:
[source,pkl]
@@ -5037,8 +5059,6 @@ in the context of that module.
[[glob-patterns]]
=== Glob Patterns
Resources and modules may be imported at the same time by globbing with the <<globbed-imports>> and <<globbed-reads>> features.
Pkl's glob patterns mostly follow the rules described by link:{uri-glob-7}[glob(7)], with the following differences:
* `*` includes names that start with a dot (`.`).
@@ -5332,7 +5352,7 @@ Module-level members can be prefixed with `module.` to resolve name conflicts:
/// See [module.pigeon].
----
To exclude a member from documentation and code completion, annotate it with `@Unlisted`:
To exclude a member from documentation and code completion, <<annotations,annotate>> it with `@Unlisted`:
[source%parsed,{pkl}]
----
@@ -5349,6 +5369,47 @@ The following member links are marked up as code but not rendered as links:footn
Nevertheless, it is a good practice to use member links in the above cases.
[[annotations]]
=== Annotations
Annotations are a mechanism to provides extra metadata about Pkl <<modules,modules>>, <<classes,classes>>, <<methods,methods>>, and <<properties,properties>>.
They provide metadata about the type or member they annotate that can be via link:{uri-stdlib-reflectModule}[reflection] or Pkl's Java APIs.
The most common use cases for annotations are to add metadata to influence behavior of xref:pkl-doc:index.adoc[Pkldoc], code generation tools, or <<module-output,module output>>.
Annotations are regular Pkl objects whose class extends link:{uri-stdlib-Annotation}[`Annotation`].
Annotation instances are defined similarly to regular <<classes, class instances>>, but instead of using the `new` keyword the class name is prefixed with `@`.
The object body may be omitted if an annotation's class has no properties or the declared annotation does not override any of the class's default values
Multiple annotations may be defined on a member.
If the annotated member has a <<doc-comments,doc comment>>, the annotation is defined between the comment and the member.
For instructions, switch to a release version of this page.
endif::[]
[[winget]]
=== Windows Package Manager
On Windows, release versions can be installed with {uri-winget}[Windows Package Manager].
ifdef::is-release-version[]
To install Pkl, run:
[source,shell]
----
winget install Apple.Pkl
----
To update Pkl, run:
[source,shell]
----
winget upgrade Apple.Pkl
----
endif::[]
ifndef::is-release-version[]
For instructions, switch to a release version of this page.
endif::[]
[[download]]
=== Download
@@ -428,6 +454,16 @@ output {
----
====
[[power-assertions-eval]]
.--power-assertions, --no-power-assertions
[%collapsible]
====
Default: enabled +
Enable or disable power assertions for detailed assertion failure messages.
When enabled, type constraint failures will show intermediate values in the assertion expression.
Use `--no-power-assertions` to disable this feature if you prefer simpler output or better performance.
====
This command also takes <<common-options, common options>>.
[[command-server]]
@@ -453,7 +489,9 @@ If these are the only failures, the command exits with exit code 10.
Otherwise, failures result in exit code 1.
<modules>::
The absolute or relative URIs of the modules to test. Relative URIs are resolved against the working directory.
The absolute or relative URIs of the modules to test.
The module must extend `pkl:test`.
Relative URIs are resolved against the working directory.
==== Options
@@ -498,6 +536,42 @@ Force generation of expected examples. +
The old expected files will be deleted if present.
====
[[power-assertions-test]]
.--power-assertions, --no-power-assertions
[%collapsible]
====
Default: enabled +
Enable or disable power assertions for detailed assertion failure messages.
When enabled, test failures will show intermediate values in the assertion expression, making it easier to understand why a test failed.
Use `--no-power-assertions` to disable this feature if you prefer simpler output.
====
[[test-reporter]]
.--test-reporter
[%collapsible]
====
Default: `spec` +
Example: `--test-reporter minimal` +
Which test reporter to use for CLI output. Possible values are `spec` and `minimal`.
====
This command also takes <<common-options, common options>>.
[[command-run]]
=== `pkl run`
*Synopsis:* `pkl run [<options>] [<module>] [<command options>]`
Evaluate a <<cli-tools,CLI command>> defined by `<module>`.
<module>::
The absolute or relative URIs of the command module to run.
The module must extend `pkl:Command`.
Relative URIs are resolved against the working directory.
<command options>::
Additional CLI options and arguments defined by `<module>`.
This command also takes <<common-options, common options>>.
[[command-repl]]
@@ -602,6 +676,14 @@ Force generation of expected examples. +
The old expected files will be deleted if present.
====
.--test-reporter
[%collapsible]
====
Default: `spec` +
Example: `--test-reporter minimal` +
Which test reporter to use for CLI output. Possible values are `spec` and `minimal`.
====
This command also takes <<common-options,common options>>.
[[command-project-resolve]]
@@ -707,10 +789,54 @@ pkl shell-completion bash
pkl shell-completion zsh
----
[[command-format]]
=== `pkl format`
*Synopsis*: `pkl format <options> [<paths>]`
This command formats or checks formatting of Pkl files. +
Exit codes:
* 0: No violations found or files were updated.
* 1: An unexpected error happened (ex.: IO error)
* 11: Violations were found (when running without `--write`).
If the path is a directory, recursively looks for files with a `.pkl` extension, or files named `PklProject`.
By default, the input files are formatted, and written to standard out.
==== Options
.--grammar-version
[%collapsible]
====
Default: `2` (latest version) +
Select the grammar compatibility version for the formatter.
New versions are created for each backward incompatible grammar change.
====
.-s, --silent
[%collapsible]
====
Skip writing to standard out. Mutually exclusive with `--diff-name-only`.
====
.-w, --write
[%collapsible]
====
Format files in place, overwriting them. Implies `--diff-name-only`.
====
.--diff-name-only
[%collapsible]
====
Write the path of files with formatting violations to stdout.
====
[[common-options]]
=== Common options
The <<command-eval>>, <<command-test>>, <<command-repl>>, <<command-project-resolve>>, <<command-project-package>>, <<command-download-package>>, and <<command-analyze-imports>> commands support the following common options:
The <<command-eval>>, <<command-test>>, <<command-run>>, <<command-repl>>, <<command-project-resolve>>, <<command-project-package>>, <<command-download-package>>, and <<command-analyze-imports>> commands support the following common options:
The root `pkl` command supports the following options:
.-v, --version
[%collapsible]
====
Display version information.
====
== Evaluating Modules
Say we have the following module:
@@ -800,6 +937,310 @@ If multiple module outputs are written to the same file, or to standard output,
By default, module outputs are separated with `---`, as in a YAML stream.
The separator can be customized using the `--module-output-separator` option.
[[cli-tools]]
== Implementing CLI Tools
CLI tools can be implemented in Pkl by modules extending the `pkl:Command` module.
With `pkl:Command`, you can define a script in Pkl that is executed by your shell, providing a better CLI experience.
Regular evaluation requires use of xref:language-reference:index.adoc#resources[resources] like properties and evironment variables to provide parameters:
Pkl commands have a few properties that distinguish them from standard module evaluation:
* Users provide input to commands using familiar command line idioms, providing a better experience than deriving inputs from xref:language-reference:index.adoc#resources[resources] like external properties or environment variables.
* Commands can dynamically import modules when they are specified as command line options.
* Commands may write to standard output (via `output.text` or `output.bytes`) and the filesystem (via `output.files`) in the same evaluation.
* Command file output may write to any absolute path (not only relative to the `--multiple-file-output-path` option).
** Relative output paths are written relative to the current working directory (or `--working-dir`, if specified).
** Paths of output file are printed to the command's standard error.
IMPORTANT: Users of `pkl run` must be aware of the security implications of this behavior.
Using `pkl eval` prevents accidental overwrites by not allowing absolute paths, but `pkl run` does not offer this protection.
Commands may write to any path the invoking user has permissions to modify.
Commands are implemented as regular modules and declare their supported command line flags and positional arguments using a class with annotated properties.
=== Defining Commands
Commands are defined by creating a module that extends `pkl:Command`:
[source,pkl%tested]
.my-tool.pkl
----
/// This doc comment becomes part of the command's CLI help!
/// Markdown formatting is **allowed!**
extends "pkl:Command"
options: Options // <1>
class Options {
// Define CLI flags/arguments...
}
// Regular module code...
----
<1> Re-declaration of the `options` property's type.
Like `pkl eval`, when a command completes without an evaluation error the process exits successfully (exit code 0).
Commands can return a failure using `throw` (exit code 1), but otherwise may not control the exit code.
Other than the differences listed above, commands behave like any other Pkl module.
For example, there is no way to execute other programs or make arbitrary HTTP requests.
If additional functionality is desired, xref:language-reference:index.adoc#external-readers[external readers] may be used to extends Pkl's capabilities.
=== Command Options
Each property of a command's options class becomes a command line option.
Properties with the `local`, `hidden`, `fixed`, and/or `const` modifiers are not parsed as options
A property's doc comment, if present, becomes the corresponding option's CLI help description.
Doc comments are interpreted as Markdown text and formatted nicely when displayed to users.
Properties must have xref:language-reference:index.adoc#type-annotations[type annotations] to determine how they are parsed.
Properties may be xref:language-reference:index.adoc#annotations[annotated] to influence how they behave:
* Properties annotated with link:{uri-stdlib-Command-Flag}[`@Flag`] become CLI flags named `--<property name>` that accept a value.
* `Boolean` properties annotated with link:{uri-stdlib-Command-BooleanFlag}[`@BooleanFlag`] become CLI flags named `--<property name>` and `--no-<property name>` that result in `true` and `false` values, respectively.
* `Int` (and type aliases of `Int`) properties annotated with link:{uri-stdlib-Command-CountedFlag}[`@CountedFlag`] become CLI flags named `--<property name>` that produce a value equal to the number of times they are present on the command line.
* Properties annotated with link:{uri-stdlib-Command-Argument}[`@Argument`] become positional CLI arguments and are parsed in the order they appear in the class.
* Properties with no annotation are treated the same as `@Flag` with no further customization.
Flag options may set a `shortName` property to define a single-character abbreviation (`-<short name>`).
Flag abbreviations may be combined (e.g. `-a -b -v -v -q some-value` is equivalent to `-abvvq some-value`).
[CAUTION]
====
Flag names and short names may not conflict with <<common-options,common options>>.
Future versions of Pkl may introduce additional common options and the names of these options will become forbidden for use in `pkl:Command`.
Thus, any Pkl release that adds common options may introduce breaking changes for commands.
While unfortunate, this behavior eliminates potentially dangerous or misleading ambiguities between Pkl-defined and user-defined options.
====
A `@Flag` or `@Argument` property's type annotation determines how it is converted from the raw string value:
|===
|Type |Behavior
|`String`
|Value is used verbatim.
|`Char`
|Value is used verbatim but must be exactly one character.
|`Boolean`
|True values: `true`, `t`, `1`, `yes`, `y`, `on`
False values: `false`, `f`, `0`, `no`, `n`, `off`
|`Number`
|Value is parsed as an `Int` if possible, otherwise parsed as `Float`.
|Each occurrence of the option becomes an element of the final value.
`Element` values are parsed based on the above primitive types.
|`Map<Key, Value>`, `Mapping<Key, Value>`
|Each occurrence of the option becomes an entry of the final value.
Values are split on the first `"="` character; the first part is parsed as `Key` and the second as `Value`, both based on the above primitive types.
|`Pair<First, Second>`
|Value is split on the first `"="` character; the first part is parsed as `First` and the second as `Second`, both based on the above primitive types.
|===
If a flag that accepts only a single value is provided multiple times, the last occurrence becomes the final value.
Only a single positional argument accepting multiple values is permitted per command.
A property with a xref:language-reference:index.adoc#nullable-types[nullable type] is optional and, if not specified on the command line, will have value `null`.
Properties with default values are also optional.
Type constraints are evaluated when the command is executed, so additional restrictions on option values are enforced at runtime.
==== Custom Option Conversion and Aggregation
A property may be annotated with any type if its `@Flag` or `@Argument` annotation sets the `convert` or `transformAll` properties.
The `convert` property is a xref:language-reference:index.adoc#anonymous-functions[function] that overrides how _each_ raw option value is interpreted.
The `transformAll` property is a function that overrides how _all_ parsed option values become the final property value.
The `convert` and `transformAll` functions may return an pkldoc:Import[pkl:Command] value that is replaced during option parsing with the actual value of the module specified by its `uri` property.
If `glob` is `true`, the replacement value is a `Mapping`; its keys are the _absolute_ URIs of the matched modules and its values are the actual module values.
When specifying glob import options on the command line, it is often necessary to quote the value to avoid it being interpreted by the shell.
If the return value of `convert` or `transformAll` is a `List`, `Set`, `Map`, or `Pair`, each contained value (elements and entry keys/values) that are `Import` values are also replaced.
[IMPORTANT]
====
If an option has type `Mapping<String, «some module type»>` and should accept a single glob pattern value, the option's annotation must also set `multiple = false` to override the default behavior of `Mapping` options accepting multiple values.
Example:
[source%parsed,{pkl}]
----
@Flag {
convert = (it) -> new Import { uri = it; glob = true }
multiple = false
}
birds: Mapping<String, Bird>
----
If multiple glob patterns values should be accepted and merged, `transformAll` may be used to merge every glob-imported `Mapping`:
[source%parsed,{pkl}]
----
@Flag {
convert = (it) -> new Import { uri = it; glob = true }
Like many other command line libraries, `pkl:Command` allows building commands into a hierarchy with a root command and subcommands:
[source,pkl%tested]
.my-tool.pkl
----
extends "pkl:Command"
command {
subcommands {
import("subcommand1.pkl")
import("subcommand2.pkl")
for (_, subcommand in import*("./subcommands/*.pkl")) {
subcommand
}
}
}
----
[source,pkl%tested]
.subcommand1.pkl
----
extends "pkl:Command"
import "my-tool.pkl"
parent: `my-tool` // <1>
// Regular module code...
----
<1> Optional; asserts that this is a subcommand of `my-tool` and simplifies accessing properties and options of the parent command
Each element of `subcommands` must have a unique value for `command.name`.
=== Testing Commands
Command modules are normal Pkl modules, so they may be imported and used like any other module.
This is particularly helpful when testing commands, as the command's `options` and `parent` properties can be populated by test code.
Testing the above command and subcommand might look like this:
[source,pkl%tested]
----
amends "pkl:test"
import "my-tool.pkl"
import "subcommand1.pkl"
examples {
["Test my-tool"] {
(`my-tool`) {
options {
// Set my-tool options here...
}
}.output.text
}
["Test subcommand1"] {
(subcommand1) {
parent { // this amends `my-tool`
options {
// Set my-tool options here...
}
}
options {
// Set subcommand options here...
}
}.output.text
}
}
----
[[commands-as-standalone-scripts]]
=== Commands as standalone scripts
On *nix platforms, Pkl commands can be configured to run as standalone tools that can be invoked without the `pkl run` command.
To achieve this, the command file must be marked executable (i.e. `chmod +x my-tool.pkl`) and a link:https://en.wikipedia.org/wiki/Shebang_(Unix)[shebang comment] must be added on the first line of the file:
[source,pkl%parsed]
----
#!/usr/bin/env -S pkl run
----
NOTE: The `-S` flag for `env` is required on Linux systems due to a limitation of shebang handling in the Linux kernel.
While not required on other *nix platforms like macOS, but it should be included for compatibility.
==== Shell Completion
Like with Pkl's own CLI, <<command-shell-completion, shell completions>> can be generated for standalone scripts.
[source,shell]
----
# Generate shell completion script for bash
./my-tool.pkl shell-completion bash
# Generate shell completion script for zsh
./my-tool.pkl shell-completion zsh
----
==== Customizing Completion Candidates
`@Flag` and `@Argument` annotations may specify the `completionCandidates` to improve generated shell completions.
Valid values include:
* A `Listing<String>` of literal string values to offer for completion.
* The literal string `"path"`, which offers local file paths for completion.
Options with a string literal union type implicitly offer the members of the union as completion candidates.
=== Flag name ambiguities
It is possible for commands to define flags with names or short names that collide with Pkl's own command line options.
To avoid ambiguity in parsing these options, all flags for Pkl itself (e.g. `--root-dir`) must be placed before the root command module's URI.
Command authors are encouraged to avoid overlapping with Pkl's built-in flags, but this may not always be feasible, especially for single-character abbreviated names.
This imposes a limitation around <<commands-as-standalone-scripts,standalone commands>> that prevents users from customizing Pkl evaluator options when they are invoked.
There are two recommended workarounds for this limitation:
* Use a `PklProject` to define evaluator settings instead of doing so on the command line.
* If the command line must be used, switch to invoking via `pkl run [<flags>] [<root command module>]`.
@@ -266,7 +266,7 @@ Thanks to https://github.com/gordonbondon[@gordonbondon] for contributing to thi
=== `@Generated` annotation for Java/Kotlin codegen
Classes generated by the Java and Kotlin code generator can optionally recieve new annotation called `Generated` (https://github.com/apple/pkl/pull/1075[#1075], https://github.com/apple/pkl/pull/1115[#1115]).
Classes generated by the Java and Kotlin code generator can optionally receive new annotation called `Generated` (https://github.com/apple/pkl/pull/1075[#1075], https://github.com/apple/pkl/pull/1115[#1115]).
This behavior is toggled with the `--generated-annotation` CLI flag, or the similarly named Gradle property.
@@ -342,6 +342,7 @@ In Pkl 0.29, it is an error to load a module or resource with an opaque `file:`
NOTE: To import or read a relative path, omit `file:` from the import string. For example, `import("foo/bar.txt")` instead of `import("file:foo/bar.txt")`.
[[new-base-module-names]]
=== New base module names: `Bytes` and `Charset`
Two new names are introduced to the base module: `Bytes` and `Charset`.
[.small]#The latest bugfix release is {version-minor}. (xref:changelog.adoc[All Versions])#
This release introduces a code formatter, and an in-language API for producing `pkl-binary` output.
The next release (0.31) is scheduled for February 2026.
To see what's coming in the future, follow the {uri-pkl-roadmap}[Pkl Roadmap].
Please send feedback and questions to https://github.com/apple/pkl/discussions[GitHub Discussions], or submit an issue on https://github.com/apple/pkl/issues/new[GitHub]. +
[small]#Pkl is hosted on https://github.com/apple/pkl[GitHub].
To get started, follow xref:pkl-cli:index.adoc#installation[Installation].#
Pkl's formatter is _canonical_, which means that it has a single set of formatting rules, with (almost) no configuration options.
The goal is to eliminate the possibility of formatting debates, which can lead to churn and bike-shedding.
The formatter is available both as a CLI subcommand and as a Java API.
To learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0014-canonical-formatter.adoc[SPICE-0014].
==== Using the CLI
The Pkl formatter is available under the `pkl format` subcommand. By default, the command will concatenate and write all formatted content to standard out.
To simply check for formatting violations, getting formatted output on stdout is likely too verbose.
The `--silent` flag can be used to omit any output, and the <<formatting-exit-codes,exit code>> can be used to determine
if there are formatting violations.
[source,shell]
----
pkl format --silent . || echo "Formatting violations were found!"
----
Alternatively, the `--names` flag will print out the names of any files that have formatting violations.
[source,shell]
----
pkl format --diff-name-only .
----
To apply formatting, use the `--write` (`-w`) flag.
This also implies the `--diff-name-only` flag.
[source,shell]
----
pkl format -w .
----
[[formatting-exit-codes]]
==== Exit codes
The formatter will exit with the following codes:
|===
|Code |Description
|0
|No formatting violations were found.
|1
|Non-formatting errors occurred.
|11
|Formatting violations were found.
|===
==== Grammar version
The formatter can be configured with a _grammar version_, which maps to a Pkl version range.
|===
|Grammar version |Pkl versions
|1
|0.25 - 0.29
|2
|0.30+
|===
Grammar version 2 uses the newly introduced <<trailing-commas,trailing commas>> feature, and therefore is not compatible with existing versions of Pkl.
To ensure compatibility, use the `--grammar-version 1` CLI flag.
[[binary-renderer-parser]]
=== `pkl-binary` in-language Renderer
A new in-language API has been added to render values into xref:bindings-specification:binary-encoding.adoc[pkl-binary encoding] (https://github.com/apple/pkl/pull/1203[#1203],
It's sometimes useful to separate Pkl evaluation from data consumption when used as application or service configuration.
This is possible with the `pkl-binary` format, which is a lossless encoding of Pkl data.
In this approach, Pkl is first rendered into `pkl-binary` during build time, and then deserialized into classes and structs at startup time.
This means that the Pkl evaluator does not need to be shipped with the application, which improves code portability and eliminates runtime overhead.
However, currently, the API for getting this binary format is somewhat cumbersome.
Only the host languages have access to this API (for example, https://swiftpackageindex.com/apple/pkl-swift/0.6.0/documentation/pklswift/evaluator/evaluateexpressionraw(source:expression:)[`evaluateExpressionRaw`] in pkl-swift).
This means that one-off logic must be written to render this format in the host language.
In 0.30, this renderer is added as an in-language API, through the {uri-stdlib-pklbinaryModule}[`pkl:pklbinary`] standard library module.
Additionally, it is available through CLI flag `--format pkl-binary`.
For example:
// this is parsed instead of tested because DocSnippetTests only handles textual output (via ReplServer)
[source%parsed,pkl]
----
import "pkl:pklbinary"
output {
renderer = new pklbinary.Renderer {}
}
----
To learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0021-binary-renderer-and-parser.adoc[SPICE-0021].
==== New renderer type: `BytesRenderer`
To enable the `pkl-binary` renderer feature, Pkl now supports renderers that produce `Bytes` output (https://github.com/apple/pkl/pull/1203[#1203]).
The existing `ValueRenderer` class now extends new class `BaseValueRenderer`, and a new `BytesRenderer` class is introduced.
Setting a module's output renderer to a `BytesRenderer` will control its resulting `output.bytes`.
This affects usage scenarios where a module's `output.bytes` is evaluated, for example, when using `pkl eval`.
==== Using `pkl-binary` data
Users of Pkl's language binding libraries can decode `pkl-binary` data into instances of code-generated types.
[tabs]
====
Java::
+
[source,java]
----
var encodedData = fetchEncodedData(); // some byte[] or InputStream
var config = Config.fromPklBinary(encodedData);
var appConfig = config.as(AppConfig.class);
----
Kotlin::
+
[source,kotlin]
----
val encodedData = fetchEncodedData() // some ByteArray or InputStream
val config = Config.fromPklBinary(encodedData, ValueMapper.preconfigured().forKotlin())
val appConfig = config.to<AppConfig>()
----
Go::
+
[source,go]
----
encodedData := fetchEncodedData() // some []byte
var appConfig AppConfig
if err := pkl.Unmarshal(encodedData, &appConfig); err != nil {
// handle error
}
----
Swift::
+
[source,swift]
----
let encodedData = fetchEncodedData() // some [UInt8]
let appConfig = try PklDecoder.decode(AppConfig.self, from: encodedData)
----
====
== Noteworthy [small]#🎶#
[[trailing-commas]]
=== Trailing Commas
Pkl's grammar has been updated to allow including a comma following the final item of comma-separated syntax elements (https://github.com/apple/pkl/pull/1137[#1137]).
These syntax elements are affected:
[source%tested,pkl]
----
function add(
bar,
baz, // <1>
) = bar + baz
foo = add(
1,
2, // <2>
)
typealias MyMapping<
Key,
Value, // <3>
> = Mapping<Key, Value>
bar: Mapping<
String,
Int, // <4>
>
baz: Mapping(
!containsKey("forbidden key"),
!containsKey("forbidden value"), // <5>
)
qux: (
String,
Int, // <6>
) -> Dynamic =
(paramA, paramB) -> new Dynamic {
quux = "\(paramA): \(paramB)"
}
corge = (qux) {
paramA,
paramB, // <7>
->
grault = paramA.length * paramB
}
----
<1> Function parameter lists in method definitions.
<2> Argument lists in method calls.
<3> Type parameter lists in generic type definitions.
<4> Type argument lists in type annotations and casts.
<5> Type constraint lists.
<6> Function type parameter lists in function type annotations.
<7> Object body parameter lists.
To learn more about this change, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0019-trailing-commas.adoc[SPICE-0019].
=== Pretty-printed traces
A new evaluator option is added to enable pretty-printed traces (https://github.com/apple/pkl/pull/1100[#1100], https://github.com/apple/pkl/pull/1227[#1227], https://github.com/apple/pkl/pull/1230[#1230]).
Currently, the `trace()` operator will render values as a single line, and trims the output after 100 characters.
This can obscure information when debugging.
In 0.30, a new evaluator option is added to control how traces are emitted.
Two trace modes are introduced:
* `compact` - the current output mode (default).
* `pretty` - multiline, with no limit on output size.
For example, users of the CLI can specify `--trace-mode` as a flag.
[source,shell]
----
pkl eval --trace-mode pretty myModule.pkl
----
Thanks to https://github.com/ssalevan[@ssalevan] for their contribution to this feature!
=== Better support for `Bytes` when rendering YAML
Previously, attempting to render a `Bytes` value using {uri-stdlib-YamlRenderer}[`YamlRenderer`] required the use of a link:{uri-stdlib-PcfRenderer-converters}[converter].
Now, Pkl can natively render YAML containing link:{yaml-binary-scalar}[binary scalars] (https://github.com/apple/pkl/pull/1276[#1276]).
[source,pkl%tested]
----
foo {
bar = Bytes(1, 2, 3)
}
rendered = new YamlRenderer {}.renderValue(foo) // <1>
----
<1> Result: `bar: !!binary AQID`
Similarly, link:{uri-stdlib-YamlParser}[`yaml.Parser`] now parses binary YAML values as Pkl link:{uri-stdlib-Bytes}[`Bytes`] values (https://github.com/apple/pkl/pull/1277[#1277]).
This is a breaking change; previously these values were parsed as link:{uri-stdlib-String}[`String`] value containing the base64-encoded binary data.
[source,pkl%tested]
----
import "pkl:yaml"
yamlData =
"""
bytes: !!binary AQID
"""
parsed = new yaml.Parser {}.parse(yamlData).bytes // <1>
----
<1> Result: `Bytes(1, 2, 3)`
[[pkldoc-perf-improvements]]
=== `pkldoc` performance improvements
The `pkldoc` documentation generator has been overhauled (https://github.com/apple/pkl/pull/1169[#1169], https://github.com/apple/pkl/pull/1224[#1224], https://github.com/apple/pkl/pull/1241[#1241], https://github.com/apple/pkl/pull/1242[#1242]).
Currently, the `pkldoc` tool needs to consume much of an existing documentation website whenever generating new documentation.
This adds significant I/O overhead as a pkldoc documentation website grows.
The generator has been overhauled to minimize the amount of data needed to be read from the current site.
To read more about this change, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0018-pkldoc-io-improvements.adoc[SPICE-0018].
[[pkldoc-migration]]
==== Migration
The new pkldoc website introduces breaking changes to the data model.
Because of this, existing sites must be migrated before using the `0.30` version of pkldoc.
To migrate, run the one-time command `pkldoc --migrate`.
* Add internal IntelliJ plugin that's meant to assist with development of the Pkl codebase itself (https://github.com/apple/pkl/pull/1248[#1248]).
* Update CircleCI macOS instance type and Xcode version (https://github.com/apple/pkl/pull/1243[#1243], https://github.com/apple/pkl/pull/1244[#1244]).
* Disable multi-jdk testing when running on Windows ARM (https://github.com/apple/pkl/pull/1223[#1223]).
* Refine documentation for class `Any` (https://github.com/apple/pkl/pull/1194[#1194]).
== Bugs fixed [small]#🐜#
The following bugs have been fixed.
* Incorrect error message when refusing to read past root dir (https://github.com/apple/pkl/pull/1234[#1233]).
* Unicode U+7FFF character (翿) incorrectly parsed as EOF (https://github.com/apple/pkl/pull/1251[#1251]).
* Fallback certificates do not work in certain classloader setups (https://github.com/apple/pkl/pull/1198[#1199]).
== Contributors [small]#🙏#
We would like to thank the contributors to this release (in alphabetical order):
Pkl's test output and error output has been improved with power assertions (pr:https://github.com/apple/pkl/pull/1384[], pr:https://github.com/apple/pkl/pull/1419[])!
Pkl has two places that are effectively assertions.
These are:
* Type constraint expressions
* Test facts
Currently, when these assertions fail, the error message prints the assertion's source section.
However, this information can sometimes be lacking.
It tells you what the mechanics of the assertion is, but doesn't tell you _why_ the assertion is failing.
For example, here is the current error output of a failing typecheck.
[source,text]
----
–– Pkl Error ––
Type constraint `name.endsWith(lastName)` violated.
Value: new Person { name = "Bub Johnson" }
7 | passenger: Person(name.endsWith(lastName)) = new { name = "Bub Johnson" }
----
Just from this error message, we don't know what the last name is supposed to be.
What is `name` supposed to end with?
We just know it's some property called `lastName` but, we don't know what it _is_.
In Pkl 0.31, the error output becomes:
[source,text]
----
–– Pkl Error ––
Type constraint `name.endsWith(lastName)` violated.
Value: new Person { name = "Bub Johnson" }
name.endsWith(lastName)
│ │ │
│ false "Smith"
"Bub Johnson"
7 | passenger: Person(name.endsWith(lastName)) = new { name = "Bub Johnson" }
----
Now, we know what the expectation is.
This type of diagram is also added to test facts.
When tests fail, Pkl emits a diagram of the expression, and the values produced.
For example, given the following test:
.math.pkl
[source,pkl]
----
amends "pkl:test"
facts {
local function add(a: Int, b: Int) = a * b
local function divide(a: Int, b: Int) = a % b
["math"] {
add(3, 4) == 7
divide(8, 2) == 4
}
}
----
The error output now includes a power assertion diagram, which helps explain why the test failed.
To learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0026-power-assertions.adoc[SPICE-0026].
[[cli-framework]]
=== CLI Framework
Pkl 0.31 introduces a new framework for implementing CLI tools in Pkl (pr:https://github.com/apple/pkl/pull/1367[], pr:https://github.com/apple/pkl/pull/1431[], pr:https://github.com/apple/pkl/pull/1432[], pr:https://github.com/apple/pkl/pull/1436[], pr:https://github.com/apple/pkl/pull/1440[], pr:https://github.com/apple/pkl/pull/1444[]).
The framework provides a way to build command line tools with user experience idioms that will be immediately familiar to users.
CLI tools implemented in Pkl have largely the same capabilities as normal Pkl evaluation (i.e. writing to standard output and files), but this may be extended using xref:language-reference:index.adoc#external-readers[external readers].
Commands are defined by extending the pkldoc:#[pkl:Command] module:
.bird-generator.pkl
[source,pkl]
----
extends "pkl:Command"
options: Options
class Options {
/// Mapping of <bird>=<bird age> pairs defining the list of birds.
@Argument
birds: Mapping<String, Number>
/// Aggregation function to apply to all bird ages.
aggregate: *"sum" | "mean" | "count"
}
class Bird {
/// Name of the bird.
name: String
/// Age of the bird in years.
age: Number
}
birds: Listing<Bird> = new {
for (_name, _age in options.birds) {
new { name = _name; age = _age }
}
}
result: Number =
if (options.aggregate == "sum")
birds.toList().fold(0.0, (result, bird) -> result + bird.age)
else if (options.aggregate == "mean")
birds.toList().fold(0.0, (result, bird) -> result + bird.age) / birds.length
else
birds.length
----
Commands are executed using the `pkl run` CLI subcommand:
[source,bash]
----
$ pkl run bird-generator.pkl pigeon --aggregate=mean Pigeon=1 Hawk=8 Eagle=3
--aggregate=<count, mean, sum> Aggregation function to apply to all bird ages.
-h, --help Show this message and exit
Arguments:
<birds> Mapping of <bird>=<bird age> pairs defining the list of birds.
----
To learn more about this feature, consult xref:pkl-cli:index.adoc#cli-tools[the documentation] and https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0025-pkl-run-cli-framework.adoc[SPICE-0025].
== Noteworthy [small]#🎶#
=== Syntax Highlighting
The Pkl CLI displays Pkl code in several locations: stack frames within errors messages, <<power-assertions,power assertions>>, and in the xref:pkl-cli:index.adoc#repl[REPL].
This code is now syntax highlighted to improve readability (pr:https://github.com/apple/pkl/pull/1385[], pr:https://github.com/apple/pkl/pull/1409[]):
The Pkl CLI now supports specifying modules using xref:language-reference:index.adoc#project-dependencies[dependency notation] (pr:https://github.com/apple/pkl/pull/1434[], pr:https://github.com/apple/pkl/pull/1439[]).
This is especially helpful for <<cli-framework,CLI commands>> defined in Packages:
[source,bash]
----
$ pkl run @my-tool/cmd.pkl ...
----
This enhancement applies to the `pkl eval`, `pkl run`, `pkl test`, and `pkl analyze imports` commands.
It also applies to the `pkldoc`, `pkl-codegen-java`, and `pkl-codegen-kotlin` tools.
[NOTE]
Dependency notation only works for remote package dependencies. xref:language-reference:index.adoc#local-dependencies[Local dependencies] are not supported.
=== Property Converter Annotations
Pkl provides the pkldoc:BaseValueRenderers#converters[] mechanism for transforming values during rendering.
Converters are flexible, but their design makes some transformations awkward.
In particular, modifying property names during rendering required a lot of extra code.
The new pkldoc:ConvertProperty[] annotation adds a way to express parameterized per-property name and value transformations (pr:https://github.com/apple/pkl/pull/1333[]).
To learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0024-annotation-converters.adoc[SPICE-0024].
Additional new Pkl APIs for per-format property renaming will be added for many built-in renderers:
The pkldoc:#[pkl:Command] standard library module is added.
==== Additions to `pkl:json`
* pkldoc:Property[pkl:json]
==== Additions to `pkl:jsonnet`
* pkldoc:Property[pkl:jsonnet]
==== Additions to `pkl:protobuf`
* pkldoc:Property[pkl:protobuf]
==== Additions to `pkl:xml`
* pkldoc:Property[pkl:xml]
==== Additions to `pkl:yaml`
* pkldoc:Property[pkl:yaml]
== Breaking Changes [small]#💔#
Things to watch out for when upgrading.
=== Removal of `@argfile` support
Prior versions of Pkl had an undocumented feature allowing inclusion of CLI arguments from files using `@path/to/file`.
In order to support <<cli-dependency-notation,dependency notation>> on the CLI, `@argfile` support has been removed from Pkl.
=== Removal of `Collection#transpose()`
Prior versions of Pkl defined a `transpose()` method on the `Collection` class.
This method was never implemented and threw an error when called.
As it was never functional, it has been removed entirely without a deprecation warning (pr:https://github.com/apple/pkl/pull/1437[]).
== Miscellaneous [small]#🐸#
* Improve formatting of imports to keep surrounding comments (pr:https://github.com/apple/pkl/pull/1424[]).
* Add support for evaluating module output and expressions to `ConfigEvaluator` (pr:https://github.com/apple/pkl/pull/1297[]).
* The `pkl format --write` command now exits successfully when formatting violations are found and updated (pr:https://github.com/apple/pkl/pull/1340[]).
* Add `pkl-bom` module to aid in aligning Pkl Java dependencies (pr:https://github.com/apple/pkl/pull/1390[]).
* Improve error message when writing `PklProject.deps.json` fails (pr:https://github.com/apple/pkl/pull/1405[]).
* Add information about pkldoc:Annotation[]s to the language reference (pr:https://github.com/apple/pkl/pull/1427[]).
* Improved usability for the `org.pkl.formatter.Formatter` Java API (pr:https://github.com/apple/pkl/pull/1428[]).
== Bugs fixed [small]#🐜#
The following bugs have been fixed.
* `Function.toString()` returns incorrect result (pr:https://github.com/apple/pkl/pull/1411[]).
* Failure when `--multiple-file-output-path` is a symlink (pr:https://github.com/apple/pkl/pull/1389[]).
* The `module` type in a non-final module has default value of type `Dynamic` (pr:https://github.com/apple/pkl/pull/1392[]).
* The `module` type is cached incorrectly in some cases (pr:https://github.com/apple/pkl/pull/1393[]).
* A possible race condition involving symlinks could bypass `--root-dir` during module and resource reading (pr:https://github.com/apple/pkl/pull/1426[]).
* `org.pkl.core.evaluatorSettings.PklEvaluatorSettings.parse` no longer accepts a `pathNormalizer` argument.
=== Loading rule changes in `pkl:EvaluatorSettings`
Breaking changes have been made to how evaluator settings are loaded (https://github.com/apple/pkl/pull/1394[#1394]).
==== Loading rule changes for the external reader executable
The following changes have been made for the `executable` property in an external reader:
* If the executable does not contain a slash (`/` on POSIX, `\` on Windows) character, it is always resolved against the `PATH` environment variable.
* If it does contain a slash, it is resolved relative to the enclosing PklProject directory, instead of the current working directory.
=== Changes to `--external-module-reader` and `--external-resource-reader` CLI flags
The `--external-module-reader` and `--external-resource-reader` CLI flags will _replace_ any external readers otherwise configured within a PklProject, instead of add to it (https://github.com/apple/pkl/pull/1394[#1394]).
This makes this behavior consistent with how other settings work.
== Work In Progress [small]#🚆#
They missed the train but deserve a mention.
.XXX
[%collapsible]
====
XXX
====
== Contributors [small]#🙏#
We would like to thank the contributors to this release (in alphabetical order):
* Allow nullable reads for custom/external resources (pr:https://github.com/apple/pkl/pull/1471[]).
This allows custom/external resources to produce `null` values for xref:language-reference:index.adoc#nullable-reads[nullable reads] (`read?`).
While this is a breaking change in behavior, it is currently not possible to exercise with versions of pkl-go or pkl-swift released prior to this change.
=== Fixes
* Fix typo in changelog and language reference (pr:https://github.com/apple/pkl/pull/1455[]).
* Fix bugs in `CommandSpecParser` (pr:https://github.com/apple/pkl/pull/1448[], pr:https://github.com/apple/pkl/pull/1449[]).
* Respect `--omit-project-settings` for all evaluator options (pr:https://github.com/apple/pkl/pull/1459[]).
* Fix SecurityManager check for HTTP(S) module URIs (pr:https://github.com/apple/pkl/pull/1463[]).
* Fix performance regression caused by activation of power assertion instrumentation during some union type checks (pr:https://github.com/apple/pkl/pull/1462[]).
* Fix module reflection when power assertion instrumentation is active (pr:https://github.com/apple/pkl/pull/1464[]).
* Prevent I/O when checking UNC paths against `--root-dir` (pr:https://github.com/apple/pkl/pull/1466[]).
* Prevent `--multiple-file-output-path` writes from following symlinks outside the target directory
(pr:https://github.com/apple/pkl/pull/1467[]).
=== Contributors ❤️
Thank you to all the contributors for this release!
* https://github.com/04cb[@04cb]
* https://github.com/HT154[@HT154]
* https://github.com/KushalP[@KushalP]
[[release-0.31.0]]
== 0.31.0 (2026-02-26)
xref:0.31.adoc[Release Notes]
[[release-0.30.2]]
== 0.30.2 (2025-12-15)
=== Fixes
* Fixes formatting of blank files (https://github.com/apple/pkl/pull/1351[#1351]).
* Fixes an issue where the `pkl format` CLI command adds an extra newline when writing formatted content to standard output (https://github.com/apple/pkl/issues/1346[#1346]).
* Make linux executables link to glibc 2.17 (https://github.com/apple/pkl/pull/1352[#1352]).
* Fix incorrect parsing of super expressions (https://github.com/apple/pkl/pull/1364[#1364]).
=== Contributors ❤️
Thank you to all the contributors for this release!
* Fixes an issue where autocompletion in Bash and ZSH do noes not suggest filenames (https://github.com/apple/pkl/pull/1161[#1161]).
* Fixes an issue where `pkldoc` throws a runtime error about failing to load class path resources (https://github.com/apple/pkl/issues/1174[#1174]).
* Fixes an issue where `pkldoc` always runs with `testMode` set to true.
* Fixes an issue where evaluating a module that ends with an unmatched backtick throws `ArrayIndexOutOfBoundsException` (https://github.com/apple/pkl/issues/1182[#1182]).
* Fixes the formatting of YAML strings when emitting backslash characters within quoted strings (https://github.com/apple/pkl/pull/1165[#1165]).
* Fixes an issue where `local` members inside `Mapping` objects are incorrectly encoded into binary format (https://github.com/apple/pkl/issues/1151[#1151]).
=== Contributors ❤️
Thank you to all the contributors for this release!
The Pkl team aims to release a new version of Pkl in February, June, and October of each year.
* xref:0.32.adoc[0.32 Release Notes]
* xref:0.31.adoc[0.31 Release Notes]
* xref:0.30.adoc[0.30 Release Notes]
* xref:0.29.adoc[0.29 Release Notes]
* xref:0.28.adoc[0.28 Release Notes]
* xref:0.27.adoc[0.27 Release Notes]
* xref:0.26.adoc[0.26 Release Notes]
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
dependabot[bot]
