DOCSEARCHbyAlgolia
Submit Docs

Pkl Configuration-as-Code Language

repository·main·Indexed 11 days ago

https://github.com/apple/pkl

A configuration-as-code language developed by Apple providing rich validation and tooling for complex configurations. Includes libpkl, a native C library for integrating Pkl functionality into native environments via a MessagePack-based message passing API, and a lossless binary serialization format called pkl-binary.

Tokens
49.6K
Snippets
164
Records
254
Agent score
92%

What's inside Pkl

  2. Overview of Pkl configuration language

    main

    Pkl (pronounced Pickle) is an embeddable configuration language designed for rich data templating and validation. It is designed to scale from simple, ad-hoc configuration tasks to complex, repetitive ones.

    Developers can use Pkl in three primary ways:

    1. Command Line: Using the Pkl CLI for direct interaction.
    2. Build Pipelines: Integrating Pkl into automated workflows.
    3. Embedded: Integrating Pkl directly into a program via language bindings.

  3. Overview of Pkldoc

    main

    Pkldoc is a documentation website generator designed to produce navigable and searchable API documentation for Pkl modules. Its design and user experience are inspired by Scaladoc.

    Key Features

    • Code Navigation: Hyperlinked modules, classes, functions, and properties.
    • Member Search: Search the entire documentation by member name (supports prefixing for specific types).
    • Comment Folding: Expand/collapse multi-paragraph doc comments.
    • Markdown Support: Write doc comments using Markdown.
    • Member Links & Anchors: Link to other members and obtain deep links via anchor symbols.
    • Cross-site Links: Enable linking between different Pkldoc websites (e.g., linking your module docs to the Pkl Standard Library docs).

  4. Overview of Pkl Core

    main

    Pkl Core is the central implementation of the Pkl language. It provides the necessary infrastructure to use Pkl within the JVM ecosystem. Developers can use it to:

    • Embed Pkl directly into JVM-based applications to leverage its configuration capabilities.
    • Build libraries and tools that extend or interact with the Pkl language.

    It serves as the foundational layer for any JVM-based integration of the Pkl language.

  5. Overview of Pkl

    main
    Pkl is a configuration-as-code language designed with rich validation and tooling. It is intended to provide a more robust and programmable alternative to static configuration formats, allowing developers to define complex configurations with built-in validation logic.

  6. Use the Pkl CLI tools

    main

    The Pkl Command-line interface (CLI) provides two primary tools for interacting with Pkl files:

    1. Batch evaluator: Used for evaluating Pkl files in a non-interactive mode, typically for automation, CI/CD, or single-shot evaluations.
    2. REPL (Read-Evalled Print Loop): An interactive environment for exploring Pkl code, testing expressions, and inspecting values in real-time.

  7. Integrate Pkl with Java

    main

    Pkl offers two primary ways to integrate with Java applications:

    1. Embed the Pkl runtime: You can include the Pkl runtime directly within your Java program to evaluate Pkl code and interact with Pkl data structures at runtime.
    2. Code Generation: You can generate Java source code from Pkl source files, allowing you to work with Pkl-defined schemas as type-safe Java objects.

  9. Integrate Pkl with Kotlin

    main

    Pkl offers two primary ways to integrate with Kotlin applications:

    1. Runtime Embedding: You can embed the Pkl runtime directly into your Kotlin application to evaluate Pkl code and access configuration values at runtime.
    2. Code Generation: You can generate type-safe Kotlin code directly from your Pkl source files, allowing you to interact with Pkl configurations using native Kotlin classes and properties.

  10. Amend vs. Extend a Module

    main

    Pkl provides two ways to build upon existing modules: amends and extends.

    Amending a Module (amends)

    Used to fill in template modules. An amending module has the same type as the module it amends.

    • Constraint: It cannot define new properties, methods, or classes unless they are local.
    • Syntax: amends "module.pkl".
    • Use Case: You have a template defining structure/validation, and you want to provide specific values.

    Extending a Module (extends)

    Used to create a new module that inherits from an open module.

    • Constraint: The target module must be declared as open.
    • Capability: It can define new properties, methods, and classes.
    • Syntax: extends "module.pkl".
    • Use Case: Creating a specialized version of a module with additional functionality.
    // Amending (Template pattern)
// parrot.pkl
amends "pigeon.pkl"
name = "Parrot"

// Extending (Inheritance pattern)
// parrot.pkl
open module pigeon
name = "Pigeon"

// parrot.pkl
extends "pigeon.pkl"
name = "Parrot"
function say() = "Hello"

  11. Use basic types in Pkl

    main

    Pkl provides several basic types for unstructured values. When defining properties, you can explicitly annotate them with type signatures. Common types include:

    • String: For text values.
    • Int: For integers.
    • Boolean: For true/false values.
    • Float: For floating-point numbers.
    • Duration: For time durations (e.g., 30.min).
    • DataSize: For data sizes (e.g., 52.4288.mb).

    Note that when running pkl eval, the output format is pcf (a subset of Pkl) which does not include these type signatures in the rendered output.

    name: String = "Writing a Template"
part: Int = 3
hasExercises: Boolean = true
amountLearned: Float = 13.37
duration: Duration = 30.min
bandwidthRequirementPerSecond: DataSize = 52.4288.mb

  12. Understand the Pkl evaluation lifecycle

    main

    Pkl code is organized into modules (files). The process of running Pkl code is called evaluation.

    1. Evaluation: The evaluator processes a module to produce an in-memory data model (similar to a JSON data model).
    2. Success: If evaluation succeeds, the evaluator converts the data model into an external representation (rendering) and exits with status code 0.
    3. Failure: If evaluation fails, the evaluator prints an error message and exits with a non-zero status code.

    Key properties of the evaluation process include:

    • Immutability: All Pkl data is immutable. Operations on values always return a new value rather than modifying the original.
    • Isolation: Evaluation is strictly sandboxed. Pkl code cannot interact with the outside world except through well-defined exceptions, preventing malicious or buggy code from accessing the host system.