starred/pkl
1
0
Fork 0
mirror of https://github.com/apple/pkl.git synced 2026-04-25 17:58:50 +02:00
Code Issues 198 Packages Projects Releases 10 Wiki Activity

Polish documentation for pkl-binary (#1250)

Browse Source
This commit is contained in:
Daniel Chao
2025-10-26 21:23:57 -07:00
committed by GitHub
parent fdb2bd8c75
commit 1a25e044ac
3 changed files with 29 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/modules/ROOT/partials/component-attributes.adoc
View File

@@ -75,6 +75,7 @@ endif::[]
:uri-stdlib-xmlModule: {uri-pkl-stdlib-docs}/xml
:uri-stdlib-protobufModule: {uri-pkl-stdlib-docs}/protobuf
:uri-stdlib-evaluatorSettingsModule: {uri-pkl-stdlib-docs}/EvaluatorSettings
:uri-stdlib-pklbinaryModule: {uri-pkl-stdlib-docs}/pklbinary
:uri-stdlib-evaluatorSettingsHttpClass: {uri-stdlib-evaluatorSettingsModule}/Http
:uri-stdlib-Boolean: {uri-stdlib-baseModule}/Boolean
:uri-stdlib-xor: {uri-stdlib-baseModule}/Boolean#xor()

12
docs/modules/bindings-specification/pages/binary-encoding.adoc
View File

@@ -1,9 +1,15 @@
= Pkl Binary Encoding
= `pkl-binary` Encoding
include::ROOT:partial$component-attributes.adoc[]
include::partial$component-attributes.adoc[]
Pkl values can be encoded into a binary format.
This format is used for Pkl's non-JVM language bindings, for example, for its Go and Swift bindings.
:uri-pkl-core-Evaluator: {uri-pkl-core-main-sources}/Evaluator.java
Pkl values can be encoded into a binary format called "pkl-binary".
This format is a lossless serialization of the underlying Pkl values.
Pkl code can be rendered into this format using the {uri-stdlib-pklbinaryModule}[pkl:pklbinary] standard library module.
Alternatively, many language bindings also provide methods to evaluate into `pkl-binary`, such as the `evaluateExpressionPklBinary` method in link:{uri-pkl-core-Evaluator}[org.pkl.core.Evaluator].
The binary format is uses link:{uri-messagepack}[MessagePack] encoding.

23
stdlib/pklbinary.pkl
View File

@@ -14,15 +14,30 @@
// limitations under the License.
//===----------------------------------------------------------------------===//
/// APIs for handling Pkl's [binary encoding format](https://pkl-lang.org/main/current/bindings-specification/binary-encoding.html).
/// APIs for working with `pkl-binary` encoding.
///
/// `pkl-binary` is a binary encoding of Pkl data.
/// It can be used to encode all values, with the exception of [Function] types (lambda
/// expressions).
///
/// `pkl-binary` encoding is useful for separating evaluation and data consumption into two
/// separate steps.
/// For example, applications can produce `pkl-binary` at build time, and deserialize this into
/// code-generated structs at application runtime.
///
/// The `pkl-binary` format uses MessagePack encoding.
/// Its specification is available at
/// <https://pkl-lang.org/main/current/bindings-specification/binary-encoding.html>.
@ModuleInfo { minPklVersion = "0.30.0" }
module pkl.pklbinary
/// Render values as the [`pkl-binary` encoding format](https://pkl-lang.org/main/current/bindings-specification/binary-encoding.html).
/// Render values as `pkl-binary`.
class Renderer extends BytesRenderer {
/// Render a Pkl value as `pkl-binary`.
/// Renders [value] as `pkl-binary`.
external function renderValue(value: Any): Bytes
/// Render a Pkl document as `pkl-binary`.
/// Renders [value] as `pkl-binary`.
///
/// Every `pkl-binary` value is also a valid document.
external function renderDocument(value: Any): Bytes
}