### Map API Examples

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Illustrates common Map API methods like checking for key/value containment, checking if empty, getting length, and retrieving a value with a default.

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

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

### Install Pkl using Winget on Windows

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

Installs the Pkl executable using the Windows Package Manager.

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

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

### Example Method

Source: https://github.com/apple/pkl/blob/main/pkl-doc/src/test/files/DocMigratorTest/output/com.package1/1.2.3/unlistedProperty/index.html

An example method that returns an unknown type. Its specific functionality is not detailed here.

```pkl
function myMethod(): unknown
```

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

### Example Configuration for a Workshop

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-tutorial/pages/03_writing_a_template.adoc

An example of a Pkl configuration file defining various properties for a workshop, including nested objects and lists.

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

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

### Install Pkl with Homebrew

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

Installs the Pkl CLI using Homebrew on macOS and Linux. Ensure Homebrew is installed first.

```shell
brew install pkl
```

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

### String API Examples

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

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

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

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

### Download and install Pkl executable on Windows

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

Downloads the Pkl executable for Windows and verifies the installation.

```PowerShell
Invoke-WebRequest '{uri-pkl-windows-download}' -OutFile pkl.exe
.\pkl --version
```

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

### Download and install Java executable for Pkl on Windows

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

Downloads the Java executable for Pkl and verifies the installation.

```PowerShell
Invoke-WebRequest '{uri-pkl-java-download}' -OutFile jpkl.bat
.\jpkl --version
```

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

### Download and install Pkl executable on Linux (amd64)

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

Downloads the Pkl executable for Linux amd64, makes it executable, and verifies the installation.

```shell
curl -L -o pkl '{uri-pkl-linux-amd64-download}'
chmod +x pkl
./pkl --version
```

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

### Pkl Settings File Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

An example of a Pkl settings file, which amends the 'pkl:settings' standard library module to customize the CLI experience, such as setting the default editor.

```pkl
amends "pkl:settings" // <1>

editor = Idea // <2>
```

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

### Pkl Module Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/bindings-specification/pages/index.adoc

This is an example of a Pkl module that imports all .pkl files from a custom file system.

```pkl
module MyModule

theModules = import*("customfs:/*.pkl")
```

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

### Importing Modules

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Demonstrates importing specific .pkl files. This is a basic example of module loading.

```pkl
["birds/pigeon.pkl"] = import("birds/pigeon.pkl")
["birds/parrot.pkl"] = import("birds/parrot.pkl")
["birds/falcon.pkl"] = import("birds/falcon.pkl")
```

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

### Download and install Java executable for Pkl on macOS/Linux

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

Downloads the Java executable for Pkl, makes it executable, and verifies the installation.

```shell
curl -L -o jpkl '{uri-pkl-java-download}'
chmod +x jpkl
./jpkl --version
```

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

### Property with summary and code example

Source: https://github.com/apple/pkl/blob/main/pkl-doc/src/test/files/DocGeneratorTest/output/run-1/com.package1/1.2.3/modulePropertyCommentInheritance/index.html

Defines an integer property with a summary and a code example for its calculation.

```pkl
property8: [Int](https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Int.html) ([com.package1.modulePropertyComments](../modulePropertyComments/index.html))

    Summary

        
        code = 4 * 10
        
    
    Rest of the body
```

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

### Download and install Pkl executable on Linux (aarch64)

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

Downloads the Pkl executable for Linux aarch64, makes it executable, and verifies the installation.

```shell
curl -L -o pkl '{uri-pkl-linux-aarch64-download}'
chmod +x pkl
./pkl --version
```

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

### Install Pkl with Mise

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

Installs and activates the Pkl CLI globally using Mise on macOS, Linux, and Windows. Replace `{pkl-version}` with the desired Pkl version.

```shell
# Install and activate Pkl globally
 mise use -g pkl@{pkl-version}
```

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

### Example Module and Class Definition

Source: https://github.com/apple/pkl/blob/main/pkl-doc/src/test/files/DocGeneratorTest/output/run-1/com.package1/1.2.3/classComments/Comments8.html

This snippet defines a module, a data structure, a function, and a class. It serves as a general example of Pkl syntax.

```pkl
/// example module
module foo.bar

person {
  name = "Pigeon"
  age = 42
}

function sing() = "tra-la-la"

class Person {
  name: String
  age: Int
}
```

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

### Module Property with Code in Doc Comment (Example 1)

Source: https://github.com/apple/pkl/blob/main/pkl-doc/src/test/files/DocMigratorTest/input/version-1/com.package1/1.2.3/modulePropertyComments/index.html

Demonstrates a module property where the documentation comment includes a code example, separated into summary and body.

```pkl
property8: Int
    """
    Summary
    
        
        code = 4 * 10
        
    
    Rest of the body
    """
```

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

### Download and install Pkl executable on Alpine Linux

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

Downloads the Pkl executable for Alpine Linux, makes it executable, and verifies the installation.

```shell
curl -L -o pkl '{uri-pkl-alpine-download}'
chmod +x pkl
./pkl --version
```

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

### Comprehensive Doc Comment Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

A detailed example of a doc comment for a module, demonstrating Markdown formatting and best practices for documentation.

```pkl
/// An aviated animal going by the name of [bird](https://en.wikipedia.org/wiki/Bird).
///

```

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

### Standard Library URI Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Example of a URI for importing a standard library module. Standard library modules are named `pkl.<simpleName>` and have URIs of the form `pkl:<simpleName>`.

```plaintext
pkl:math
```

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

### Trace Output Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

This is an example of the output generated by a `trace` expression in Pkl, showing the evaluated expression, its result, and its location.

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

```

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

### Download and install Pkl executable on macOS (amd64)

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

Downloads the Pkl executable for macOS amd64, makes it executable, and verifies the installation.

```shell
curl -L -o pkl '{uri-pkl-macos-amd64-download}'
chmod +x pkl
./pkl --version
```

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

### Start Pkl REPL Session

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

Starts an interactive Read-Eval-Print Loop (REPL) session for Pkl. The REPL allows for interactive code evaluation and module loading.

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

pkl>
```

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

### Import Graph Analysis

Source: https://github.com/apple/pkl/blob/main/docs/modules/release-notes/pages/0.27.adoc

Example of how to import a graph for analysis. Requires the `analyze` module.

```pkl
importGraph: analyze.ImportGraph = analyze.importGraph(Set("file:///path/to/my/module.pkl"))
```

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

### Module Property with Code in Doc Comment (Example 2)

Source: https://github.com/apple/pkl/blob/main/pkl-doc/src/test/files/DocMigratorTest/input/version-1/com.package1/1.2.3/modulePropertyComments/index.html

Shows a module property with a documentation comment containing a code example, including a summary and a 'Rest' section.

```pkl
property9: Int
    """
    Summary
    
        
        code = 0
        
    
    Rest
    """
```

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

### File URI Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Represents a module located on the local file system.

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

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

### Module Path URI Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Resolves modules relative to a specified module path, similar to Java's class path. The example shows how a module path is searched.

```plaintext
modulepath:/path/to/my_module.pkl
```

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

### Install Fish Shell Completion for Pkl CLI

Source: https://github.com/apple/pkl/blob/main/docs/modules/release-notes/pages/0.29.adoc

Installs shell completions for the Pkl CLI in the fish shell by redirecting the output of the `shell-completion` subcommand to the appropriate fish configuration directory.

```shellscript
pkl shell-completion fish > "~/.config/fish/completions/pkl.fish"
```

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

### Indented if/let Expressions

Source: https://github.com/apple/pkl/blob/main/docs/modules/style-guide/pages/index.adoc

The bodies of `if` and `let` expressions should be indented if they start on their own line. This example shows a standard `if-else` structure.

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

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

### Running a Pkl CLI Tool

Source: https://github.com/apple/pkl/blob/main/docs/modules/release-notes/pages/0.31.adoc

Demonstrates how to execute a Pkl CLI tool using the 'pkl run' command, passing arguments and options.

```bash
$ pkl run bird-generator.pkl pigeon --aggregate=mean Pigeon=1 Hawk=8 Eagle=3
birds {
  new {
    name = "Pigeon"
    age = 1
  }
  new {
    name = "Hawk"
    age = 8
  }
  new {
    name = "Eagle"
    age = 3
  }
}
result = 4.0
```

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

### Verify Kotlin CodeGen CLI Version

Source: https://github.com/apple/pkl/blob/main/docs/modules/kotlin-binding/pages/codegen.adoc

This output shows an example of the version information printed by the Kotlin code generator CLI after successful installation.

```shell
pkl-codegen-kotlin {pkl-version} (macOS 14.2, Java 17.0.10)
```

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

### HTTP(S) URI Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Represents a module imported via an HTTP(S) GET request. Modules loaded this way are cached only until the Pkl command exits or the Evaluator is closed.

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

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

### Pkl Amending Objects

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-tutorial/pages/03_writing_a_template.adoc

Defines a 'TutorialPart' class and then creates multiple instances by amending a base instance. This is useful for configurations with similar structures but different values.

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


```

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

### Doc Comments with Summary and Details

Source: https://github.com/apple/pkl/blob/main/docs/modules/style-guide/pages/index.adoc

Use doc comments starting with a one-sentence summary, followed by additional paragraphs for details. Each new sentence should begin on its own line. This example shows how to document a duration property with notes and a link.

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

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

### Windows File URI Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Illustrates how to correctly import a module from a Windows file path using an absolute file URI. Relative paths use '/' as a separator on all platforms.

```pkl
import "file:///C:/path/to/my/module.pkl"
```

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

### Property with code example

Source: https://github.com/apple/pkl/blob/main/pkl-doc/src/test/files/DocGeneratorTest/output/run-1/com.package1/1.2.3/modulePropertyCommentInheritance/index.html

Defines an integer property with a code example for its calculation.

```pkl
property10: [Int](https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Int.html) ([com.package1.modulePropertyComments](../modulePropertyComments/index.html))

        
        code = 2
        
    
    Rest
```

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

### Set API Examples

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Illustrates common Set operations such as checking for containment, slicing, mapping elements, and finding intersections.

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

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

### Module Header Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/style-guide/pages/index.adoc

Demonstrates the structure of a Pkl module header, including module, extends, and import clauses. Ensure clauses are separated by blank lines.

```pkl
module com.example.Foo // <1>

extends "Bar.pkl" // <2>

import "baz.pkl" // <3>
import "Buz.pkl" // <3>
```

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

### Configure HTTP Rewrites for Package Mirroring

Source: https://github.com/apple/pkl/blob/main/docs/modules/release-notes/pages/0.29.adoc

Provides an example of configuring HTTP rewrite rules in `~/.pkl/settings.pkl` to use package mirrors for external dependencies.

```pkl
http {
  rewrite {
    "https://pkg.pkl-lang.org" = "https://my.internal.mirror/pkg-pkl-lang"
    "https://github.com" = "https://my.internal.mirror/github"
  }
}
```

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

### Globbed Import Example (Mapping Initialization)

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Illustrates the equivalent of a globbed import expression by manually initializing a Mapping with imported modules.

```pkl
birds = new Mapping {
  pigeon = import("birds/pigeon.pkl")
  parrot = import("birds/parrot.pkl")
  falcon = import("birds/falcon.pkl")
}
```

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

### Property with summary and zero code example

Source: https://github.com/apple/pkl/blob/main/pkl-doc/src/test/files/DocGeneratorTest/output/run-1/com.package1/1.2.3/modulePropertyCommentInheritance/index.html

Defines an integer property with a summary and a code example resulting in zero.

```pkl
property9: [Int](https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Int.html) ([com.package1.modulePropertyComments](../modulePropertyComments/index.html))

    Summary

        
        code = 0
        
    
    Rest
```

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

### Pkl Code Formatting Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/style-guide/pages/index.adoc

Demonstrates basic Pkl code structure and formatting, including line continuations for expressions and assignments.

```pkl
foo = bar |>
  baz |>
  biz

myNum = 1 +
  2 +
  3 +
  4
```

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

### Complete Workshop Template Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-tutorial/pages/03_writing_a_template.adoc

A comprehensive Pkl template defining various properties, custom classes, and imported modules for a workshop.

```pkl
module Workshop

import "TutorialPart.pkl"

title: String

interactive: Boolean

seats: Int

occupancy: Float

duration: Duration

`abstract`: String

class Event {
  name: String

  year: Int
}

event: Event

instructors: Listing<String>

class Session {
  time: Duration

  date: String
}

sessions: Listing<Session>

assistants: Mapping<String, String>

agenda: Mapping<String, TutorialPart>
```

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

### Property with code in doc comment (example 2)

Source: https://github.com/apple/pkl/blob/main/pkl-doc/src/test/files/DocGeneratorTest/output/run-1/com.package1/1.2.3/modulePropertyComments/index.html

Presents a property with a documentation comment containing a simple code example.

```pkl
property9: [Int](https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Int.html)[Source](https://example.com/package1/modulePropertyComments.pkl#L123-L456)

Summary

        
        code = 0
        
    
    Rest
```

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

### Evaluating Pkl Modules

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Demonstrates how to evaluate Pkl modules using the `pkl eval` command with different URI schemes like file, http, module-path, and built-in modules.

```shell
$ pkl eval path/to/mymodule.pkl
$ pkl eval file:///path/to/my_module.pkl
$ pkl eval https://apple.com/path/to/mymodule.pkl
$ pkl eval --module-path=/pkl-modules modulepath:/path/to/my_module.pkl
$ pkl eval pkl:math
```

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

### Property with code in doc comment (example 1)

Source: https://github.com/apple/pkl/blob/main/pkl-doc/src/test/files/DocGeneratorTest/output/run-1/com.package1/1.2.3/modulePropertyComments/index.html

Shows a property with a documentation comment that includes a code example for calculation.

```pkl
property8: [Int](https://pages.github.com/apple/pkl/stdlib/pkl/0.24.0/base/Int.html)[Source](https://example.com/package1/modulePropertyComments.pkl#L123-L456)

Summary

        
        code = 4 * 10
        
    
    Rest of the body
```

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

### Implicitly Typed New Instantiation Examples

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Illustrates various scenarios of implicitly typed 'new' invocations, including assignments to typed and untyped properties, Listing elements, and Mapping entries.

```pkl
class Bird {
  name: String

  function listHatchlings(items: Listing<String>): Listing<String> = new {
    for (item in items) {
      "\(name):\(item)"
    }
  }
}

typedProperty: Bird = new { // <1>
  name = "Swift"
}

untypedProperty = new { // <2>
  hello = "world"
}

typedListing: Listing<Bird> = new {
  new { // <3>
    name = "Kite"
  }
}

untypedListing: Listing = new {
  new { // <4>
    hello = "there"
  }
}

typedMapping: Mapping<String, Bird> = new {
  default { entryKey ->
    name = entryKey
  }
  ["Saltmarsh Sparrow"] = new { // <5>
    name = "Sharp-tailed Sparrow"
  }
}

amendedMapping = (typedMapping) {
  ["Saltmarsh Sparrow"] = new {} // <6>
}

class Aviary {
  birds: Listing<Bird> = new {
    new Bird { name = "Osprey" }
  }
}

aviary: Aviary = new {
  birds = new { // <7>
    new Bird { name = "Kiwi" }
  }
}

swiftHatchlings = typedProperty.listHatchlings(new { "Poppy"; "Chirpy" }) // <8>

```

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

### Download and install Pkl executable on macOS (aarch64)

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-cli/pages/index.adoc

Downloads the Pkl executable for macOS aarch64, makes it executable, and verifies the installation.

```shell
curl -L -o pkl '{uri-pkl-macos-aarch64-download}'
chmod +x pkl
./pkl --version
```

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

### Configure External Readers via Command Line

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Demonstrates how to configure external readers for resources and modules using command-line flags. Multiple flags can be passed for different schemes.

```text
$ pkl eval <module> --external-resource-reader <scheme>=<executable> --external-module-reader <scheme>='<executable> <argument> <argument>'
```

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

### Pkl Test Fact Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/release-notes/pages/0.31.adoc

A Pkl code example defining test facts for arithmetic functions, which will benefit from power assertions upon failure.

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

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

### Pkl Typechecking Example (Pre-0.27 Behavior)

Source: https://github.com/apple/pkl/blob/main/docs/modules/release-notes/pages/0.27.adoc

Demonstrates how Pkl evaluated listing elements and mapping values eagerly in versions prior to 0.27, potentially leading to errors even if unused.

```pkl
class Bird {
  name: String
  canFly: Boolean
}

local bird: Bird = new {
  name = "Pidgy"
  canFly = throw("uh oh")
}

birdName = bird.name

```

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

### Enable Pretty Traces in Pkl CLI

Source: https://github.com/apple/pkl/blob/main/docs/modules/release-notes/pages/0.30.adoc

Shows how to use the `--trace-mode pretty` flag with the Pkl CLI to enable multiline, unlimited-size traces for debugging.

```shell
pkl eval --trace-mode pretty myModule.pkl  
```

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

### Module Doc Comment Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

An example of a module-level documentation comment written in Markdown. Doc comments are used for user-facing documentation and are processed by tools like Pkldoc.

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

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

### Defining Class and Module Methods

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Illustrates defining both instance methods within a class and standalone methods within a module. It shows how methods can access properties and how they are dispatched.

```pkl
class Bird {
  name: String
  function greet(bird: Bird): String = "Hello, \(bird.name)!" // <1>
}

function greetPigeon(bird: Bird): String = bird.greet(pigeon) // <2>

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

greeting1 = pigeon.greet(parrot) // <3>
greeting2 = greetPigeon(parrot)  // <4>
```

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

### Example Binary Data Structure

Source: https://github.com/apple/pkl/blob/main/docs/modules/bindings-specification/pages/message-passing-api.adoc

An example of a binary data structure, likely representing a message payload. It includes a request ID and lists of allowed modules and resources.

```json5
[
  0x20,
  {
    "requestId": 193501,
    "allowedModules": ["pkl:", "repl:"],
    "allowedResources": ["file:", "package:", "projectpackage:"]
  }
]
```

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

### Using the pkl:analyze Module for Import Graphs

Source: https://github.com/apple/pkl/blob/main/docs/modules/release-notes/pages/0.27.adoc

Demonstrates how to import and use the new `pkl:analyze` module to compute the total import graph of input modules.

```pkl
import "pkl:analyze"

```

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

### External Reader Example (Custom Scheme)

Source: https://github.com/apple/pkl/blob/main/docs/modules/release-notes/pages/0.27.adoc

Demonstrates how Pkl 0.27 allows custom schemes like 'secret:' to be read by external processes, extending Pkl's I/O capabilities for CLI users.

```pkl
result = read("secret:mypassword") // <1>

```

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

### Base Method Example

Source: https://github.com/apple/pkl/blob/main/pkl-doc/src/test/files/DocGeneratorTest/output/run-1/com.package1/1.2.3/baseModule/index.html

A basic method defined within the base module. No specific usage notes are provided beyond its existence.

```pkl
baseMethod(): unknown
```

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

### Constructing a List with Elements

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Create a list with predefined elements using the `List()` constructor, passing the elements as arguments. Elements can be of different types.

```pkl
list2 = List(1, 2, 3) // <2>
list3 = List(1, "x", 5.min, List(1, 2, 3)) // <3>
----
```

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

### Map Construction

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Shows how to construct maps, including an empty map, a map with key-value pairs, and a map with nested structures.

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

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

### Configuring Output with Data Size Conversion

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Demonstrates configuring a YamlRenderer with a value converter to handle DataSize types, showing how to render memory and disk quotas.

```pkl
quota {
  memory = 100.mb
  disk = 20.gb
}

output {

```

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

### Single-line Comment

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Use `//` to start a single-line comment that extends to the end of the line.

```pkl
// Single-line comment
```

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

### Indented let Expression Body

Source: https://github.com/apple/pkl/blob/main/docs/modules/style-guide/pages/index.adoc

The body of a `let` expression should be indented if it starts on its own line.

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

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

### Configure External Resource Reader

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Example of configuring an external resource reader for the 'ldap' scheme using a hypothetical 'pkl-ldap' executable.

```text
$ pkl eval <module> --external-resource-reader ldap=pkl-ldap
```

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

### Define an Annotation class

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Annotation classes extend `Annotation`. This example defines the `SomeAnnotation` class.

```pkl
class SomeAnnotation extends Annotation {
  description: String = "some annotation"
}
```

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

### Evaluate Pkl Module in Java

Source: https://github.com/apple/pkl/blob/main/docs/modules/pkl-core/pages/index.adoc

This example demonstrates how to build an Evaluator, evaluate a Pkl module from text, and access properties of the evaluated module. The Evaluator should be closed after use, typically with a try-with-resources statement.

```java
import org.pkl.core.Evaluator;
import org.pkl.core.ModuleSource;
import org.pkl.core.PObject;
import org.pkl.core.PklException;

import java.util.List;

public class CoreEvaluatorExample {

    public static void main(String[] args) {
        // <1> Build an Evaluator with default configuration.
        // The evaluator should be closed once it is no longer needed.
        // In this example, this is done with a try-with-resources statement.
        // Note that objects returned by the evaluator remain valid after calling close().
        try (Evaluator evaluator = Evaluator.preconfigured()) {
            // <2> Build a ModuleSource using the given text as the module's contents.
            // Evaluate the given module source. Alternatively, it's possible to build a ModuleSource
            // from a file, path, uri, and other sources.
            var module = evaluator.evaluate(ModuleSource.text("pigeon { diet = ["seeds", "insects"] } pigeon.name = \"Pipsy\""));

            // <3> Get the module's "pigeon" property, which is represented as PObject in Java.
            var pigeon = module.getProperty("pigeon");
            if (pigeon instanceof PObject) {
                // <4> Get the class name for this object. In this example, the class name is pkl.base#Dynamic.
                System.out.println(pigeon.getDynamicClass().getName());

                // <5> Get pigeon's "diet" property, which is represented as List<String> in Java.
                var diet = ((PObject) pigeon).getProperty("diet");
                if (diet instanceof List<?>) {
                    System.out.println(diet);
                }
            }
        } catch (PklException e) {
            // Handle evaluation errors
            e.printStackTrace();
        }
    }
}
```

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

### Character Class Example

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Demonstrates the syntax and usage of character classes within glob patterns.

```text
[abc]
means "a single character that is a, b, or c".
```

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

### Glob Pattern Wildcard `?`

Source: https://github.com/apple/pkl/blob/main/docs/modules/language-reference/pages/index.adoc

Example illustrating the `?` wildcard in glob patterns, which matches a single character.

```text
?
Match a single character.
```