mirror of
https://github.com/apple/pkl.git
synced 2026-03-17 23:03:54 +01:00
98 lines
4.5 KiB
Plaintext
98 lines
4.5 KiB
Plaintext
= Concepts
|
|
include::ROOT:partial$component-attributes.adoc[]
|
|
:uri-property-list: https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/PropertyLists/UnderstandXMLPlist/UnderstandXMLPlist.html
|
|
|
|
Let's get to know Pkl by discussing some of its concepts and features.
|
|
|
|
[[abstraction]]
|
|
== Abstraction
|
|
|
|
Configuration tends to grow larger and more complex over time, making it increasingly difficult to understand and maintain.
|
|
Pkl can reduce the size and complexity of configuration by
|
|
|
|
* describing similar configuration elements in terms of their differences
|
|
* introducing abstractions for common configuration elements
|
|
* separating configuration structure from configuration data
|
|
* computing instead of enumerating configuration
|
|
|
|
[[evaluation]]
|
|
== Evaluation
|
|
|
|
Pkl code lives in _modules_, a more fancy and general term for _files_.
|
|
Evaluating a module produces an in-memory _data model_ that is roughly comparable to a JSON data model.
|
|
If evaluation completes successfully, the Pkl evaluator converts the data model to an external representation and terminates with the status code zero.
|
|
Otherwise, the evaluator prints an error message and terminates with a non-zero status code.
|
|
|
|
[[immutability]]
|
|
== Immutability
|
|
|
|
All Pkl data is immutable.
|
|
Manipulating a value always returns a new value, leaving the original value unchanged.
|
|
Immutability eliminates many potential sources of errors.
|
|
|
|
[[isolation]]
|
|
== Isolation
|
|
|
|
Evaluation of Pkl code is strictly sandboxed.
|
|
Except for a few well-defined and well-controlled exceptions, Pkl code cannot interact with the outside world.
|
|
Leaving aside bugs in the language implementation, the worst thing that buggy or malicious Pkl code can do is to consume CPU and memory resources until the evaluator gets killed.
|
|
Over time, sandboxing will be further strengthened to cover fine-grained CPU and memory boxing.
|
|
|
|
[[rendering]]
|
|
== Rendering
|
|
|
|
Converting a data model to an external representation is called _rendering_ the model.
|
|
Pkl ships with renderers for the following data formats:
|
|
|
|
* JSON
|
|
* Jsonnet
|
|
* Pcf (a static subset of Pkl)
|
|
* (Java) Properties
|
|
* {uri-property-list}[Property List]
|
|
* XML
|
|
* YAML
|
|
|
|
Support for other formats can be added by writing a custom renderer in Pkl or Java.
|
|
See xref:language-reference:index.adoc#module-output[Module Output] and xref:pkl-core:index.adoc#value-visitor[Value Visitor] for more information.
|
|
|
|
[[resemblance]]
|
|
== Resemblance
|
|
|
|
By design, Pkl code tends to structurally and visually resemble the configuration it generates.
|
|
This makes the code easier to read and write.
|
|
|
|
[[reuse]]
|
|
== Reuse
|
|
|
|
Modules can reuse other modules by xref:language-reference:index.adoc#import-module[importing] them from local or remote locations.
|
|
Imports can also be used to split up one large module into multiple smaller ones, increasing maintainability.
|
|
A configurable security policy helps to keep imports under control.
|
|
|
|
[[schema]]
|
|
== Schema
|
|
|
|
Configuration is structured data.
|
|
Pkl supports -- but does not require -- to express this structure as a _configuration schema_, a set of classes defining configuration properties, their defaults, types, and constraints.
|
|
Writing and maintaining a configuration schema takes some effort but, in return, provides these benefits:
|
|
|
|
* Independent evolution of configuration schema and configuration data, often by different teams (for example service providers and service consumers).
|
|
* Automatic xref:pkl-doc:index.adoc[documentation generation].
|
|
* Strong validation of configuration, both during development time and runtime.
|
|
* Statically typed access to configuration from xref:java-binding:codegen.adoc[Java] and other languages through code generation.
|
|
* Schema-aware development tools, for example REPLs and editors with code completion support.
|
|
|
|
[[template]]
|
|
== Templating
|
|
|
|
Pkl supports writing templates for objects and entire modules.
|
|
Templates can be repeatedly turned into concrete configuration by filling in the blanks, and -- when necessary -- overriding defaults.
|
|
Sharing template modules over the network can streamline complex configuration tasks for entire teams, organizations, and communities.
|
|
|
|
[[usability]]
|
|
== Usability
|
|
|
|
Everybody needs a configuration solution, but nobody wants to spend a lot of time learning it.
|
|
To reflect this reality, Pkl has a strong focus on usability.
|
|
For example, error messages explain causes and possible solutions and object properties maintain definition order to avoid surprises.
|
|
We hope that this focus on usability will make Pkl accessible to a wide audience of occasional users, while still leaving room for expert users and advanced use cases.
|