diff --git a/docs/modules/ROOT/partials/component-attributes.adoc b/docs/modules/ROOT/partials/component-attributes.adoc index e31ca65e9..47b640282 100644 --- a/docs/modules/ROOT/partials/component-attributes.adoc +++ b/docs/modules/ROOT/partials/component-attributes.adoc @@ -74,6 +74,7 @@ endif::[] :uri-stdlib-mathModule: {uri-pkl-stdlib-docs}/math :uri-stdlib-xmlModule: {uri-pkl-stdlib-docs}/xml :uri-stdlib-protobufModule: {uri-pkl-stdlib-docs}/protobuf +:uri-stdlib-pklbinaryModule: {uri-pkl-stdlib-docs}/pklbinary :uri-stdlib-evaluatorSettingsModule: {uri-pkl-stdlib-docs}/EvaluatorSettings :uri-stdlib-pklbinaryModule: {uri-pkl-stdlib-docs}/pklbinary :uri-stdlib-evaluatorSettingsHttpClass: {uri-stdlib-evaluatorSettingsModule}/Http @@ -131,7 +132,9 @@ endif::[] :uri-stdlib-Class: {uri-stdlib-baseModule}/Class :uri-stdlib-TypeAlias: {uri-stdlib-baseModule}/TypeAlias :uri-stdlib-Deprecated: {uri-stdlib-baseModule}/Deprecated +:uri-stdlib-BaseValueRenderer: {uri-stdlib-baseModule}/BaseValueRenderer :uri-stdlib-ValueRenderer: {uri-stdlib-baseModule}/ValueRenderer +:uri-stdlib-BytesRenderer: {uri-stdlib-baseModule}/BytesRenderer :uri-stdlib-PcfRenderer-converters: {uri-stdlib-baseModule}/PcfRenderer#converters :uri-stdlib-Function: {uri-stdlib-baseModule}/Function :uri-stdlib-Function0: {uri-stdlib-baseModule}/Function0 diff --git a/docs/modules/language-reference/pages/index.adoc b/docs/modules/language-reference/pages/index.adoc index 2a6c94b73..139e47e49 100644 --- a/docs/modules/language-reference/pages/index.adoc +++ b/docs/modules/language-reference/pages/index.adoc @@ -1423,7 +1423,7 @@ The recipe for transforming a listing is: . Transform the list using ``List``'s link:{uri-stdlib-List}[rich API]. . If necessary, convert the list back to a listing. -TIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-ValueRenderer}[value renderer]. +TIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-BaseValueRenderer}[value renderer]. Because most value renderers treat lists the same as listings, it is often not necessary to convert back to a listing. Equipped with this knowledge, let's try to accomplish our objective: @@ -1803,7 +1803,7 @@ The recipe for transforming a mapping is: . Transform the map using ``Map``'s link:{uri-stdlib-Map}[rich API]. . If necessary, convert the map back to a mapping. -TIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-ValueRenderer}[value renderer]. +TIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-BaseValueRenderer}[value renderer]. As most value renderers treat maps the same as mappings, it is often not necessary to convert back to a mapping. Equipped with this knowledge, let's try to accomplish our objective: diff --git a/docs/modules/pkl-cli/partials/cli-common-options.adoc b/docs/modules/pkl-cli/partials/cli-common-options.adoc index 8f2b84409..5b9a3c891 100644 --- a/docs/modules/pkl-cli/partials/cli-common-options.adoc +++ b/docs/modules/pkl-cli/partials/cli-common-options.adoc @@ -163,3 +163,11 @@ The left-hand side describes the source prefix, and the right-hand describes the This option is commonly used to enable package mirroring. The above example will rewrite URL `\https://pkg.pkl-lang.org/pkl-k8s/k8s@1.0.0` to `\https://my.internal.mirror/pkl-k8s/k8s@1.0.0`. ==== + +.--trace-mode +[%collapsible] +==== +Default: `compact` + +Specifies how `trace()` output is formatted. +Possible options are `compact` and `pretty`. +==== diff --git a/docs/modules/release-notes/pages/0.29.adoc b/docs/modules/release-notes/pages/0.29.adoc index 2f424f064..d3ea4e461 100644 --- a/docs/modules/release-notes/pages/0.29.adoc +++ b/docs/modules/release-notes/pages/0.29.adoc @@ -342,6 +342,7 @@ In Pkl 0.29, it is an error to load a module or resource with an opaque `file:` NOTE: To import or read a relative path, omit `file:` from the import string. For example, `import("foo/bar.txt")` instead of `import("file:foo/bar.txt")`. +[[new-base-module-names]] === New base module names: `Bytes` and `Charset` Two new names are introduced to the base module: `Bytes` and `Charset`. diff --git a/docs/modules/release-notes/pages/0.30.adoc b/docs/modules/release-notes/pages/0.30.adoc index 20e60e43c..ff95c39c9 100644 --- a/docs/modules/release-notes/pages/0.30.adoc +++ b/docs/modules/release-notes/pages/0.30.adoc @@ -1,32 +1,344 @@ = Pkl 0.30 Release Notes :version: 0.30 :version-minor: 0.30.0 -:release-date: TBD +:release-date: November 3rd, 2025 -link:ROOT:partial$component-attributes.adoc[role=include] +include::ROOT:partial$component-attributes.adoc[] Pkl {version} was released on {release-date}. + [.small]#The latest bugfix release is {version-minor}. (xref:changelog.adoc[All Versions])# -The next release (0.XX) is scheduled for ???.. +This release introduces a code formatter, and an in-language API for producing `pkl-binary` output. + +The next release (0.31) is scheduled for February 2026. To see what's coming in the future, follow the {uri-pkl-roadmap}[Pkl Roadmap]. -Please send feedback and questions to https://github.com/apple/pkl/discussions[GitHub Discussions], or submit an issue on https://github.com/apple/pkl/issues/new[Github]. + +Please send feedback and questions to https://github.com/apple/pkl/discussions[GitHub Discussions], or submit an issue on https://github.com/apple/pkl/issues/new[GitHub]. + [small]#Pkl is hosted on https://github.com/apple/pkl[GitHub]. To get started, follow xref:pkl-cli:index.adoc#installation[Installation].# == Highlights [small]#💖# -News you don't want to miss. +[[formatter]] +=== Formatter + +Pkl now has a formatter (https://github.com/apple/pkl/pull/1107[#1107], https://github.com/apple/pkl/pull/1208[#1208], https://github.com/apple/pkl/pull/1211[#1211], https://github.com/apple/pkl/pull/1215[#1215], https://github.com/apple/pkl/pull/1217[#1217], https://github.com/apple/pkl/pull/1235[#1235], https://github.com/apple/pkl/pull/1246[#1246], https://github.com/apple/pkl/pull/1247[#1247], https://github.com/apple/pkl/pull/1252[#1252], https://github.com/apple/pkl/pull/1256[#1256], https://github.com/apple/pkl/pull/1259[#1259], https://github.com/apple/pkl/pull/1260[#1260], https://github.com/apple/pkl/pull/1263[#1263], https://github.com/apple/pkl/pull/1265[#1265], https://github.com/apple/pkl/pull/1266[#1266], https://github.com/apple/pkl/pull/1267[#1267], https://github.com/apple/pkl/pull/1270[#1270], https://github.com/apple/pkl/pull/1271[#1271], https://github.com/apple/pkl/pull/1272[#1272], https://github.com/apple/pkl/pull/1273[#1273], https://github.com/apple/pkl/pull/1274[#1274])! + +Pkl's formatter is _canonical_, which means that it has a single set of formatting rules, with (almost) no configuration options. +The goal is to eliminate the possibility of formatting debates, which can lead to churn and bike-shedding. + +The formatter is available both as a CLI subcommand and as a Java API. + +To learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0014-canonical-formatter.adoc[SPICE-0014]. + +==== Using the CLI + +The Pkl formatter is available under the `pkl format` subcommand. By default, the command will concatenate and write all formatted content to standard out. + +To simply check for formatting violations, getting formatted output on stdout is likely too verbose. +The `--silent` flag can be used to omit any output, and the <> can be used to determine +if there are formatting violations. + +[source,shell] +---- +pkl format --silent . || echo "Formatting violations were found!" +---- + +Alternatively, the `--names` flag will print out the names of any files that have formatting violations. + +[source,shell] +---- +pkl format --diff-name-only . +---- + +To apply formatting, use the `--overwrite` (`-w`) flag. +This also implies the `--diff-name-only` flag. + +[source,shell] +---- +pkl format -w . +---- + +[[formatting-exit-codes]] +==== Exit codes + +The formatter will exit with the following codes: + +|=== +|Code |Description + +|0 +|No formatting violations were found. + +|1 +|Non-formatting errors occurred. + +|11 +|Formatting violations were found. +|=== + +==== Grammar version + +The formatter can be configured with a _grammar version_, which maps to a Pkl version range. + +|=== +|Grammar version |Pkl versions + +|1 +|0.25 - 0.29 + +|2 +|0.30+ +|=== + +Grammar version 2 uses the newly introduced <> feature, and therefore is not compatible with existing versions of Pkl. +To ensure compatibility, use the `--grammar-version 1` CLI flag. -=== XXX +[[binary-renderer-parser]] +=== `pkl-binary` in-language Renderer + +A new in-language API has been added to render values into xref:bindings-specification:binary-encoding.adoc[pkl-binary encoding] (https://github.com/apple/pkl/pull/1203[#1203], +https://github.com/apple/pkl/pull/1250[#1250]). + +It's sometimes useful to separate Pkl evaluation from data consumption when used as application or service configuration. +This is possible with the `pkl-binary` format, which is a lossless encoding of Pkl data. + +In this approach, Pkl is first rendered into `pkl-binary` during build time, and then deserialized into classes and structs at startup time. +This means that the Pkl evaluator does not need to be shipped with the application, which improves code portability and eliminates runtime overhead. + +However, currently, the API for getting this binary format is somewhat cumbersome. +Only the host languages have access to this API (for example, https://swiftpackageindex.com/apple/pkl-swift/0.6.0/documentation/pklswift/evaluator/evaluateexpressionraw(source:expression:)[`evaluateExpressionRaw`] in pkl-swift). +This means that one-off logic must be written to render this format in the host language. + +In 0.30, this renderer is added as an in-language API, through the {uri-stdlib-pklbinaryModule}[`pkl:pklbinary`] standard library module. +Additionally, it is available through CLI flag `--format pkl-binary`. + +For example: + +// this is parsed instead of tested because DocSnippetTests only handles textual output (via ReplServer) +[source%parsed,pkl] +---- +import "pkl:pklbinary" + +output { + renderer = new pklbinary.Renderer {} +} +---- + +To learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0021-binary-renderer-and-parser.adoc[SPICE-0021]. + +==== New renderer type: `BytesRenderer` + +To enable the `pkl-binary` renderer feature, Pkl now supports renderers that produce `Bytes` output (https://github.com/apple/pkl/pull/1203[#1203]). + +The existing `ValueRenderer` class now extends new class `BaseValueRenderer`, and a new `BytesRenderer` class is introduced. + +Setting a module's output renderer to a `BytesRenderer` will control its resulting `output.bytes`. + +This affects usage scenarios where a module's `output.bytes` is evaluated, for example, when using `pkl eval`. + +==== Using `pkl-binary` data + +Users of Pkl's language binding libraries can decode `pkl-binary` data into instances of code-generated types. + +[tabs] +==== +Java:: ++ +[source,java] +---- +var encodedData = fetchEncodedData(); // some byte[] or InputStream +var config = Config.from(encodedData); +var appConfig = config.as(AppConfig.class); +---- + +Kotlin:: ++ +[source,kotlin] +---- +val encodedData = fetchEncodedData() // some ByteArray or InputStream +val config = Config.from(encodedData, ValueMapper.preconfigured().forKotlin()) +val appConfig = config.to() +---- + +Go:: ++ +[source,go] +---- +encodedData := fetchEncodedData() // some []byte +var appConfig AppConfig +if err := pkl.Unmarshal(encodedData, &result); err != nil { + // handle error +} +---- + +Swift:: ++ +[source,swift] +---- +let encodedData = fetchEncodedData() // some [UInt8] +let appConfig = try PklDecoder.decode(AppConfig.self, from: encodedData) +---- +==== == Noteworthy [small]#🎶# -Ready when you need them. +[[trailing-commas]] +=== Trailing Commas + +Pkl's grammar has been updated to allow including a comma following the final item of comma-separated syntax elements (https://github.com/apple/pkl/pull/1137[#1137]). + +These syntax elements are affected: + +[source%tested,pkl] +---- +function add( + bar, + baz, // <1> +) = bar + baz + +foo = add( + 1, + 2, // <2> +) -=== XXX +typealias MyMapping< + Key, + Value, // <3> +> = Mapping + +bar: Mapping< + String, + Int, // <4> +> + +baz: Mapping( + !containsKey("forbidden key"), + !containsKey("forbidden value"), // <5> +) + +qux: ( + String, + Int, // <6> +) -> Dynamic = + (paramA, paramB) -> new Dynamic { + quux = "\(paramA): \(paramB)" + } + +corge = (qux) { + paramA, + paramB, // <7> + -> + grault = paramA.length * paramB +} +---- +<1> Function parameter lists in method definitions. +<2> Argument lists in method calls. +<3> Type parameter lists in generic type definitions. +<4> Type argument lists in type annotations and casts. +<5> Type constraint lists. +<6> Function type parameter lists in function type annotations. +<7> Object body parameter lists. + +To learn more about this change, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0019-trailing-commas.adoc[SPICE-0019]. + +=== Pretty-printed traces + +A new evaluator option is added to enable pretty-printed traces (https://github.com/apple/pkl/pull/1100[#1100], https://github.com/apple/pkl/pull/1227[#1227], https://github.com/apple/pkl/pull/1230[#1230]). + +Currently, the `trace()` operator will render values as a single line, and trims the output after 100 characters. +This can obscure information when debugging. + +In 0.30, a new evaluator option is added to control how traces are emitted. +Two trace modes are introduced: + +* `compact` - the current output mode (default). +* `pretty` - multiline, with no limit on output size. + +For example, users of the CLI can specify `--trace-mode` as a flag. + +[source,shell] +---- +pkl eval --trace-mode pretty myModule.pkl +---- + +Thanks to https://github.com/ssalevan[@ssalevan] for their contribution to this feature! + +[[pkldoc-perf-improvements]] +=== `pkldoc` performance improvements + +The `pkldoc` documentation generator has been overhauled (https://github.com/apple/pkl/pull/1169[#1169], https://github.com/apple/pkl/pull/1224[#1224], https://github.com/apple/pkl/pull/1241[#1241], https://github.com/apple/pkl/pull/1242[#1242]). + +Currently, the `pkldoc` tool needs to consume much of an existing documentation website whenever generating new documentation. +This adds significant I/O overhead as a pkldoc documentation website grows. + +The generator has been overhauled to minimize the amount of data needed to be read from the current site. + +To read more about this change, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0018-pkldoc-io-improvements.adoc[SPICE-0018]. + +[[pkldoc-migration]] +==== Migration + +The new pkldoc website introduces breaking changes to the data model. +Because of this, existing sites must be migrated before using the `0.30` version of pkldoc. + +To migrate, run the one-time command `pkldoc --migrate`. + +=== Java API changes + +==== New classes + +New classes are introduced to the Java API. + +* `org.pkl.core.PklBinaryDecoder` + +==== New methods + +New methods are introduced to the Java API. + +* `org.pkl.core.Evaluator.evaluateExpressionPklBinary` +* `org.pkl.core.EvaluatorBuilder.setTraceMode` +* `org.pkl.core.EvaluatorBuilder.getTraceMode` +* `org.pkl.config.java.Config.fromPklBinary` + +=== Standard Library changes + +New modules, properties, methods, classes and typealiases have been added to the standard library (https://github.com/apple/pkl/pull/1106[#1106]). + +==== Changes to `pkl:base` + +Additions: + +* New class: {uri-stdlib-BaseValueRenderer}[`BaseValueRenderer`] +* {uri-stdlib-ValueRenderer}[`ValueRenderer`] (now a subclass of {uri-stdlib-BaseValueRenderer}[`BaseValueRenderer`]) +* {uri-stdlib-BytesRenderer}[`BytesRenderer`] +* {uri-stdlib-baseModule}/RenderDirective#bytes[`RenderDirective.bytes`] + +==== Additions to `pkl:EvaluatorSettings` + +* {uri-stdlib-evaluatorSettingsModule}#traceMode[`traceMode`] + +==== Additions to `pkl:reflect` + +* {uri-stdlib-reflectModule}/Class#allMethods[`Class.allMethods`] +* {uri-stdlib-reflectModule}/Class#allProperties[`Class.allProperties`] +* {uri-stdlib-reflectModule}/Property#allAnnotations[`Propterty.allAnnotations`] +* {uri-stdlib-reflectModule}/Propterty#allModifiers[`Propterty.allModifiers`] + +==== New module: `pkl:pklbinary` + +The `pkl:pklbinary` standard library module is added. + +=== `pkl repl` improvements + +The REPL now handles interrupts (Ctrl-C) in a more user-friendly way (https://github.com/apple/pkl/pull/1188[#1188]). + +Instead of exiting immediately, it behaves like other REPLs: + +* If the line is non-empty or in a continuation, the buffer is cleared. +* If the line is empty, print a message with instructions on exiting the REPL. +** If another interrupt is sent immediately after, exit. == Breaking Changes [small]#💔# @@ -34,20 +346,46 @@ Things to watch out for when upgrading. === Minimum Kotlin version bump -For users of Pkl's Kotlin libraries, the minimum Kotlin version has been bumped to 2.1 (https://github.com/apple/pkl/pull/900[#900]). +For users of Pkl's Kotlin libraries, the minimum Kotlin version has been bumped to 2.1 (https://github.com/apple/pkl/pull/1232[#1232]). + +=== New base module names: `BaseValueRenderer`, `BytesRenderer` + +Two new names are introduced to the base module: `BaseValueRenderer`, and `BytesRenderer`. +That means that any code that currently references these names on implicit `this` will break (https://github.com/apple/pkl/pull/1203[#1203]). + +To learn more about how this breaks code and how to fix it, see xref:0.29.adoc#new-base-module-names[New base module names] in 0.29's release notes. + +=== `pkldoc` sites need to be migrated + +Due to breaking changes made in pkldoc's data model, existing pkldoc websites must be migrated. + +See <> for more details. == Miscellaneous [small]#🐸# -* XXX +* Dependency updates (https://github.com/apple/pkl/pull/1184[#1184], https://github.com/apple/pkl/pull/1225[#1225], https://github.com/apple/pkl/pull/1226[#1226], https://github.com/apple/pkl/pull/1228[#1228]). +* Enforce Pkl formatting of stdlib (https://github.com/apple/pkl/pull/1236[#1236], https://github.com/apple/pkl/pull/1253[#1253], https://github.com/apple/pkl/pull/1258[#1258]). +* Add internal IntelliJ plugin that's meant to assist with development of the Pkl codebase itself (https://github.com/apple/pkl/pull/1248[#1248]). +* Update CircleCI macOS instance type and Xcode version (https://github.com/apple/pkl/pull/1243[#1243], https://github.com/apple/pkl/pull/1244[#1244]). +* Disable multi-jdk testing when running on Windows ARM (https://github.com/apple/pkl/pull/1223[#1223]). +* Refine documentation for class `Any` (https://github.com/apple/pkl/pull/1194[#1194]). == Bugs fixed [small]#🐜# The following bugs have been fixed. -* XXX (https://github.com/apple/pkl/issues/XXX[XXX]) +* Incorrect error message when refusing to read past root dir (https://github.com/apple/pkl/pull/1234[#1233]). +* Unicode U+7FFF character (翿) incorrectly parsed as EOF (https://github.com/apple/pkl/pull/1251[#1251]). +* Fallback certificates do not work in certain classloader setups (https://github.com/apple/pkl/pull/1198[#1199]). == Contributors [small]#🙏# We would like to thank the contributors to this release (in alphabetical order): -* XXX +* https://github.com/bioball[@bioball] +* https://github.com/HT154[@HT154] +* https://github.com/netvl[@netvl] +* https://github.com/spyoungtech[@spyoungtech] +* https://github.com/srueg[@srueg] +* https://github.com/ssalevan[@ssalevan] +* https://github.com/stackoverflow[@stackoverflow] diff --git a/docs/modules/release-notes/pages/changelog.adoc b/docs/modules/release-notes/pages/changelog.adoc index 16f8f0c8c..7fde1a3c7 100644 --- a/docs/modules/release-notes/pages/changelog.adoc +++ b/docs/modules/release-notes/pages/changelog.adoc @@ -2,7 +2,9 @@ include::ROOT:partial$component-attributes.adoc[] [[release-0.30.0]] -== 0.30.0 (TBD) +== 0.30.0 (2025-10-30) + +xref:0.30.adoc[Release notes] [[release-0.29.1]] == 0.29.1 (2025-08-27)