Language Reference

A value of type Int is a 64-bit signed integer.

Integer literals can be written in decimal, hexadecimal, binary, or octal notation:

Integers can optionally include an underscore as a separator to improve readability. An underscore does not affect the integer’s value.

Negative integer literals start with a minus sign, as in -123.

Integers support the standard comparison operators:

Integers support the following arithmetic operators:

Arithmetic overflows are caught and result in an error.

To restrict an integer’s range, use one of the predefined type aliases or an isBetween type constraint:

A value of type Float is a 64-bit double-precision floating point number.

Float literals use decimal notation. They consist of an integer part, decimal point, fractional part, and exponent part. The integer and exponent part are optional.

Negative float literals start with a minus sign, as in -1.23.

The special float values not a number, positive infinity, and negative infinity are written as:

The NaN and Infinity properties are defined in the standard library.

Floats support the same comparison and arithmetic operators as integers. Float literals with zero fractional part can be safely replaced with integer literals. For example, it is safe to write 1.3 * 42 instead of 1.3 * 42.0.

Floats can also include the same underscore separater as integers. For example, 1_000.4_400 is a float whose value is equivalent to 1000.4400.

To restrict a float to a finite value, use the isFinite type constraint:

To restrict a float’s range, use the isBetween type constraint:

To embed the result of expression <expr> in a string, use \(<expr>):

Before a result is inserted, it is converted to a string:

To write a string that spans multiple lines, use a multiline string literal:

Multiline string literals are delimited by three double quotes ("""). String content and closing delimiter must each start on a new line.

The content of a multiline string starts on the first line after the opening quotes and ends on the last line before the closing quotes. Line breaks are included in the string and normalized to \n.

The previous multiline string is equivalent to this single line string. Notice that there is no leading or trailing whitespace.

String interpolation, character escape sequences, and Unicode escape sequences work the same as for single line strings:

Each content line must begin with the same whitespace characters as the line containing the closing delimiter, which are not included in the string. Any further leading whitespace characters are preserved. In other words, line indentation is controlled by indenting lines relative to the closing delimiter.

In the following string, lines have no leading whitespace:

In the following string, lines are indented between three and five spaces:

Some strings contain many verbatim backslash (\) or quote (") characters. A good example is regular expressions, which make frequent use of backslash characters for their own escaping. In such cases, using the escape sequences \\ and \" quickly becomes tedious and hampers readability.

Instead, leading/closing string delimiters can be customized to start/end with a pound sign (#). This also affects the escape character, which changes from \ to \#.

All backslash and quote characters in the following string are interpreted verbatim:

Escape sequences and string interpolation still work, and now start with \#:

More generally, string delimiters and escape character can be customized to contain n pound signs each, for n >= 1.

In the following string, n is 2. As a result, the string content is interpreted verbatim:

The String class offers a rich API. Here are just a few examples:

Let’s define an object with properties name and extinct:

To access an object property by name, use dot (.) notation:

Objects can be nested:

As you probably guessed, the nested property class can be accessed with dodo.taxonomy.class.

Like all values, objects are immutable, which is just a fancy (and short!) way to say that their properties never change. So what happens when Pigeon moves to a different street? Do we have to construct a new object from scratch?

Fortunately we don’t have to. An object can be amended to form a new object that only differs in selected properties. Here is how this looks:

As you can see, it is easy to construct a new object that overrides selected properties of an existing object, even if, as in our example, the overridden property is nested inside another object.

Let’s move on to Pkl’s secret sauce: the ability to define an object property’s value in terms of another property’s value, and the resulting late binding effect. Here is an example:

We have defined a hypothetical penguin object whose adultWeightInGrams property is defined in terms of the eggIncubation duration. Can you guess what happens when penguin is amended and its eggIncubation overridden?

As you can see, madeUpBird's adultWeightInGrams changed along with its eggIncubation. This is what we mean when we say that object properties are late-bound.

Late binding of properties is an incredibly useful feature for a configuration language. It is used extensively in Pkl code (especially in templates), and is the key to understanding how Pkl works.

Say we have the following object:

How can property name be removed?

The recipe for transforming an object is:

Equipped with this knowledge, let’s try to accomplish our objective:

The resulting dynamic object is equivalent to dodo, except that it no longer has a name property.

Pkl has two kinds of objects:

Note that every module is a typed object. Its properties implicitly define a class, and new properties cannot be added when amending the module.

A typed object is backed by a class. Let’s look at an example:

Congratulations, you have constructed your first typed object^[4]! How does it differ from a dynamic object?

The answer is that a typed object has a fixed structure prescribed by its class, which cannot be changed when amending the object:

Evaluating this, gives:

Class structure is also enforced when instantiating a class. Let’s try to override property name with a value of the wrong type:

Evaluating this, also fails:

Typed objects are the fundamental building block for constructing validated data models in Pkl. To dive deeper into this topic, continue with Classes.

Listings have a literal syntax that is similar to that of objects. Here is a listing with two elements:

To access an element by index, use the [] (subscript) operator:

Listings can contain arbitrary types of elements:

Listings can have local properties:

Let’s say we have the following listing:

To add, override, or amend elements of this listing, amend the listing itself:

A listing element can be defined in terms of another element. To reference the element at index <index>, use this[<index>]:

Listing elements are late-bound:

Say we have the following listing:

How can the order of elements be reversed programmatically?

The recipe for transforming a listing is:

Equipped with this knowledge, let’s try to accomplish our objective:

result now contains the same elements as birds, but in reverse order.

Listings can have a default element:

default is a hidden (that is, not rendered) property defined in class Listing. If birds had a type annotation, a suitable default element would be inferred from its type parameter. If, as in our example, no type annotation is provided or inherited, the default element is the empty Dynamic object.

Like regular listing elements, the default element is late-bound. As a result, defaults can be changed retroactively:

Because both of birds's elements amend the default element, changing the default element also changes them. An equivalent literal definition of birds2 would look as follows:

Note that Parrot kept its diet because its prior self defined it explicitly, overriding any default.

If you are interested in the technical underpinnings of default elements (and not afraid of dragons!), continue with Function Amending.

To declare the type of a property that is intended to hold a listing, use:

This declaration has the following effects:

Here is an example:

Because the default value for type Bird is new Bird {}, that value becomes the listing’s default element.

Let’s go ahead and populate birds:

Thanks to birds's default element, which was inferred from its type, it is not necessary to state the type of each list element (new Bird { …​ }, new Bird { …​ }, etc.).

Mappings have the same literal syntax as objects, except that keys enclosed in [] take the place of property names. Here is a mapping with two entries:

To access a value by key, use the [] (subscript) operator:

Mappings can contain arbitrary types of values:

Although string keys are most common, mappings can contain arbitrary types of keys:

Keys can be computed:

Mappings can have local properties:

Let’s say we have the following mapping:

To add, override, or amend entries of this mapping, amend the mapping:

A mapping entry’s value can be defined in terms of another entry’s value. To reference the value with key <key>, use this[<key>]:

Mapping values are late-bound:

Say we have the following mapping:

How can birds's keys be reversed programmatically?

The recipe for transforming a mapping is:

Equipped with this knowledge, let’s try to accomplish our objective:

result contains the same values as birds, but its keys have changed to "noegiP" and "torraP".

Mappings can have a default value:

default is a hidden (that is, not rendered) property defined in class Mapping. If birds had a type annotation, a suitable default value would be inferred from its second type parameter. If, as in our example, no type annotation is provided or inherited, the default value is the empty Dynamic object.

Like regular mapping values, the default value is late-bound. As a result, defaults can be changed retroactively:

Because both of birds's mapping values amend the default value, changing the default value also changes them. An equivalent literal definition of birds2 would look as follows:

Note that Parrot kept its lifespan because its prior self defined it explicitly, overriding any default.

If you are interested in the technical underpinnings of default values, continue with Function Amending.

To declare the type of a property that is intended to hold a mapping, use:

This declaration has the following effects:

Here is an example:

Because the default value for type Bird is new Bird {}, that value becomes the mapping’s default value.

Let’s go ahead and populate birds:

Thanks to birds's default value, which was inferred from its type, it is not necessary to state the type of each mapping value (["Pigeon"] = new Bird { …​ }, ["Parrot"] = new Bird { …​ }, etc.).

Pkl supports single inheritance with a Java(Script) like syntax.

Modules are the unit of loading, executing, and sharing Pkl code. Every file containing Pkl code is a module. By convention, module files have a .pkl extension.

Modules have a Module Name and are loaded from a Module URI.

At runtime, modules are represented as objects of type Module. The precise runtime type of a module is a subclass of Module containing the module’s property and method definitions.

Like class members, module members may have type annotations, which are validated at runtime:

Because modules are regular objects, they can be assigned to properties and passed to and returned from methods.

Modules can be imported by other modules. In analogy to objects, modules can serve as templates for other modules through amending. In analogy to classes, modules can be extended to add additional module members.

Modules may declare their name by way of a module clause, which consists of the keyword module followed by a qualified name:

A module clause must come first in a module. Its doc comment, if present, holds the module’s overall documentation.

In the absence of a module clause, a module’s name is inferred from the module URI from which the module was first loaded. For example, the inferred name for a module first loaded from https://example.com/pkl/bird.pkl is bird.

Module names do not affect evaluation but are used in diagnostic messages and Pkldoc. In particular, they are the first component (everything before the hash sign) of fully qualified member names such as pkl.base#Int.

Modules are loaded from module URIs.

By default, the following URI types are available for import:

Recall how an object is amended:

Amending a module works in the same way, except that the syntax differs slightly:

A module is amended by way of an amends clause, which consists of the keyword amends followed by the module URI of the module to amend.

An amends clause comes after the module clause (if present) and before any import clauses:

At most one amends clause is permitted. A module cannot have both an amends clause and an extends clause.

An amending module has the same type (that is, module class) as the module it amends. As a consequence, it cannot define new properties, methods, or classes, unless they are declared as local. In our example, this means that module parrot can only define (and thus override) the property name. Spelling mistakes such as namw are caught immediately, rather than accidentally defining a new property.

Amending is used to fill in template modules:

Template modules are often provided by third parties and served over HTTPS.

Recall how a class is extended:

Extending a module works in the same way, except that the syntax differs slightly:

A module is extended by way of an extends clause, which consists of the keyword extends followed by the module URI of the module to extend. The extends clause comes after the module clause (if present) and before any import clauses. Only modules declared as open can be extended.

At most, one extends clause is permitted. A module cannot have both an amends clause and an extends clause.

Extending a module implicitly defines a new module class that extends the original module’s class.

A module import makes the imported module accessible to the importing module. A module is imported by way of either an import clause, or an import expression.

Multiple modules may be imported at once with import*. When importing multiple modules, a glob pattern is used to match against existing resources. A globbed import evaluates to a Mapping, where keys are the expanded form of the glob and values are import expressions on each individual module.

Globbed imports can be expressed as either a clause, or as an expression. When expressed as a clause, they follow the same naming rules as a normal import clause: they introduce a local property equal to the last path segment without the .pkl extension. A globbed import clause cannot be used as a type.

Assuming that a file system contains these files:

The following two snippets are logically identical:

By default, only the file and package schemes are globbable. Globbing another scheme will cause Pkl to throw.

Pkl can be extended to provide custom globbable schemes through the ModuleKey SPI.

When globbing within packages, only the asset path (the fragment section) is globbable. Otherwise, characters are interpreted verbatim, and not treated as glob wildcards.

For details on how glob patterns work, refer to Glob Patterns in the Advanced Topics section.

When attempting to directly evaluate a module, as in pkl eval myModule.pkl, the following security checks are performed:

The module allowlist is a comma-separated list of regular expressions. For access to be granted, at least one regular expression must match a prefix of the module URI. For example, the allowlist file:,https: grants access to any module whose URI starts with file: or https:.

When a module attempts to load another module (via amends, extends, or imports), the following security checks are performed:

For access to be granted, the source module’s trust level must be higher than or equal to the target module’s trust level. By default, there are five trust levels, listed from highest to lowest:

For example, this means that file: modules can import https: modules, but not the other way around.

If a module URI is resolved in multiple steps, all URIs are subject to the above security checks. An example for this is an HTTPS URL that results in a redirect.

Pkl embedders can further customize security checks.

By default, the output of evaluating a module is the entire module rendered as Pcf. There are two ways to change this behavior:

The !! (non-null) operator asserts that its operand is non-null. Here are some examples:

The ?? (null coalescing) operator fills in a default for a null value.

The above expression evaluates to value if value is non-null, and to default otherwise. Here are some examples:

The ?. (null propagation) operator provides null-safe access to a member whose receiver may be null.

The above expression evaluates to value.member if value is non-null, and to null otherwise. Here are some examples:

The ?. operator is often combined with ??:

The ifNonNull() method is a generalization of the null propagation operator.

The above expression evaluates to doSomethingWith(name) if name is non-null, and to null otherwise. Here are some examples:

To express that a property can have any type except Null, use the NonNull type alias:

If a resource does not exist or cannot be read, read() fails with an error. To recover from the absence of a resource, use read?() instead, which returns null for absent resources:

Multiple resources may be read at the same time with read*(). When reading multiple resources, a glob pattern is used to match against existing resources. A globbed read returns a Mapping, where the keys are the expanded form of the glob, and values are read expressions on each individual resource.

Assuming that a file system contains these files:

The following two snippets are logically identical:

By default, the following schemes support globbing:

Globbing other resources results in an error.

For details on how glob patterns work, reference Glob Patterns in the Advanced Topics section.

When Pkl is embedded within another runtime, it can be extended to read other kinds of resources.

When embedded into a JVM application, new resources may be read by implementing the ResourceReader SPI. When Pkl is embedded within Swift, new resources may be read by implementing the ResourceReader interface. When Pkl is embedded within Go, new resources may be read by implementing the ResourceReader interface.

When attempting to read a resource, the resource URI is checked against the resource allowlist (--allowed-resources). In embedded mode, the allowlist is configured via an evaluator’s SecurityManager.

The resource allowlist is a comma-separated list of regular expressions. For access to be granted, at least one regular expression must match a prefix of the resource URI. For example, the allowlist file:,https: grants access to any resource whose URI starts with file: or https:.

A let expression is Pkl’s version of an (immutable) local variable. Its syntax is:

A let expression is evaluated as follows:

Here is an example:

let expressions serve two purposes:

let expressions can have type annotations:

let expressions can be stacked:

To test if a value conforms to a type, use the is operator.

All the following tests hold:

A value can be tested against any type, not just a class:

The as (type cast) operator performs a runtime type check on its operand. If the type check succeeds, the operand is returned as-is; otherwise, an error is thrown.

Although type casts are never mandatory in Pkl, they occasionally help humans and tools better understand an expression’s type.

A value of type List is an ordered, indexed collection of elements.

A list’s elements have zero-based indexes and are eagerly evaluated.

Lists are constructed with the List() method^[5]:

To concatenate lists, use the + operator:

To access a list element by index, use the [] (subscript) operator:

Class List offers a rich API. Here are just a few examples: