diff --git a/docs/modules/ROOT/partials/component-attributes.adoc b/docs/modules/ROOT/partials/component-attributes.adoc index c34a2849..e31ca65e 100644 --- a/docs/modules/ROOT/partials/component-attributes.adoc +++ b/docs/modules/ROOT/partials/component-attributes.adoc @@ -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() diff --git a/docs/modules/bindings-specification/pages/binary-encoding.adoc b/docs/modules/bindings-specification/pages/binary-encoding.adoc index 103f8bbf..637d2530 100644 --- a/docs/modules/bindings-specification/pages/binary-encoding.adoc +++ b/docs/modules/bindings-specification/pages/binary-encoding.adoc @@ -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. diff --git a/stdlib/pklbinary.pkl b/stdlib/pklbinary.pkl index 28aaa3f3..606a8249 100644 --- a/stdlib/pklbinary.pkl +++ b/stdlib/pklbinary.pkl @@ -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 +/// . @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 }