Pkl 0.33 Release Notes

Support for generic methods has been greatly expanded (#1849, #1940).

A generic method is a method that accepts types as arguments. This is a powerful tool that allows writing business logic that works over a variety of types.

For example, this code declares two parameters: type parameter T, and value parameter arg.

Generic methods currently already exist in a limited sense:

In Pkl 0.33, both of these restrictions are lifted.

To pass type arguments into a generic method, add the type surrounded by angle brackets:

If type arguments are omitted entirely, it behaves as calling the method with the unknown type. The following two are logically identical:

This is a breaking change: in some cases, code that parses as a comparison expression now parses as a method call.

To read more about generic methods, consult the language reference.

To learn more about the design of generic method calls, consult SPICE-0032.

A new standard library module is introduced called pkl:net, for working with network types (#1834).

Its centerpiece is Url, a URL as defined by RFC 3986. A string is parsed with Url(), which accepts an absolute URL as well as a relative reference, and which throws if the string cannot be parsed:

Parsing is lenient: whatever cannot appear literally in a component is percent-encoded as its UTF-8 bytes, and whatever is already encoded is kept as written. Every component is held percent-encoded in its raw property, whether the input was encoded or not; the percent-decoded form of each is available as userInfo, host, path, query, and fragment. The derived pathSegments and queryParameters are percent-decoded too.

A URL can also be built from its components, or derived from another URL by amending it. A component given this way has to be percent-encoded already:

Each component is type-checked, so a URL built this way cannot be malformed. For example, a rawPort can only hold digits, only a URL with a rawHost can have one, and a rawPath of "/a b" is rejected. The decoded components are fixed, so they cannot be amended.

A relative reference can be resolved against an absolute URL, which also removes dot segments from the result’s path:

Comparing two URLs with == compares their components as written. To instead compare them as the syntax-based normalization of RFC 3986, where scheme and host are case-insensitive and percent-encoding is normalized, use equals():

The module also provides standalone helpers: encodeUrlComponent() and decodeUrlComponent() for percent-encoding, and buildQuery() and parseQuery() for application/x-www-form-urlencoded queries.

Alongside this module, pkl:base gains String.isValidUrl, which tells whether a string is a valid absolute URL. It is stricter than net.Url(), which also parses a relative reference, and which percent-encodes whatever cannot appear literally in a URL component. The Uri typealias is now defined in terms of it, which is a breaking change.

A new standard library module is introduced called pkl:syntax, for working with Pkl source code (#1821, #1964, #1955).

It has three parts:

A new C library, libpkl, is introduced (#1238, #1799, #1801, #1805, #1812).

One of Pkl’s selling points is the ability to embed the language into another runtime as a library. However, currently, callers from non-JVM languages must spawn Pkl as a child process. This introduces a system dependency on downstream users, and also introduces complexity and overhead for the operating system.

To address this pain point, a new library called libpkl is released for the C language.

This is a low-level library meant to be called into from language binding libraries. It exposes the message passing API through a small C interface (pkl.h).

Archives containing the header, both static and dynamic (shared) libraries, and pkg-config files are published for each supported OS and architecture, as part of the GitHub release.

To read more about libpkl, consult the libpkl documentation.

To read more about the design of this feature, consult SPICE-0015.

Thank you to @KushalP for their contributions to this feature!

The Pkl CLI can now profile where an evaluation spends its CPU time (#1823, #1931).

Profiling is enabled by passing --profile-cpu-output, which sets the file to write the profile to. The profile is written in pprof format, so it can be explored with any tool that reads it, such as go tool pprof.

Profiling is only exposed through the CLI. For more details, consult the CLI documentation.

The this keyword can now be used as a type (#1708, #1962).

A self type is the type of the object that a member is accessed on. Self types are useful when building class hierarchies, because they let a member refer to the same type as the object it belongs to, even after the class is extended.

Currently, Pkl has a self-type, module, but it specifically describes the type of the module object. There is no equivalent for regular classes nor objects.

To address this shortcoming, the this keyword is now also a type. It refers to the self-type of the directly enclosing object, class, or module.

When a class is extended, this in an inherited member refers to the subclass, not to the class that declares the member:

The this type can be used in properties, method parameters and return types, function types, and type arguments. It cannot be used in a type alias body.

The this type has also been adopted in the standard library.

To read more about the design, see SPICE-0029.

The new {} expression can now correctly infer its parent in more positions (#1768, #1824, #1845, #1847, #1857).

An implicitly typed new {} expression tells Pkl to infer the parent when amending. When used inside a property, for example, it amends the class property default.

Using new {} in the following positions currently throw, and will work in Pkl 0.33:

Inference is not available where the parameter type is not known ahead of time. Additionally, it cannot be used for constructor methods like List(), generic methods like Pair(), and Function.apply().

It is an error for the parameter type to be this or module.

Pkl now supports parsing .netrc files to configure HTTP Basic authentication headers (#1817, #1854).

A new method is introduced called netRcHeaders() on class pkl.EvaluatorSettings#Http.

It can be used to read credentials directly from a local .netrc file and mapped to HTTP Authorization headers:

It follows standard curl parsing rules, supporting comments, quoted values, and escaped characters.

Thank you to @ayashjorden for their contributions to this feature!

Native pkl and pkldoc binaries for Intel Mac systems are no longer published with Pkl releases (#1769).

To continue running new Pkl releases on these systems, use an appropriate Java runtime and the jpkl and jpkldoc Java executables.

Currently, type arguments to the Class type are erased. Any Class value would typecheck against Class<T> for any value of T.

In Pkl 0.33, this erasure has been removed. A Class value typechecked against Class<T> must be a subclass of T (#1698).

If T does not resolve to a class type (i.e. it is a union type, nullable type, string literal type, parameterized type, or nothing), the type check will always fail.

Some properties within the pkl:math and pkl:release modules have been marked const (#1864).

Currently, module properties in pkl:math and pkl:release can be overridden by amending the module. Doing this makes little sense; these values are constants and overriding them by amending their module would be odd.

The following properties are now const and cannot be amended:

This is a breaking change for code that looks like this:

The join method in List, Set, and Listing will now call the toString() method if overridden on an object (#1872).

This is a breaking change, but is also considered a bugfix.

The following snippet will produce different results:

Currently, Pkl ignores the toString() override, and produces:

In Pkl 0.33, the overridden toString() will be called, and produces:

The Uri typealias in pkl:base is now String(isValidUrl) instead of a plain String (#1834).

A value typed as Uri must be a valid absolute URL according to RFC 3986. This means that a relative reference, or a URL containing a character that must be percent-encoded, no longer type-checks:

This affects every standard library member typed as Uri, among them Resource.uri, importGraph(), and the URI-valued properties of pkl:Project, pkl:EvaluatorSettings and pkl:DocPackageInfo.

As a consequence, an invalid URI is now reported as a type constraint violation at the point where it is set, rather than as an error raised later by whatever consumes it.

As part of the introduction of generic methods, the Reference() constructor method in pkl:ref takes the domain and referent types as type arguments instead of taking a Class parameter (#1849). This also makes it possible to construct references to non-class types, such as Listing<String> or String | Int.

The ref.Domain class has been renamed to ref.AbstractDomain.

To support generic method calls, the syntax for Pkl has changed to permit passing type arguments when calling a method.

This purposefully introduces an ambiguity to the grammar: the following expression can be parsed as either a generic method call, or as nested comparison expressions:

To resolve such ambiguities, such code is preferably parsed as a generic method call.

This contrived example is nonsensical today, because it is an error to compare a boolean. However, there are times when such code might be written in a well-formed way, for example:

In Pkl 0.33, this above snippet will interpret bar as a generic method call. To restore the old meaning, wrap the left-hand side with parentheses:

The catch() and catchOrNull() methods now fully evaluate the value returned by the function they are given (#1910).

Currently, an error nested inside the returned value was not caught. It surfaced later, when the value was used. In Pkl 0.33, it is caught, and catch() returns its message.

When extending an abstract class or module, it is now an error if any abstract methods are not implemented.

In the following snippet, class Swallow is invalid because it does not implement canCarry:

The module type should no longer be used inside typealiases, class bodies, annotation bodies, and const scopes. Such usages will emit a deprecation warning, and will become a full error in Pkl 0.34 (#1708).

The module type is a self-type, which refers to the this of the module. When a module is extended, the module type refers to the extending module. On the other hand, the definition of classes and typealiases cannot be changed by an extending module.

The following snippet is misleading, because the module property friend is a self-type, whereas class property Feature.animal is not.

To have clearer semantics, the module type can no longer be used inside const scopes.

In most cases, such code should be replaced with a self-import.

The pkl:protobuf module is deprecated without replacement (#1778).

The protobuf module renders Pkl data into the "textproto" format. However, Pkl is more expressive than protobuf, which means that Pkl’s renderer needs to make rendering choices that are bespoke to Pkl’s protobuf renderer.

For example, there is no native equivalent for Pkl’s null literal. To address this, Pkl’s protobuf renderer renders these as a "null" scalar.

These rendering choices are somewhat ad-hoc and likely to break from one usage to the next.

Users of protobuf are encouraged render Pkl into ProtoJSON instead.