mirror of
https://github.com/apple/pkl.git
synced 2026-06-12 00:24:37 +02:00
Aditya Singh
a9c98e4396
Several `Facts:` examples in the `pkl:base` standard library docs assert
statements that are false when evaluated. Since these examples are not
run by any test, the mistakes went unnoticed and are rendered verbatim
into the generated API docs, where they mislead readers.
The corrected examples:
- `String.isNotBlank`: `"\t\n\r".isNotBlank` was listed as holding, but
a string of only whitespace is blank, so it is false. Negated it to
match the neighboring `!"".isNotBlank` and `!" ".isNotBlank` examples.
- `DataSize.toBinaryUnit` / `toDecimalUnit`: the `mb`/`mib` lines
mirrored the `kb`/`kib` lines, but the identity only holds for adjacent
units. `1024.kb == 1000.kib` (both 1,024,000 b), whereas `1024.mb` is
1,024,000,000 b and `1000.mib` is 1,048,576,000 b, so they are not
equal. There is no clean round-number equivalent at this magnitude, so I
removed the two false lines; the remaining examples still demonstrate
the conversion.
- `Collection.any`: `!List(1, 2, 3).any((n) -> n.isEven)` is false
because 2 is even. Changed the list to `List(1, 3, 5)` so the negation
holds.
- `IntSeq.end`: the example read `IntSeq(2, 5).start == 5`, which
documents the wrong property and is false (`start` is 2). Corrected it
to `IntSeq(2, 5).end == 5`.
- `List.isDistinctBy` / `distinctBy`: `List("a", "b", "abc")` is not
distinct by length, since `"a"` and `"b"` both have length 1. Switched
to `List("a", "bb", "ccc")` so the distinctness examples hold.
- `Map`: `Map(...).values` returns a `List`, not a `Set`. Corrected the
expected type.
I verified that each corrected example evaluates to `true`, and that the
neighboring examples I kept still pass, using the released Pkl 0.31.1
binary. The changes are confined to doc-comment text, so formatting is
unaffected.
---------
Signed-off-by: Aditya Singh <adisin650@gmail.com>
= image:.idea/icon.svg[Pkl,30] Pkl
:uri-homepage: https://pkl-lang.org
:uri-docs: {uri-homepage}/main/current
:uri-docs-introduction: {uri-docs}/introduction
:uri-docs-release-notes: {uri-docs}/release-notes
:uri-docs-language: {uri-docs}/language
:uri-docs-tools: {uri-docs}/tools
:uri-github-issue: https://github.com/apple/pkl/issues
:uri-github-discussions: https://github.com/apple/pkl/discussions
:uri-pkl-examples: https://pkl-lang.org/main/current/examples.html
:uri-installation: https://pkl-lang.org/main/current/pkl-cli/index.html#installation
:uri-lang-reference: https://pkl-lang.org/main/current/language-reference/index.html
:uri-ci-artifacts: https://s01.oss.sonatype.org/content/groups/public/org/pkl-lang/
:uri-ci-pipeline: https://github.com/apple/pkl/actions
A configuration as code language with rich validation and tooling.
== Quick Links
* {uri-installation}[Installation]
* {uri-lang-reference}[Language Reference]
== Documentation
* {uri-homepage}[Home Page]
** {uri-docs-introduction}[Introduction]
** {uri-docs-language}[Language]
** {uri-docs-tools}[Tools]
** {uri-pkl-examples}[Examples]
** {uri-docs-release-notes}[Release Notes]
== Community
We'd love to hear from you!
* Create an {uri-github-issue}[issue]
* Ask a question on {uri-github-discussions}[GitHub Discussions]
== Development
image:https://github.com/apple/pkl/actions/workflows/main.yml/badge.svg?style=svg["Build (main)", link="https://github.com/apple/pkl/actions/workflows/main.yml"]
* link:CONTRIBUTING.adoc[] for tips on pull requests and filing issues
* link:DEVELOPMENT.adoc[] for build instructions
* {uri-ci-artifacts}[Sonatype Repository] for the artifacts/binaries built by our {uri-ci-pipeline}[CI pipelines] (and those of our other tools and packages repositories).
== Pkl GitHub Repositories
[%autowidth]
|===
|Name |Description
|`apple/pkl`
|A configuration as code language with rich validation and tooling.
|https://github.com/apple/pkl-evolution[`apple/pkl-evolution`]
|Suggested Pkl Improvements, Changes, or Enhancements (SPICEs)
|https://github.com/apple/pkl-go[`apple/pkl-go`]
|Pkl bindings for the Go programming language
|https://github.com/apple/pkl-go-examples[`apple/pkl-go-examples`]
|Examples for using Pkl within Go applications
|https://github.com/apple/highlightjs-pkl[`apple/highlightjs-pkl`]
|Highlight.js syntax highlighting for Pkl
|https://github.com/apple/pkl-intellij[`apple/pkl-intellij`]
|JetBrains editor plugins providing Pkl language support
|https://github.com/apple/pkl-jvm-examples[`apple/pkl-jvm-examples`]
|Examples for using Pkl within JVM applications
|https://github.com/apple/pkl-k8s[`apple/pkl-k8s`]
|Templates for using Pkl with Kubernetes
|https://github.com/apple/pkl-k8s-examples[`apple/pkl-k8s-examples`]
|Examples for using Pkl with Kubernetes
|https://github.com/apple/pkl-lang.org[`apple/pkl-lang.org`]
|The pkl-lang.org website
|https://github.com/apple/pkl-lsp[`apple/pkl-lsp`]
|Language server for Pkl, implementing the server-side of the Language Server Protocol
|https://github.com/apple/pkl-neovim[`apple/pkl-neovim`]
|Pkl language support for Neovim
|https://github.com/apple/pkl-package-docs[`apple/pkl-package-docs`]
|Documentation for Pkl packages
|https://github.com/apple/pkl-pantry[`apple/pkl-pantry`]
|Shared Pkl packages
|https://github.com/apple/pkl-project-commons[`apple/pkl-project-commons`]
|Utility libraries for Pkl
|https://github.com/apple/pkl-readers[`apple/pkl-readers`]
|Shared Pkl https://pkl-lang.org/main/current/language-reference/index.html#external-readers[external reader] tools
|https://github.com/apple/pkl-spring[`apple/pkl-spring`]
|Spring Boot extension for configuring Boot apps with Pkl
|https://github.com/apple/pkl-swift[`apple/pkl-swift`]
|Pkl bindings for the Swift programming language
|https://github.com/apple/pkl-swift-examples[`apple/pkl-swift-examples`]
|Examples for using Pkl within Swift applications
|https://github.com/apple/pkl-vscode[`apple/pkl-vscode`]
|Pkl language support for VS Code
|https://github.com/apple/pkl.tmbundle[`apple/pkl.tmbundle`]
|TextMate bundle for Pkl
|https://github.com/apple/tree-sitter-pkl[`apple/tree-sitter-pkl`]
|Tree-sitter parser for Pkl
|https://github.com/apple/rules_pkl[`apple/rules_pkl`]
|Bazel build rules for Pkl
|===