Pkl

https://pkl-lang.org/main/current/
Admin
Pkl is an embeddable configuration language providing rich support for data templating and...
Tokens:82,682
Snippets:1,226
Trust Score:8.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### CLI Version Output Example

Source: https://pkl-lang.org/main/current/java-binding/codegen.html

Example output when checking the version of the pkl-codegen-java CLI.

```shell
pkl-codegen-java 0.31.1 (macOS 14.2, Java 17.0.10)
```

--------------------------------

### Example Workshop Configuration

Source: https://pkl-lang.org/main/current/language-tutorial/03_writing_a_template.html

This is an example of a Pkl configuration file for a workshop. It includes various data types like strings, booleans, numbers, durations, nested objects, lists, and mappings.

```pkl
title = "Pkl: Configure your Systems in New Ways"
interactive = true
seats = 100
occupancy = 0.85
duration = 1.5.h
`abstract` = """
  With more systems to configure, the software industry is drowning in repetitive and brittle configuration files.
  YAML and other configuration formats have been turned into programming languages against their will.
  Unsurprisingly, they don’t live up to the task.
  Pkl puts you back in control.
  "

event {
  name = "Migrating Birds between hemispheres"
  year = 2024
}

instructors {
  "Kate Sparrow"
  "Jerome Owl"
}

sessions {
  new {
    date = "2/1/2024"
    time = 30.min
  }
  new {
    date = "2/1/2024"
    time = 30.min
  }
}

assistants {
  ["kevin"] = "Kevin Parrot"
  ["betty"] = "Betty Harrier"
}

agenda {
  ["beginners"] {
    name = "Basic Configuration"
    part = 1
    duration = 45.min
  }
  ["intermediates"] {
    name = "Filling out a Template"
    part = 2
    duration = 45.min
  }
  ["experts"] {
    name = "Writing a Template"
    part = 3
    duration = 45.min
  }
}

```

--------------------------------

### String API Examples

Source: https://pkl-lang.org/main/current/language-reference/index.html

Provides examples of common String class methods: length, reverse, contains, and trim.

```pkl
strLength = "dodo".length __**(1)**
reversedStr = "dodo".reverse() __**(2)**
hasAx = "dodo".contains("alive") __**(3)**
trimmed = "  dodo  ".trim() __**(4)**
```

--------------------------------

### Install Pkl with Mise

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Install and manage Pkl versions using Mise on macOS, Linux, and Windows. Use the global flag for system-wide installation or omit for local project installation.

```shell
# Install and activate Pkl globally
mise use -g pkl@0.31.1

# Install and activate Pkl locally
mise use pkl@0.31.1
```

--------------------------------

### Doc Comments Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Demonstrates basic list and map operations, and a helper function.

```Pkl
birds = List("Robin", "Swallow", "Eagle", "Falcon")
indexes = birds.mapIndexed((i, _) -> i)

function constantly(_, second) = second
```

--------------------------------

### Set API Examples

Source: https://pkl-lang.org/main/current/language-reference/index.html

Provides examples of common Set operations in Pkl, including checking for containment, subset operations, mapping, and intersection.

```pkl
set = Set(1, 2, 3, 4)
res1 = set.contains(3) __**(1)**
res2 = set.drop(1).take(2) __**(2)**
res3 = set.map((n) -> n * 3) __**(3)**
res4 = set.intersect(Set(3, 9, 2)) __**(4)**
```

--------------------------------

### Package Asset URI Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Example of a package asset URI used to import a module from a package.

```text
package://example.com/mypackage@1.0.0#/my_module.pkl
```

--------------------------------

### NoProxy Configuration Example

Source: https://pkl-lang.org/main/current/bindings-specification/message-passing-api.html

Example of how to configure `noProxy` settings, specifying hosts and IP addresses that should bypass proxy servers. Supports CIDR notation and wildcard entries.

```pkl
noProxy {
  "127.0.0.1"
  "169.254.0.0/16"
  "example.com"
  "localhost:5050"
}
```

--------------------------------

### Install Pkl with Windows Package Manager

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Install the Pkl release version on Windows using the Windows Package Manager (winget).

```shell
winget install Apple.Pkl
```

--------------------------------

### List Hatchlings Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Demonstrates creating a list of hatchlings using typedProperty.listHatchlings.

```pkl
swiftHatchlings = typedProperty.listHatchlings(new {
  "Poppy"
  "Chirpy"
})
```

--------------------------------

### Download and Install Windows Pkl Executable

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Manually download and install the native Pkl executable for Windows. Ensure the downloaded file is executable and check the version.

```powershell
Invoke-WebRequest 'https://github.com/apple/pkl/releases/download/0.31.1/pkl-windows-amd64.exe' -OutFile pkl.exe
.
pkl --version
```

--------------------------------

### Comprehensive Doc Comment Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

A detailed example showcasing doc comments for a module, class, type alias, property, and function in Pkl.

```Pkl
/// An aviated animal going by the name of [bird](https://en.wikipedia.org/wiki/Bird).
///
/// These animals live on the planet Earth.
module com.animals.Birds

/// A bird living on Earth.
///
/// Has [name] and [lifespan] properties and an [isOlderThan()] method.
class Bird {
  /// The name of this bird.
  name: String

  /// The lifespan of this bird.
  lifespan: UInt8

  /// Tells if this bird is older than [bird].
  function isOlderThan(bird: Bird): Boolean = lifespan > bird.lifespan
}

/// An adult [Bird].
typealias Adult = Bird(lifespan >= 2)

/// A common [Bird] found in large cities.
pigeon: Bird = new {
  name = "Pigeon"
  lifespan = 8
}
```

--------------------------------

### Map API Examples

Source: https://pkl-lang.org/main/current/language-reference/index.html

Provides examples of common Map operations in Pkl, such as checking for key/value containment, emptiness, length, and retrieving values.

```pkl
map = Map("Pigeon", 5.gb, "Parrot", 10.gb)
res1 = map.containsKey("Parrot") __**(1)**
res2 = map.containsValue(8.gb) __**(2)**
res3 = map.isEmpty __**(3)**
res4 = map.length __**(4)**
res5 = map.getOrNull("Falcon") __**(5)**
```

--------------------------------

### Start Pkl REPL Session

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

To start an interactive REPL session, execute the 'pkl repl' command in your terminal.

```shell
$ pkl repl
Welcome to Pkl 0.31.1.
Type an expression to have it evaluated.
Type :help or :examples for more information.

pkl>
```

--------------------------------

### Install Pkl with Homebrew

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Use Homebrew to install the latest release version of Pkl on macOS and Linux.

```shell
brew install pkl
```

--------------------------------

### Example Module Content

Source: https://pkl-lang.org/main/current/language-reference/index.html

A simple Pkl module defining a username variable.

```pkl
username = "pigeon"

```

--------------------------------

### Output Directory Option Example

Source: https://pkl-lang.org/main/current/java-binding/codegen.html

Specify the directory where generated source code should be placed. Relative paths are resolved against the working directory. Example shows outputting to a 'generated/' directory.

```bash
-o generated/
```

--------------------------------

### Module Header Example

Source: https://pkl-lang.org/main/current/style-guide/index.html

Demonstrates the structure of a Pkl module header, including module, extends, and import clauses.

```Pkl
module com.example.Foo 

extends "Bar.pkl" 

import "baz.pkl"
import "Buz.pkl"
```

--------------------------------

### Let Binding Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Illustrates the use of a let binding with a trace statement.

```Pkl
name = let (_ = trace("defining name")) "Eagle"
```

--------------------------------

### Download and Install Java Pkl Executable (Windows)

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Download the Pkl Java executable (jar file) for Windows. This requires Java 17 or higher to be installed and available on the system path. Ensure the downloaded file is executable and check the version.

```powershell
Invoke-WebRequest 'https://repo1.maven.org/maven2/org/pkl-lang/pkl-cli-java/0.31.1/pkl-cli-java-0.31.1.jar' -OutFile jpkl.bat
.
pkl --version
```

--------------------------------

### File URI Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Represents a module located on the local file system.

```text
file:///path/to/my_module.pkl
```

--------------------------------

### List API Examples

Source: https://pkl-lang.org/main/current/language-reference/index.html

Demonstrates common operations on Pkl Lists, such as checking for containment, accessing elements, and transforming the list.

```pkl
list = List(1, 2, 3, 4)
res1 = list.contains(3) __**(1)**
res2 = list.first __**(2)**
res3 = list.rest __**(3)**
res4 = list.reverse() __**(4)**
res5 = list.drop(1).take(2) __**(5)**
res6 = list.map((n) -> n * 3) __**(6)**
```

--------------------------------

### Import Sorting Example

Source: https://pkl-lang.org/main/current/style-guide/index.html

Illustrates the recommended sorting order for import statements, separating package/relative imports with a blank line.

```Pkl
import "modulepath:/foo.pkl"
import "package://example.com/mypackage@1.0.0#/foo.pkl"

import "@mypackage/baz.pkl"

import ".../my/file/bar2.pkl"
import ".../my/file/bar11.pkl"
```

--------------------------------

### Run Pkl as a Server

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Starts the Pkl server, which communicates over standard input/output. This is intended for embedding Pkl functionality into external clients.

```shell
pkl server
```

--------------------------------

### Rename Option Examples

Source: https://pkl-lang.org/main/current/java-binding/codegen.html

Allows modification of default class and package names derived from Pkl module names. The examples illustrate literal prefix replacement and the behavior with and without trailing dots, as well as the longest matching prefix rule.

```bash
--rename com.foo.=x
--rename org.bar=y.
--rename net.baz=z

--rename com.foo.Main=w.Main
--rename com.foo.=x.
--rename com.=y.
--rename =z.
```

--------------------------------

### Download and Install Linux Pkl Executable (amd64)

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Manually download and install the native Pkl executable for Linux on amd64 architecture. This executable is dynamically linked against glibc and libstdc++. Ensure the downloaded file is executable and check the version.

```shell
curl -L -o pkl 'https://github.com/apple/pkl/releases/download/0.31.1/pkl-linux-amd64'
chmod +x pkl
./pkl --version
```

--------------------------------

### Download and Install macOS Pkl Executable (amd64)

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Manually download and install the native Pkl executable for macOS on amd64 architecture. Ensure the downloaded file is executable and check the version.

```shell
curl -L -o pkl 'https://github.com/apple/pkl/releases/download/0.31.1/pkl-macos-amd64'
chmod +x pkl
./pkl --version
```

--------------------------------

### Pigeon Module Example

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

A simple Pkl module defining metadata. This is used in conjunction with the 'Evaluate Pkl Expression' example.

```pkl
metadata {
  species = "Pigeon"
}
```

--------------------------------

### Trace Output Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Example of the output generated by a `trace` expression, showing the evaluated expression, its result, and its location.

```shell
pkl: TRACE: num1 * num2 = 672 (at file:///some/module.pkl, line 42)
```

--------------------------------

### Indent Option Example

Source: https://pkl-lang.org/main/current/java-binding/codegen.html

Configure the characters used for indenting generated source code. The default is two spaces. Example shows using a tab.

```bash
--indent "\t"
```

--------------------------------

### Download and Install Linux Pkl Executable (aarch64)

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Manually download and install the native Pkl executable for Linux on aarch64 architecture. This executable is dynamically linked against glibc and libstdc++. Ensure the downloaded file is executable and check the version.

```shell
curl -L -o pkl 'https://github.com/apple/pkl/releases/download/0.31.1/pkl-linux-aarch64'
chmod +x pkl
./pkl --version
```

--------------------------------

### Pkl Test Fact Example

Source: https://pkl-lang.org/main/current/release-notes/0.31.html

A Pkl test file demonstrating facts with 'add' and 'divide' functions.

```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
  }
}
```

--------------------------------

### Download and Install Java Pkl Executable (macOS/Linux)

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Download the Pkl Java executable (jar file) for macOS and Linux. This requires Java 17 or higher to be installed and available on the system path. Ensure the downloaded file is executable and check the version.

```shell
curl -L -o jpkl 'https://repo1.maven.org/maven2/org/pkl-lang/pkl-cli-java/0.31.1/pkl-cli-java-0.31.1.jar'
chmod +x jpkl
./jpkl --version
```

--------------------------------

### Type Cast Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Shows how to use the 'as' operator for a runtime type check and cast, primarily for clarity.

```pkl
birds {
  new { name = "Pigeon" }
  new { name = "Barn owl" }
}
names = birds.toList().map((it) -> it.name) as List<String>
```

--------------------------------

### Download and Install macOS Pkl Executable (aarch64)

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Manually download and install the native Pkl executable for macOS on aarch64 architecture. Ensure the downloaded file is executable and check the version.

```shell
curl -L -o pkl 'https://github.com/apple/pkl/releases/download/0.31.1/pkl-macos-aarch64'
chmod +x pkl
./pkl --version
```

--------------------------------

### Evaluating an Amended Pkl File

Source: https://pkl-lang.org/main/current/language-tutorial/02_filling_out_a_template.html

This example demonstrates how to evaluate the amended Pkl file to generate YAML output.

```bash
$ pkl eval -f yml /Users/me/tutorial/cicd.pkl
```

--------------------------------

### Download and Install Alpine Linux Pkl Executable (amd64)

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Manually download and install the Pkl executable for Alpine Linux on amd64 architecture. This executable is statically linked against musl libc and libstdc++. Ensure the downloaded file is executable and check the version.

```shell
curl -L -o pkl 'https://github.com/apple/pkl/releases/download/0.31.1/pkl-alpine-linux-amd64'
chmod +x pkl
./pkl --version
```

--------------------------------

### Link to pkl.base String

Source: https://pkl-lang.org/main/current/language-reference/index.html

Provides an example of linking to a member from the `pkl.base` module using its simple name.

```Pkl
/// Returns a [String].
```

--------------------------------

### Object Body Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Defines an object with a default behavior and specific behaviors for 'Falcon' and 'Eagle'.

```Pkl
birds = new Dynamic {
  default { _ ->
    species = "Bird"
  }
  ["Falcon"] {}
  ["Eagle"] {}
}
```

--------------------------------

### Standard Library URI Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Standard library modules are named `pkl.<simpleName>` and have module URIs of the form `pkl:<simpleName>`.

```text
pkl:math
```

--------------------------------

### Nullable Spread Syntax Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Shows the nullable spread syntax, which is equivalent to spreading within a 'when' condition to handle null values gracefully.

```pkl
result {
  ...?myValue
}
```

--------------------------------

### Pkl Settings File Example

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

This snippet shows a typical Pkl settings file that amends the default settings and configures IntelliJ IDEA as the preferred editor. Use this to customize your CLI environment.

```pkl
amends "pkl:settings"

editor = Idea
```

--------------------------------

### Importing the JSON Module in Pkl

Source: https://pkl-lang.org/main/current/standard-library.html

Demonstrates how to import the `pkl.json` module to use its functionalities. No specific setup is required beyond the import statement.

```Pkl
import "pkl:json"
```

--------------------------------

### Basic Arithmetic Operation

Source: https://pkl-lang.org/main/current/language-reference/index.html

A simple example of an arithmetic operation within a configuration file context.

```Pkl
a = x + 1
```

--------------------------------

### New Property Definitions (Bad)

Source: https://pkl-lang.org/main/current/style-guide/index.html

This example shows incorrect formatting for new property definitions, lacking a blank line between them.

```pkl
/// Denotes something.
myFoo: String
/// Something else
myOtherFoo: String
```

--------------------------------

### HTTP(S) URI Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Represents a module imported via an HTTP(S) GET request. Modules loaded from HTTP(S) URIs are only cached until the `pkl` command exits or the `Evaluator` object is closed.

```text
https://example.com/my_module.pkl
```

--------------------------------

### Define and Call Class and Module Methods

Source: https://pkl-lang.org/main/current/language-reference/index.html

Demonstrates defining an instance method on a class and a module method. Shows how to call both instance and module methods.

```Pkl
class Bird {
  name: String
  function greet(bird: Bird): String = "Hello, \(bird.name)!"
}

function greetPigeon(bird: Bird): String = bird.greet(pigeon)

pigeon: Bird = new {
  name = "Pigeon"
}
parrot: Bird = new {
  name = "Parrot"
}

greeting1 = pigeon.greet(parrot)
greeting2 = greetPigeon(parrot)
```

--------------------------------

### Dependency Notation URI Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Dependency notation URIs represent a path within a project or package dependency. When importing a relative directory or file that starts with `@`, the import string must be prefixed with `./`.

```text
@birds/bird.pkl
```

--------------------------------

### Generate Multiple Output Files (JSON and YAML)

Source: https://pkl-lang.org/main/current/language-reference/index.html

Configure `output.files` to produce multiple output files. Use the `--multiple-file-output-path` CLI option to specify the base directory. This example generates a JSON and a YAML file for different bird types.

```pkl
pigeon {
  name = "Pigeon"
  diet = "Seeds"
}
parrot {
  name = "Parrot"
  diet = "Seeds"
}
output {
  files {
    ["birds/pigeon.json"] {
      value = pigeon
      renderer = new JsonRenderer {}
    }
    ["birds/parrot.yaml"] {
      value = parrot
      renderer = new YamlRenderer {}
    }
  }
}
```

--------------------------------

### Running a Pkl CLI Command

Source: https://pkl-lang.org/main/current/release-notes/0.31.html

Demonstrates how to execute a Pkl CLI command using 'pkl run' with arguments and options.

```bash
$ pkl run bird-generator.pkl pigeon --aggregate=mean Pigeon=1 Hawk=8 Eagle=3
```

--------------------------------

### Doc Comment Example

Source: https://pkl-lang.org/main/current/style-guide/index.html

Use doc comments to provide information to module users. Include a one-sentence summary followed by additional details, notes, and links.

```pkl
/// The time allotted for eating lunch.
///
/// Note:
/// * Hamburgers typically take longer to eat than salad.
/// * Pizza gets prepared per-order.
///
/// Orders must be placed on-prem.
/// See <https://cafeteria.com> for more details.
lunchHours: Duration
```

--------------------------------

### Object Member Spacing (Bad)

Source: https://pkl-lang.org/main/current/style-guide/index.html

This example demonstrates incorrect spacing with too many blank lines between object members.

```pkl
foo = "bar"


baz = "buz"
```

--------------------------------

### Evaluate Multiple Tutorial Part Instances

Source: https://pkl-lang.org/main/current/language-tutorial/03_writing_a_template.html

Evaluates the 'pklTutorialParts.pkl' file, showing the output for all three tutorial part instances, including inherited and amended properties.

```Shell
$ pkl eval pklTutorialParts.pkl
pklTutorialPart1 {
  name = "Basic Configuration"
  part = 1
  hasExercises = true
  amountLearned = 13.37
  duration = 30.min
  bandwidthRequirementPerSecond = 52.4288.mb
}
pklTutorialPart2 {
  name = "Filling out a Template"
  part = 2
  hasExercises = true
  amountLearned = 13.37
  duration = 30.min
  bandwidthRequirementPerSecond = 52.4288.mb
}
pklTutorialPart3 {
  name = "Writing a Template"
  part = 3
  hasExercises = true
  amountLearned = 13.37
  duration = 30.min
  bandwidthRequirementPerSecond = 52.4288.mb
}
```

--------------------------------

### Pkl Module Example (metadata)

Source: https://pkl-lang.org/main/current/pkl-gradle/index.html

A simple Pkl module defining a 'metadata' object with a 'name' property. This can be used with the 'expression' configuration option.

```pkl
metadata {
  name = "my-pod"
}
```

--------------------------------

### Define a Class with Multiple Properties and Instantiate

Source: https://pkl-lang.org/main/current/language-tutorial/03_writing_a_template.html

Defines a 'TutorialPart' class with various properties including String, Int, Boolean, Float, Duration, and DataSize. It then instantiates three properties of this class, with 'pklTutorialPart2' and 'pklTutorialPart3' amending 'pklTutorialPart1'.

```Pkl
class TutorialPart {
  name: String

  part: Int

  hasExercises: Boolean

  amountLearned: Float

  duration: Duration

  bandwidthRequirementPerSecond: DataSize
}

pklTutorialPart1: TutorialPart = new {
  name = "Basic Configuration"
  part = 1
  hasExercises = true
  amountLearned = 13.37
  duration = 30.min
  bandwidthRequirementPerSecond = 50.mib.toUnit("mb")
}

pklTutorialPart2: TutorialPart = (pklTutorialPart1) {
  name = "Filling out a Template"
  part = 2
}

pklTutorialPart3: TutorialPart = (pklTutorialPart1) {
  name = "Writing a Template"
  part = 3
}
```

--------------------------------

### Verify Kotlin Code Generator CLI Version

Source: https://pkl-lang.org/main/current/kotlin-binding/codegen.html

Example output confirming the version of the Kotlin code generator CLI.

```shell
pkl-codegen-kotlin 0.31.1 (macOS 14.2, Java 17.0.10)
```

--------------------------------

### Example Rename Mapping

Source: https://pkl-lang.org/main/current/kotlin-binding/codegen.html

Demonstrates how rename mappings affect generated code for packages and classes. Longest matching prefix is used.

```bash
--rename com.foo.=x  // Dot on the left only
--rename org.bar=y.  // Dot on the right only
--rename net.baz=z   // No dots
```

```bash
// The following renames will be made:
"com.foo.bar" -> "xbar"       // Target prefix merged into the suffix
"org.bar.baz" -> "y..baz"     // Double dot, invalid name
"net.baz.qux" -> "z.qux"      // Looks okay, but...
"net.bazqux"  -> "zqux"       // ...may cut the name in the middle.
```

```bash
// Assuming the following arguments:
--rename com.foo.Main=w.Main
--rename com.foo.=x.
--rename com.=y.
--rename =z.

// The following renames will be made:
com.foo.Main -> w.Main
com.foo.bar  -> x.bar
com.baz.qux  -> y.baz.qux
org.foo.bar  -> z.org.foo.bar
```

--------------------------------

### Configure Object Members with Member Predicates

Source: https://pkl-lang.org/main/current/language-reference/index.html

Configures all object members matching a predicate, useful for elements that cannot be accessed by key. This example configures environment variables.

```pkl
environmentVariables {
  new { name = "PIGEON"; value = "pigeon-value" }
  new { name = "PARROT"; value = "parrot-value" }
  new { name = "BARN OWL"; value = "barn-owl-value" }
}
```

--------------------------------

### Aggregate Module Outputs with Dynamic File Extensions

Source: https://pkl-lang.org/main/current/language-reference/index.html

Aggregate module outputs by referencing their `output` property within `output.files`. This example dynamically determines file extensions based on the renderer.

```pkl
import "pigeon.pkl"
import "parrot.pkl"

output {
  files {
    ["birds/pigeon.\(pigeon.output.renderer.extension)"] = pigeon.output
    ["birds/parrot.\(parrot.output.renderer.extension)"] = parrot.output
  }
}
```

--------------------------------

### Download and Execute Kotlin Code Generator CLI (Windows)

Source: https://pkl-lang.org/main/current/kotlin-binding/codegen.html

Download the Kotlin code generator CLI using Invoke-WebRequest, and verify the installation by checking the version.

```powershell
Invoke-WebRequest 'https://github.com/apple/pkl/releases/download/0.31.1/pkl-codegen-kotlin' -OutFile pkl-codegen-kotlin.bat
.\pkl-codegen-kotlin --version
```

--------------------------------

### Import and Use TutorialPart for Agenda

Source: https://pkl-lang.org/main/current/language-tutorial/03_writing_a_template.html

This snippet imports the 'TutorialPart' module and defines 'agenda' as a Mapping from String to TutorialPart. This reuses an existing type definition.

```pkl
import "TutorialPart.pkl"

agenda: Mapping<String, TutorialPart>

```

--------------------------------

### Configure Environment Variables (Map)

Source: https://pkl-lang.org/main/current/pkl-gradle/index.html

Set environment variables that can be read by Pkl code using the 'env:' scheme. This example shows setting multiple variables.

```gradle
environmentVariables = ["MY_VAR_1": "myValue1", "MY_VAR_2": "myValue2"]

```

--------------------------------

### Download and Execute Kotlin Code Generator CLI (macOS/Linux)

Source: https://pkl-lang.org/main/current/kotlin-binding/codegen.html

Download the Kotlin code generator CLI using curl, make it executable, and verify the installation by checking the version.

```shell
curl -L -o pkl-codegen-kotlin 'https://github.com/apple/pkl/releases/download/0.31.1/pkl-codegen-kotlin'
chmod +x pkl-codegen-kotlin
./pkl-codegen-kotlin --version
```

--------------------------------

### Module URI Best Practice

Source: https://pkl-lang.org/main/current/style-guide/index.html

Demonstrates the preferred use of triple-dot Module URIs for referencing ancestor modules to avoid excessive '../'.

```Pkl
amends ".../ancestor.pkl"

import ".../ancestor2.pkl"
```

--------------------------------

### Configure Output Directory

Source: https://pkl-lang.org/main/current/pkl-gradle/index.html

Sets the directory where generated Pkldoc documentation will be placed. Defaults to `layout.buildDirectory.dir("pkldoc/<generator_name>")`.

```groovy
outputDir = layout.projectDirectory.dir("pkl-docs")
```

--------------------------------

### Empty List Creation

Source: https://pkl-lang.org/main/current/language-reference/index.html

Demonstrates creating an empty list using the List() constructor.

```pkl
list1 = List()
```

--------------------------------

### Generator Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Uses a generator to create a list of bird names from a map of bird colors.

```Pkl
birdColors = Map("Robin", "blue", "Eagle", "white", "Falcon", "red")

birds = new Listing {
  for (name, _ in birdColors) {
    name
  }
}
```

--------------------------------

### Evaluate Module URIs

Source: https://pkl-lang.org/main/current/language-reference/index.html

Demonstrates how to evaluate modules using various URI types directly from the command line.

```shell
$ pkl eval path/to/mymodule.pkl
```

```shell
$ pkl eval file:///path/to/my_module.pkl
```

```shell
$ pkl eval https://apple.com/path/to/mymodule.pkl
```

```shell
$ pkl eval --module-path=/pkl-modules modulepath:/path/to/my_module.pkl
```

```shell
$ pkl eval pkl:math
```

--------------------------------

### Use Non-Null Operator

Source: https://pkl-lang.org/main/current/language-reference/index.html

The `!!` operator asserts that its operand is non-null. This example applies it to a string variable.

```pkl
name = "Pigeon"
nameNonNull = name!!  __**(1)**
```

--------------------------------

### Extending a Class in Pkl

Source: https://pkl-lang.org/main/current/language-reference/index.html

Example of extending a class in Pkl, inheriting and overriding properties and methods.

```pkl
open class Pigeon {
  name = "Pigeon"
  diet = "Seeds"
}

class Parrot extends Pigeon {
  name = "Parrot"
  diet = "Berries"
  extinct = false

  function say() = "Pkl is great!"
}
```

--------------------------------

### Assigning Anonymous Functions to Properties

Source: https://pkl-lang.org/main/current/language-reference/index.html

An example of assigning an anonymous function to a property to give it a name, and then invoking it.

```pkl
add = (a, b) -> a + b
added = add.apply(2, 3)
```

--------------------------------

### Object Initialization with `new` (Good)

Source: https://pkl-lang.org/main/current/style-guide/index.html

When initializing a Typed object using `new`, omit the type. Use `new {}` instead of `new Foo {}`.

```pkl
myFoo: Foo = new { foo = "bar" }
```

```pkl
open class Foo {}
class Bar extends Foo {}

foo: Foo = new Bar {}
```

--------------------------------

### Defining a Typed Object Class

Source: https://pkl-lang.org/main/current/language-reference/index.html

Example of defining a class for a typed object with specific properties and their types.

```pkl
class Bird {
  name: String
  lifespan: Int
  migratory: Boolean
}
```

--------------------------------

### Indentation: Assignment operator on same line

Source: https://pkl-lang.org/main/current/style-guide/index.html

If an assignee starts on the same line as the assignment, no extra indentation is needed for its content.

```pkl
foo = new {
  baz = "baz"
  biz = "biz"
}
```

```pkl
foo = new {
    baz = "baz"
    biz = "biz"
  }
```

--------------------------------

### Anonymous Function Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

A simple anonymous function that accepts a parameter 'n', multiplies it by 3, and returns the result.

```pkl
(n) -> n * 3
```

--------------------------------

### Construct Binary Data Sizes

Source: https://pkl-lang.org/main/current/language-reference/index.html

Demonstrates constructing data sizes using binary units (powers of 1024). Units range from bytes to pebibytes.

```pkl
datasize1 = 5.b
datasize2 = 5.kib
datasize3 = 5.mib
datasize4 = 5.gib
datasize5 = 5.tib
datasize6 = 5.pib
```

--------------------------------

### Map Construction

Source: https://pkl-lang.org/main/current/language-reference/index.html

Shows how to construct Maps in Pkl, including empty maps, maps with key-value pairs, and nested maps.

```pkl
map1 = Map() __**(1)**
map2 = Map(1, "one", 2, "two", 3, "three") __**(2)**
map3 = Map(1, "x", 2, 5.min, 3, Map(1, 2)) __**(3)**
```

--------------------------------

### Incorrect Block Comment Formatting

Source: https://pkl-lang.org/main/current/style-guide/index.html

This example shows incorrect formatting for a single-line block comment, lacking spaces after `/*` and before `*/`.

```pkl
/*Let's have a zebra party*/
```

--------------------------------

### Configuring HTTP Rewrites for Package Mirroring

Source: https://pkl-lang.org/main/current/language-reference/index.html

Illustrates how to use the `--http-rewrite` option to direct Pkl to download packages from a custom mirror URL instead of the default internet location. This requires separate rewrites for package metadata and package zip files.

```bash
--http-rewrite https://pkg.pkl-lang.org/=\https://my.internal.mirror/
```

--------------------------------

### Construct Decimal Data Sizes

Source: https://pkl-lang.org/main/current/language-reference/index.html

Demonstrates constructing data sizes using decimal units (powers of 1000). Units range from bytes to petabytes.

```pkl
datasize1 = 5.b
datasize2 = 5.kb
datasize3 = 5.mb
datasize4 = 5.gb
datasize5 = 5.tb
datasize6 = 5.pb
```

--------------------------------

### Stacked Let Expressions

Source: https://pkl-lang.org/main/current/language-reference/index.html

Shows how to stack multiple let expressions to define sequential local variables.

```pkl
birdDiets = 
  let (birds = List("Pigeon", "Barn owl", "Parrot"))
  let (diet = List("Seeds", "Mice", "Berries"))
    birds.zip(diet)
```

--------------------------------

### Indentation: Assignment operator on new line

Source: https://pkl-lang.org/main/current/style-guide/index.html

When an assignee starts after a newline, it should be indented. This ensures clarity for multi-line assignments.

```pkl
foo =
  "foo"

bar =
  new {
    baz = "baz"
    biz = "biz"
  }
```

```pkl
foo =
"foo"

bar =
new {
  baz = "baz"
  biz = "biz"
}
```

--------------------------------

### Set Construction

Source: https://pkl-lang.org/main/current/language-reference/index.html

Shows how to construct Sets in Pkl, including creating empty sets, sets with unique elements, and sets with duplicate elements which are automatically handled.

```pkl
res1 = Set() __**(1)**
res2 = Set(1, 2, 3) __**(2)**
res3 = Set(1, 2, 3, 1) __**(3)**
res4 = Set(1, "x", 5.min, List(1, 2, 3)) __**(4)**
```

--------------------------------

### Reading Environment Variable

Source: https://pkl-lang.org/main/current/language-reference/index.html

The `read` expression is used to access external resources. This example shows how to read an environment variable.

```pkl
path = read("env:PATH")
```

--------------------------------

### Initialize Nullable Property with Default

Source: https://pkl-lang.org/main/current/language-reference/index.html

Demonstrates initializing a nullable property with a default value using `Null()` and amending it later.

```pkl
// we don't have a pet yet, but already know that it is going to be a bird
pet = Null(new Dynamic {
  animal = "bird"
})
```

```pkl
amends "template.pkl"

// We got a pet, let's fill in its name
pet {
  name = "Parry the Parrot"
}
```

```pkl
amends "template.pkl"

// We do not need to name anything if we have no pet yet
pet {}
```

```pkl
pet = null
```

```pkl
pet {
  name = "Parry the Parrot"
}
```

--------------------------------

### Incorrect Class Name Formatting

Source: https://pkl-lang.org/main/current/style-guide/index.html

This example demonstrates an incorrect class name format, using camelCase instead of PascalCase.

```pkl
class zebraParty {}
```

--------------------------------

### Multiline String Equivalent

Source: https://pkl-lang.org/main/current/language-reference/index.html

Shows the single-line string equivalent of the previous multiline string, demonstrating \n normalization.

```pkl
"Although the Dodo is extinct,\nthe species will be remembered."
```

--------------------------------

### Bytes Construction

Source: https://pkl-lang.org/main/current/language-reference/index.html

Shows how to construct Bytes objects in Pkl, including from byte values and as empty sequences.

```pkl
bytes1 = Bytes(0xff, 0x00, 0x3f) __**(1)**
bytes2 = Bytes() __**(2)**
```

--------------------------------

### Object Member Spacing (Good)

Source: https://pkl-lang.org/main/current/style-guide/index.html

Object members should be separated by at most one blank line. This example shows correct spacing.

```pkl
foo = "bar"

baz = "buz"
```

```pkl
foo = "bar"
baz = "buz"
```

--------------------------------

### Define Object with Entries

Source: https://pkl-lang.org/main/current/language-tutorial/01_basic_config.html

Shows how to define objects with entries, which are keyed by arbitrary expressions (not just strings). Any object can be used as a key.

```pkl
pigeonShelter {
  ["bird"] {
    name = "Common wood pigeon"
    diet = "Seeds"
    taxonomy {
      species = "Columba palumbus"
    }
  }
  ["address"] = "355 Bird St."
}

birdCount {
  [pigeonShelter] = 42
}
```

--------------------------------

### Indentation: Nested `if` in `else` branch

Source: https://pkl-lang.org/main/current/style-guide/index.html

A nested `if` within an `else` branch should align with its parent `if` and start on the same line as the `else` keyword.

```pkl
if (bar)
  bar
else if (baz)
  baz
else
  foo
```

```pkl
if (bar)
  bar
else
  if (baz)
    baz
  else
    foo
```

--------------------------------

### Heterogeneous List Creation

Source: https://pkl-lang.org/main/current/language-reference/index.html

Illustrates creating a list containing elements of different types, including a nested list.

```pkl
list3 = List(1, "x", 5.min, List(1, 2, 3))
```

--------------------------------

### Spread Object Entries

Source: https://pkl-lang.org/main/current/language-reference/index.html

Spreads existing entries from one object into another. This example shows spreading entries from 'entries1' into 'entries2'.

```pkl
entries1 {
  ["Pigeon"] = "Piggy the Pigeon"
  ["Barn owl"] = "Barney the Barn owl"
}

entries2 {
  ...entries1 __**(1)**
}

elements1 { 1; 2 }

elements2 {
  ...elements1 __**(2)**
}

properties1 {
  name = "Pigeon"
  diet = "Seeds"
}

properties2 {
  ...properties1 __**(3)**
}
```

--------------------------------

### Conditional Property Generation with 'when'

Source: https://pkl-lang.org/main/current/language-reference/index.html

Conditionally generates object members based on a boolean condition. This example shows property generation.

```pkl
isSinger = true

parrot {
  lifespan = 20
  when (isSinger) {
    hobby = "singing"
    idol = "Frank Sinatra"
  }
}
```

--------------------------------

### Batch Evaluate with Formatted Output to Files

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Evaluate multiple Pkl modules and write their outputs to separate files in JSON format. Placeholders like `%{moduleDir}` and `%{moduleName}` are used to define output file paths.

```shell
pkl eval --format=json --output-path=%{moduleDir}/%{moduleName}.json config1.pkl config2.pkl config3.pkl
```

--------------------------------

### Property Without Default Value

Source: https://pkl-lang.org/main/current/language-reference/index.html

An example of a property that does not have an implicit or explicit default value, which will throw an error if accessed without being overridden.

```pkl
name: String
```

--------------------------------

### Open Module Declaration for Extension

Source: https://pkl-lang.org/main/current/language-reference/index.html

Illustrates declaring a module as 'open' to allow it to be extended by other modules.

```pkl
open module pigeon

name = "Pigeon"
diet = "Seeds"
```

--------------------------------

### Nothing Type Function Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Demonstrates the 'nothing' type, which indicates a function that never returns normally and always throws an error.

```pkl
function TODO(): nothing = throw("TODO")
```

--------------------------------

### List with Elements

Source: https://pkl-lang.org/main/current/language-reference/index.html

Shows creating a list with multiple integer elements.

```pkl
list2 = List(1, 2, 3)
```

--------------------------------

### Evaluate Class with Missing Default Values

Source: https://pkl-lang.org/main/current/language-tutorial/03_writing_a_template.html

Attempts to evaluate 'TutorialPart.pkl' which has properties ('name', 'part') without default values, resulting in an error.

```Shell
$ pkl eval TutorialPart.pkl
–– Pkl Error ––
Tried to read property `name` but its value is undefined.

1 | name: String
    ^^^^
```

--------------------------------

### Quoted Identifier Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Demonstrates how to use a quoted identifier for a name that would otherwise be illegal. Backticks are not part of the identifier's name.

```pkl
`A Bird's First Flight Time` = 5.s
```

```pkl
`number` = 42
res1 = `number`
res2 = number
```

--------------------------------

### Define Class Properties with Default Values

Source: https://pkl-lang.org/main/current/language-tutorial/03_writing_a_template.html

Defines a 'TutorialPart' class with default values for 'hasExercises', 'amountLearned', 'duration', and 'bandwidthRequirementPerSecond'. Properties 'name' and 'part' remain without default values.

```Pkl
name: String

part: Int

hasExercises: Boolean = true

amountLearned: Float = 13.37

duration: Duration = 30.min

bandwidthRequirementPerSecond: DataSize = 52.4288.mb
```

--------------------------------

### Configure Module Cache Directory (Directory)

Source: https://pkl-lang.org/main/current/pkl-gradle/index.html

Specify the directory for caching packages. If null, defaults to '~/.pkl/cache'. This example uses a build directory.

```gradle
moduleCacheDir = layout.buildDirectory.dir("pkl-module-cache")

```

--------------------------------

### Using an External LDAP Resource Reader in Pkl

Source: https://pkl-lang.org/main/current/language-reference/index.html

Demonstrates how to evaluate a Pkl module that uses an external resource reader for the `ldap:` scheme. The external reader must be executable and in the system's PATH.

```pkl
email = read("ldap://ds.example.com:389/dc=example,dc=com?mail?sub?(uid=\(username))").text
```

```bash
$ pkl eval <module> --external-resource-reader ldap=pkl-ldap
username = "pigeon"
email = "pigeon@example.com"
```

--------------------------------

### Define Object with Elements

Source: https://pkl-lang.org/main/current/language-tutorial/01_basic_config.html

Demonstrates creating objects with elements, which are ordered and indexed by integers. Elements can be literal values, expressions, or other objects.

```pkl
exampleObjectWithJustIntElements {
  100
  42
}

exampleObjectWithMixedElements {
  "Bird Breeder Conference"
  (2000 + 23)
  exampleObjectWithJustIntElements
}
```

--------------------------------

### Indentation: `if` and `let` expressions

Source: https://pkl-lang.org/main/current/style-guide/index.html

Bodies of `if` and `let` expressions starting on a new line should be indented. Inline bodies and `else` branches are also permitted.

```pkl
if (bar)
  bar
else
  foo
```

```pkl
if (bar) bar else foo
```

```pkl
let (foo = "bar")
  foo.toUpperCase()
```

```pkl
let (foo = "bar") foo.toUpperCase()
```

```pkl
if (bar)
bar
else
foo
```

```pkl
let (foo = "bar")
foo.toUpperCase()
```

--------------------------------

### Apply Annotations to Module, Class, Property, and Method

Source: https://pkl-lang.org/main/current/language-reference/index.html

Illustrates the application of annotations to a module, class, property, and method, including omitting and overriding annotation properties.

```Pkl
/// Module doc comment
@SomeAnnotation __**(1)**
module myModule

class SomeAnnotation extends Annotation {
  __**(2)**
  description: String = "some annotation"
}

/// Module doc comment
@SomeAnnotation __**(3)**
class Bird {
  @SomeAnnotation { description = "some property" } __**(4)**
  name: String

  @SomeAnnotation { description = "some method" } __**(5)**
  @Unlisted __**(6)**
  function greet(greeting: String): String = "\(greeting), \(name)!"
}
```

--------------------------------

### Testing Pkl Commands and Subcommands

Source: https://pkl-lang.org/main/current/pkl-cli/index.html

Write tests for Pkl commands by amending the `pkl:test` module. Populate command options and parent options to simulate different execution contexts.

```Pkl
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
  }
}
```

--------------------------------

### Configure External Properties

Source: https://pkl-lang.org/main/current/pkl-gradle/index.html

Define external properties that can be read by Pkl code using the 'prop:' scheme. This example shows setting multiple properties.

```gradle
externalProperties = ["myProp1": "myValue1", "myProp2": "myValue2"]

```

--------------------------------

### String Concatenation in Pkl

Source: https://pkl-lang.org/main/current/style-guide/index.html

Avoid using string concatenation with the '+' operator for dynamic string construction. This example demonstrates the less preferred method.

```pkl
greeting = "Hello, " + name
```

--------------------------------

### Message Structure Example

Source: https://pkl-lang.org/main/current/bindings-specification/message-passing-api.html

Illustrates the basic structure of a message passed between client and server, encoded in MessagePack as an array with a type code and a message body.

```json
[
  1,
  { "someKey": "someValue" }
]
```

--------------------------------

### Declare Module Name

Source: https://pkl-lang.org/main/current/language-reference/index.html

Illustrates how to declare a module's qualified name using a module clause at the beginning of the file.

```Pkl
/// My bird module.
module com.animals.Birds
```

--------------------------------

### Set Operations and Equality

Source: https://pkl-lang.org/main/current/language-reference/index.html

Illustrates accessing the first element, converting a set to a listing, and comparing sets for equality in Pkl.

```pkl
res1 = Set(4, 3, 2)
res2 = res1.first __**(1)**
res3 = res1.toListing() __**(2)**
res4 = Set(2, 3, 4) == res1 __**(3)**
```

--------------------------------

### Type Constraint Violation Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Illustrates a violation of the 'name' length type constraint. The 'name' property is set to a two-character string, causing a constraint error.

```pkl
pigeon: Bird = new {
  // fails the constraint because [name] is less than 3 characters
  name = "Pi"
}
```

--------------------------------

### Relative URI Import Example

Source: https://pkl-lang.org/main/current/language-reference/index.html

Relative module URIs are interpreted relative to the URI of the enclosing module. Paths on Windows use the `/` character as the directory separator.

```text
import "parrot.pkl"
```

```text
import "/animals/birds/parrot.pkl"
```

--------------------------------

### Pkl Configuration File

Source: https://pkl-lang.org/main/current/language-tutorial/01_basic_config.html

Defines basic values including strings, integers, booleans, and floating-point numbers.

```pkl
name = "Pkl: Configure your Systems in New Ways"
attendants = 100
isInteractive = true
amountLearned = 13.37

```
Tokens:
Raw