Skip to content

Pkl Cheatsheet

Introduction

For a comprehensive introduction to Pkl, check out our Pkl primer, which covers the fundamentals in just a few minutes.

For more in-depth documentation, see the official Pkl language tutorial.

Syntax Cheat Sheet

Basic Syntax

Comments:

// This is a comment

/* This is a multi-line
   multi-line comment
*/
/// User-facing documentation for a member

Module Declaration:

module MyModule

Importing Modules:

  • Standard library: import "pkl:json"
  • Local module: import "path/to/module.pkl"
  • Package: import "package://pkg.pkl-lang.org/pkl-pantry/[email protected]"
  • Project Package Reference: import @toml/toml.pkl

Variables and Assignments

name = "Dodo" // Immutable by default
local age = 42 // Local scope
var mutableValue = 10 // Mutable (use sparingly)

Objects:

dodo {
  name = "Dodo"
  extinct = true
}
// Access: dodo.name

Amendments:

dodo {
  name = "Dodo"
  extinct = true
}

revived = (dodo) {
  extinct = false
}

Data Types

Numbers:

// Integer
num = 123
hex = 0x1A
binary = 0b1011
octal = 0o755

// Float
float = 1.23
scientific = 1.2e-3

// Readable
large = 1_000_000.50

Booleans:

isActive = true
isFalse = false

Strings:

text = "Hello, Pkl!"
unicode = "\u{1F426}" // 🐦
multiline = """
Line 1
Line 2
"""

Durations:

time = 5.min
delay = 300.ms

Data Sizes:

size = 5.mb
large = 1.gb

Null:

nothing = null

Collections:

// List 
numbers = [1, 2, 3]

// Listing (lazy evaluated)
foods = new Listing<String> {
  "bacon"
  "nachos"
}

// Set
unique = new Set { 
  1
  2
  3 
}

// Mapping
pairs = new Mapping { 
  ["key1"] = "value1"
  ["key2"] = "value2" 
}

Classes and Objects

Class Definition:

class Bird {
  name: String
  extinct: Boolean
}

Instantiation:

dodo = new Bird { name = "Dodo"; extinct = true }

Type Constraints:

age: Int(isBetween(0, 130))
oddName: String(length.isOdd, chars.first == chars.last)

Operators

  • Arithmetic: +, -, *, /, ~/ (integer division), %, ** (power) 

    sum = 5 + 3
power = 2 ** 3

  • Comparison: ==, !=, <, <=, >, >= 

    isEqual = 5.mb == 3.kib

  • Logical: &&, ||, !, .xor, .implies 

    result = true && false

  • Null Coalescing: ?? 

    value = maybeNull ?? "default"

Control Flow

If Expression:

status = if (age > 18) "Adult" else "Minor"

For Generators:

// Generate over a list
names = List("Pigeon", "Barn owl", "Parrot")

birds {
  for (_name in names) {
    new {
      name = _name
      lifespan = 42
    }
  }
}

// Generate over a map
namesAndLifespans = Map("Pigeon", 8, "Barn owl", 15, "Parrot", 20)

birdsByName {
  for (_name, _lifespan in namesAndLifespans) {
    [_name] {
      name = _name
      lifespan = _lifespan
    }
  }
}

When Generators:

needNfs = true
class Server {
  type: String
  name: String
}


servers {
  when (needNfs) {
    new Server {
      type = "NFS"
      name = "nfs-server"
    }
  }
  new Server {
    type = "WWW"
    name = "www-server"
  }
  new Server {
    type = "App"
    name = "app-server"
  }
}

Let Expression:


result = let (x = 5) x * 2

Functions and Methods

Function Definition:

function double(x: Int): Int = x * 2

Method in Class:

class Bird {
    function describe() = "\(name) is \(extinct ? "extinct" : "alive")"
}

Calling Functions and Methods:

doubled = double(5) // 10
desc = dodo.describe()

Standard Library Modules

The standard library is imported with import "pkl:<module>". Key modules include: - pkl:base: - Fundamental types: Int, Float, String, Boolean, Collection - Properties: isFinite, length, isEmpty - Example: import "pkl:base" (auto-imported, no need to import explicitly)

  • pkl:json:

    • Parse JSON: json.parse("{\"key\": \"value\"}")
    • Render JSON: json.render(myObject)

  • pkl:math:

    • Constants: math.pi, math.e
    • Functions: math.sqrt(16), math.abs(-5)

  • pkl:platform:

    • Info: platform.os, platform.arch

  • pkl:toml (from pantry):

Other Notable Modules:

  • pkl:reflect: Reflection utilities
  • pkl:protobuf: Experimental Protocol Buffers renderer
  • pkl:yaml: YAML parsing/rendering

Error Handling and Validation

Throw:

throw("Invalid input")

Constraints:

age: Int(isPositive) // Throws if negative