[ { "path": ".editorconfig", "content": "root = true\n\n[*]\ncharset = utf-8\nindent_style = space\nindent_size = 2\n# don't trim whitespace within (say) a Pkl multiline string\ntrim_trailing_whitespace = false\ninsert_final_newline = true\nmax_line_length = 100\n" }, { "path": ".git-blame-ignore-revs", "content": "# Auto-format Kotlin code\n816cd483c8adf4c04e14236c173a1dc6bd2579ea\n" }, { "path": ".gitattributes", "content": "# linguist-generated would suppress files in diffs\n**/src/test/files/** linguist-vendored\n.github/workflows/* linguist-generated\n\n/docs/** linguist-documentation\n\n*.pcf linguist-language=Pkl\nPklProject linguist-language=Pkl\n\n* text eol=lf\n*.bat text eol=crlf\n\n*.gif binary\n*.jar binary\n*.woff2 binary\n*.pem binary\n*.png binary\n" }, { "path": ".githooks/pre-commit", "content": "#!/bin/sh\n\nfiles=`git diff --cached --name-status`\n\nif [[ $files =~ .github/* ]]; then\n pkl eval --project-dir .github/ -m .github .github/index.pkl\n git add .github/workflows/\nfi\n" }, { "path": ".github/PklProject", "content": "amends \"pkl:Project\"\n\ndependencies {\n [\"pkl.impl.ghactions\"] {\n uri = \"package://pkg.pkl-lang.org/pkl-project-commons/pkl.impl.ghactions@1.5.0\"\n }\n [\"gha\"] {\n uri = \"package://pkg.pkl-lang.org/pkl-pantry/com.github.actions@1.2.0\"\n }\n}\n" }, { "path": ".github/PklProject.deps.json", "content": "{\n \"schemaVersion\": 1,\n \"resolvedDependencies\": {\n \"package://pkg.pkl-lang.org/pkl-pantry/com.github.actions@1\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://pkg.pkl-lang.org/pkl-pantry/com.github.actions@1.3.1\",\n \"checksums\": {\n \"sha256\": \"fd515da685ea126678c3ec684e84a4f992d43481cc1d75cb866cd55775f675f9\"\n }\n },\n \"package://pkg.pkl-lang.org/pkl-project-commons/pkl.impl.ghactions@1\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://pkg.pkl-lang.org/pkl-project-commons/pkl.impl.ghactions@1.5.0\",\n \"checksums\": {\n \"sha256\": \"2c1e0d9efcd65b3c3207bf535c325ebc0ec2ab169187b324c4bb70821cac0e51\"\n }\n },\n \"package://pkg.pkl-lang.org/pkl-pantry/pkl.experimental.deepToTyped@1\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://pkg.pkl-lang.org/pkl-pantry/pkl.experimental.deepToTyped@1.2.0\",\n \"checksums\": {\n \"sha256\": \"84c7feb391f4ac273a99dc89b8fd51dbcd21dbda4ce640f6908527f83acdd4d6\"\n }\n },\n \"package://pkg.pkl-lang.org/pkl-pantry/pkl.github.dependabotManagedActions@1\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://pkg.pkl-lang.org/pkl-pantry/pkl.github.dependabotManagedActions@1.0.3\",\n \"checksums\": {\n \"sha256\": \"d368900942efb88ed51a98f9614748b06c74ba43423f045fcd6dedb5dbdc0bea\"\n }\n },\n \"package://pkg.pkl-lang.org/pkl-pantry/com.github.dependabot@1\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://pkg.pkl-lang.org/pkl-pantry/com.github.dependabot@1.0.0\",\n \"checksums\": {\n \"sha256\": \"02ef6f25bfca5b1d095db73ea15de79d2d2c6832ebcab61e6aba90554382abcb\"\n }\n }\n }\n}\n" }, { "path": ".github/dependabot.yml", "content": "version: 2\nupdates:\n- package-ecosystem: github-actions\n directory: /\n ignore:\n - dependency-name: '*'\n update-types:\n - version-update:semver-major\n schedule:\n interval: weekly\n" }, { "path": ".github/index.pkl", "content": "amends \"@pkl.impl.ghactions/PklCI.pkl\"\n\nimport \"@gha/Workflow.pkl\"\n\nimport \"jobs/BuildJavaExecutableJob.pkl\"\nimport \"jobs/BuildNativeJob.pkl\"\nimport \"jobs/DeployJob.pkl\"\nimport \"jobs/GithubRelease.pkl\"\nimport \"jobs/GradleJob.pkl\"\nimport \"jobs/PklJob.pkl\"\nimport \"jobs/SimpleGradleJob.pkl\"\n\ntriggerDocsBuild = \"both\"\n\ntestReports {\n junit {\n \"**/build/test-results/**/*.xml\"\n }\n html {\n \"**/build/reports/tests/**/*\"\n }\n excludeJobs {\n \"bench\"\n \"github-release\"\n Regex(\"deploy-.*\")\n }\n}\n\nlocal baseGradleCheck: SimpleGradleJob = new {\n isRelease = false\n command = \"check\"\n fetchDepth = 0\n}\n\nlocal gradleCheck = (baseGradleCheck) {\n os = \"linux\"\n}\n\nlocal gradleCheckWindows = (baseGradleCheck) {\n os = \"windows\"\n}\n\nlocal typealias PklJobs = Mapping\n\nlocal toWorkflowJobs: (PklJobs) -> Workflow.Jobs = (it) -> new Workflow.Jobs {\n for (k, v in it) {\n [k] = v.job\n }\n}\n\nlocal gradleCheckJobs: PklJobs = new {\n [\"gradle-check\"] = gradleCheck\n [\"gradle-check-windows\"] = gradleCheckWindows\n}\n\nlocal buildNativeJobs: Mapping = new {\n for (_dist in List(\"release\", \"snapshot\")) {\n for (_project in List(\"pkl-cli\", \"pkl-doc\")) {\n for (_arch in List(\"amd64\", \"aarch64\")) {\n for (_os in List(\"macOS\", \"linux\")) {\n [\"\\(_project)-\\(_os)-\\(_arch)-\\(_dist)\"] {\n arch = _arch\n os = _os\n isRelease = _dist == \"release\"\n project = _project\n }\n }\n }\n [\"\\(_project)-alpine-linux-amd64-\\(_dist)\"] {\n arch = \"amd64\"\n os = \"linux\"\n musl = true\n isRelease = _dist == \"release\"\n project = _project\n }\n [\"\\(_project)-windows-amd64-\\(_dist)\"] {\n arch = \"amd64\"\n os = \"windows\"\n isRelease = _dist == \"release\"\n project = _project\n }\n }\n }\n}\n\nlocal buildNativeSnapshots = buildNativeJobs.toMap().filter((key, _) -> key.endsWith(\"snapshot\"))\n\nlocal buildNativeReleases = buildNativeJobs.toMap().filter((key, _) -> key.endsWith(\"release\"))\n\nlocal benchmarkJob: SimpleGradleJob = new { command = \"bench:jmh\" }\n\nlocal gradleCompatibilityJob: SimpleGradleJob = new {\n command = \":pkl-gradle:build :pkl-gradle:compatibilityTestReleases\"\n fetchDepth = 0\n}\n\nlocal buildJavaExecutableJob: BuildJavaExecutableJob = new {\n fetchDepth = 0\n}\n\nlocal buildAndTestJobs: PklJobs = new {\n ...gradleCheckJobs\n [\"bench\"] = benchmarkJob\n [\"gradle-compatibility\"] = gradleCompatibilityJob\n [\"java-executables-snapshot\"] = (buildJavaExecutableJob) { isRelease = false }\n ...buildNativeSnapshots\n}\n\nlocal releaseJobs: PklJobs = new {\n ...gradleCheckJobs\n [\"bench\"] = benchmarkJob\n [\"gradle-compatibility\"] = gradleCompatibilityJob\n [\"java-executables-release\"] = (buildJavaExecutableJob) { isRelease = true }\n ...buildNativeReleases\n}\n\n// By default, just run ./gradlew check on linux.\n// Trigger other checks based on GitHub PR description. Examples:\n//\n// * [windows] -- Test on Windows\n// * [native] -- Test all native builds\n// * [native-pkl-cli] -- Test all pkl-cli os/arch pairs\n// * [native-pkl-cli-macos] -- Test pkl-cli on macOS\nprb {\n local prbJobs: Mapping = new {\n [\"gradle-check\"] = gradleCheck\n [\"gradle-check-windows\"] = (gradleCheckWindows) {\n `if` = \"contains(github.event.pull_request.body, '[windows]')\"\n }\n for (jobName, job in buildNativeSnapshots) {\n [jobName] = (job) {\n local tags = new Listing {\n \"[native]\"\n \"[native-\\(job.project)]\"\n \"[native-\\(job.project)-\\(job.os)]\"\n \"[native-\\(job.project)-\\(job.os)-\\(job.arch)]\"\n \"[native-\\(job.project)-\\(job.os)-\\(job.arch)]\"\n when (job.musl) {\n \"[native-\\(job.project)-alpine-\\(job.os)-\\(job.arch)]\"\n }\n }\n `if` =\n tags\n .toList()\n .map((it) -> \"contains(github.event.pull_request.body, '\\(it)')\")\n .join(\" || \")\n }\n }\n }\n local prbJobs2 = (prbJobs) {\n [[true]] {\n // better SLA when not running on nightly\n nightlyMacOS = false\n }\n }\n jobs = prbJobs2 |> toWorkflowJobs\n}\n\nbuild {\n jobs = buildAndTestJobs |> toWorkflowJobs\n}\n\nmain {\n jobs =\n (buildAndTestJobs) {\n [\"deploy-snapshot\"] = (\n new DeployJob {\n extraGradleArgs {\n \"--no-parallel\"\n }\n command = \"publishToSonatype\"\n }\n ) {\n needs = buildAndTestJobs.keys.toListing()\n }\n } |> toWorkflowJobs\n}\n\nreleaseBranch {\n jobs = releaseJobs |> toWorkflowJobs\n}\n\nrelease {\n jobs =\n (releaseJobs) {\n [\"deploy-release\"] = (\n new DeployJob {\n isRelease = true\n command = \"publishToSonatype closeAndReleaseSonatypeStagingRepository\"\n }\n ) {\n needs = releaseJobs.keys.toListing()\n }\n [\"github-release\"] = new GithubRelease {\n needs = \"deploy-release\"\n }\n } |> toWorkflowJobs\n}\n" }, { "path": ".github/jobs/BuildJavaExecutableJob.pkl", "content": "extends \"GradleJob.pkl\"\n\nimport \"@gha/catalog.pkl\"\n\n// Keep this in sync with projects that build java executables\nlocal projects: List = List(\"pkl-doc\", \"pkl-cli\", \"pkl-codegen-java\", \"pkl-codegen-kotlin\")\n\nlocal command =\n new Listing {\n \"./gradlew\"\n module.gradleArgs\n for (project in projects) {\n // NOTE: `build` doesn't build native executables\n \"\\(project):build\"\n }\n }.join(\" \")\n\nsteps {\n catalog.`actions/checkout@v6`\n new {\n name = \"gradle build java executables\"\n shell = \"bash\"\n run = command\n }\n (catalog.`actions/upload-artifact@v5`) {\n name = \"Upload executable artifacts\"\n with {\n name = \"executable-java\"\n path = \"*/build/executable/**/*\"\n }\n }\n}\n" }, { "path": ".github/jobs/BuildNativeJob.pkl", "content": "extends \"GradleJob.pkl\"\n\nimport \"@gha/catalog.pkl\"\nimport \"@gha/context.pkl\"\n\n/// Whether to link to musl. Otherwise, links to glibc.\nmusl: Boolean(implies(module.os == \"linux\")) = false\n\n/// The Gradle project under which to generate the executable\nproject: String\n\nextraGradleArgs {\n when (os == \"macOS\" && arch == \"amd64\") {\n \"-Dpkl.targetArch=\\(module.arch)\"\n #\"\"-Dpkl.native--native-compiler-path=${GITHUB_WORKSPACE}/.github/scripts/cc_macos_amd64.sh\"\"#\n }\n when (musl) {\n \"-Dpkl.musl=true\"\n }\n}\n\npreSteps {\n when (os == \"linux\" && !musl) {\n new {\n name = \"Install deps\"\n run = \"dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\"\n }\n }\n}\n\nsteps {\n when (musl) {\n new {\n name = \"Install musl and zlib\"\n run = read(\"../scripts/install_musl.sh\").text\n }\n }\n // workaround for https://github.com/actions/checkout/issues/1048\n when (os == \"linux\" && !musl) {\n new {\n name = \"Fix git ownership\"\n // language=bash\n run = #\"git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\"#\n }\n }\n new {\n name = \"gradle buildNative\"\n shell = \"bash\"\n run = \"./gradlew \\(module.gradleArgs) \\(project):buildNative\"\n }\n (catalog.`actions/upload-artifact@v5`) {\n name = \"Upload executable artifacts\"\n with {\n name =\n if (musl)\n \"executable-\\(project)-alpine-\\(module.os)-\\(module.arch)\"\n else\n \"executable-\\(project)-\\(module.os)-\\(module.arch)\"\n // Need to insert a wildcard to make actions/upload-artifact preserve the folder hierarchy.\n // See https://github.com/actions/upload-artifact/issues/206\n path = \"\\(project)*/build/executable/**/*\"\n }\n }\n}\n\nfixed job {\n when (os == \"linux\" && !musl) {\n container {\n image = \"redhat/ubi8:8.10\"\n }\n }\n}\n" }, { "path": ".github/jobs/DeployJob.pkl", "content": "extends \"GradleJob.pkl\"\n\nimport \"@gha/catalog.pkl\"\nimport \"@gha/Workflow.pkl\"\nimport \"@pkl.impl.ghactions/helpers.pkl\"\n\nlocal self = this\n\ncommand: String\n\narch = \"amd64\"\n\nos = \"linux\"\n\nsteps {\n catalog.`actions/checkout@v6`\n (catalog.`actions/download-artifact@v6`) {\n with {\n pattern = \"executable-**\"\n `merge-multiple` = true\n }\n }\n new Workflow.Step {\n run = \"./gradlew \\(self.gradleArgs) \\(module.command)\"\n }\n |> helpers.withMavenPublishSecrets\n}\n\nfixed job {\n environment = \"maven-release\"\n}\n" }, { "path": ".github/jobs/GithubRelease.pkl", "content": "module GithubRelease\n\nextends \"PklJob.pkl\"\n\nimport \"@gha/catalog.pkl\"\nimport \"@gha/context.pkl\"\n\nfixed job {\n `runs-on` = \"ubuntu-latest\"\n permissions {\n contents = \"write\"\n }\n needs = \"deploy-release\"\n steps {\n (catalog.`actions/download-artifact@v6`) {\n with {\n pattern = \"executable-**\"\n `merge-multiple` = true\n }\n }\n new {\n name = \"Publish release on GitHub\"\n env {\n [\"GH_TOKEN\"] = context.github.token\n [\"TAG_NAME\"] = context.github.refName\n [\"GIT_SHA\"] = context.github.sha\n [\"GH_REPO\"] = context.github.repository\n }\n // language=bash\n run =\n #\"\"\"\n # exclude build_artifacts.txt from publish\n rm -f */build/executable/*.build_artifacts.txt\n find */build/executable/* -type d | xargs rm -rf\n gh release create ${TAG_NAME} \\\n --title \"${TAG_NAME}\" \\\n --target \"${GIT_SHA}\" \\\n --verify-tag \\\n --notes \"Release notes: https://pkl-lang.org/main/current/release-notes/changelog.html#release-${TAG_NAME}\" \\\n */build/executable/*\n \"\"\"#\n }\n }\n}\n" }, { "path": ".github/jobs/GradleJob.pkl", "content": "abstract module GradleJob\n\nextends \"PklJob.pkl\"\n\nimport \"@gha/Workflow.pkl\"\nimport \"@pkl.impl.ghactions/catalog.pkl\"\n\n/// Whether this is a release build or not.\nisRelease: Boolean = false\n\n/// The architecture to use\narch: \"amd64\" | \"aarch64\" = \"amd64\"\n\n/// The OS to run on.\nos: \"macOS\" | \"linux\" | \"windows\" = \"linux\"\n\n// TODO flip this to `true` when nightly macOS is available\n/// Whether to run on nightly macOS.\nnightlyMacOS: Boolean(implies(os == \"macOS\")) = false\n\nextraGradleArgs: Listing\n\nsteps: Listing\n\npreSteps: Listing\n\n/// The fetch depth to use when doing a git checkout.\nfetchDepth: Int?\n\nfixed gradleArgs =\n new Listing {\n \"--info\"\n \"--stacktrace\"\n \"--no-daemon\"\n \"-DpklMultiJdkTesting=true\"\n when (isRelease) {\n \"-DreleaseBuild=true\"\n }\n ...extraGradleArgs\n }.join(\" \")\n\nfixed job {\n env {\n [\"LANG\"] = \"en_US.UTF-8\"\n when (os == \"windows\") {\n [\"JAVA_HOME\"] = \"/jdk\"\n }\n }\n when (os == \"macOS\") {\n `if` =\n let (cond = \"github.repository_owner == 'apple'\")\n if (super.`if` != null)\n \"(\\(super.`if`)) && \\(cond)\"\n else\n cond\n }\n `runs-on` =\n if (os == \"linux\" && arch == \"amd64\")\n \"ubuntu-latest\"\n else if (os == \"linux\" && arch == \"aarch64\")\n \"ubuntu-24.04-arm\"\n else if (os == \"windows\")\n \"windows-latest\"\n else\n new Listing {\n \"self-hosted\"\n \"macos\"\n when (nightlyMacOS) {\n \"nightly\"\n }\n }\n steps {\n ...preSteps\n // full checkout (needed for spotless)\n (catalog.`actions/checkout@v6`) {\n when (fetchDepth != null) {\n with {\n `fetch-depth` = fetchDepth\n }\n }\n }\n (catalog.`actions/setup-java@v5`) {\n with {\n `java-version` = \"21\"\n distribution = \"temurin\"\n architecture =\n if (arch == \"amd64\")\n \"x64\"\n else\n \"aarch64\"\n }\n }\n catalog.`gradle/actions/setup-gradle@v5`\n ...module.steps\n }\n}\n" }, { "path": ".github/jobs/PklJob.pkl", "content": "abstract module PklJob\n\nextends \"@pkl.impl.ghactions/jobs/PklJob.pkl\"\n\n/// Identify any jobs that must complete successfully before this job will run.\n///\n/// It can be a string or array of strings.\n/// If a job fails or is skipped, all jobs that need it are skipped unless the jobs use a conditional expression that\n/// causes the job to continue.\n/// If a run contains a series of jobs that need each other, a failure or skip applies to all jobs in the dependency\n/// chain from the point of failure or skip onwards. If you would like a job to run even if a job it is dependent on\n/// did not succeed, use the `always()` conditional expression in `jobs..if`.\n///\n/// See: \nneeds: (String | *Listing)?\n\n/// A conditional to prevent a job from running unless a condition is met.\n///\n/// You can use any supported context and expression to create a conditional.\n/// For more information on which contexts are supported in this key, see\n/// [Contexts reference](https://docs.github.com/en/actions/reference/workflows-and-actions/contexts#context-availability).\n@SourceCode { language = \"GithubExpressionLanguage\" }\n`if`: String?\n\n/// The underlying workflow job\nfixed job {\n `if` = module.`if`\n needs = module.needs\n}\n" }, { "path": ".github/jobs/SimpleGradleJob.pkl", "content": "extends \"GradleJob.pkl\"\n\nname: String = command\n\ncommand: String\n\nos = \"linux\"\n\nsteps {\n new {\n name = module.name\n shell = \"bash\"\n run =\n \"\"\"\n ./gradlew \\(module.gradleArgs) \\(module.command)\n \"\"\"\n }\n}\n" }, { "path": ".github/scripts/cc_macos_amd64.sh", "content": "#!/usr/bin/env bash\nclang -arch x86_64 \"$@\"\n" }, { "path": ".github/scripts/install_musl.sh", "content": "set -e\nmkdir -p ~/staticdeps/\n\nZLIB_VERSION=\"1.2.13\"\nMUSL_VERSION=\"1.2.5\"\n\n# install zlib\nif [[ ! -f ~/staticdeps/include/zlib.h ]]; then\n # Download zlib tarball and signature\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz\" -o /tmp/zlib.tar.gz\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz.asc\" -o /tmp/zlib.tar.gz.asc\n\n # Import zlib GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 5ED46A6721D365587791E2AA783FCD8E58BCAFBA\n\n # Verify GPG signature\n echo \"Verifying zlib GPG signature...\"\n gpg --verify /tmp/zlib.tar.gz.asc /tmp/zlib.tar.gz\n\n mkdir -p \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n cd \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n # shellcheck disable=SC2002\n cat /tmp/zlib.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"zlib-${ZLIB_VERSION}: configure...\" \n ./configure --static --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"zlib-${ZLIB_VERSION}: make...\" \n make -s -j4\n\n echo \"zlib-${ZLIB_VERSION}: make install...\" \n make -s install\n\n rm -rf /tmp/dep_zlib-${ZLIB_VERSION}\nfi\n\n# install musl\nif [[ ! -f ~/staticdeps/bin/x86_64-linux-musl-gcc ]]; then\n # Download musl tarball and signature\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz\" -o /tmp/musl.tar.gz\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz.asc\" -o /tmp/musl.tar.gz.asc\n\n # Import musl GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 836489290BB6B70F99FFDA0556BCDB593020450F\n\n # Verify GPG signature\n echo \"Verifying musl GPG signature...\"\n gpg --verify /tmp/musl.tar.gz.asc /tmp/musl.tar.gz\n\n mkdir -p \"/tmp/dep_musl-${MUSL_VERSION}\"\n cd \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # shellcheck disable=SC2002\n cat /tmp/musl.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"musl-${MUSL_VERSION}: configure...\" \n ./configure --disable-shared --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"musl-${MUSL_VERSION}: make...\" \n make -s -j4\n\n echo \"musl-${MUSL_VERSION}: make install...\" \n make -s install\n\n rm -rf \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # native-image expects to find an executable at this path.\n ln -s ~/staticdeps/bin/musl-gcc ~/staticdeps/bin/x86_64-linux-musl-gcc\nfi\n\necho \"${HOME}/staticdeps/bin\" >> \"$GITHUB_PATH\"\n" }, { "path": ".github/workflows/__lockfile__.yml", "content": "#file: noinspection MandatoryParamsAbsent,UndefinedAction\n# This is a fake workflow that never runs.\n# It's used to pin actions to specific git SHAs when generating actual workflows.\n# It also gets updated by dependabot (see .github/dependabot.yml).\n# Generated from Workflow.pkl. DO NOT EDIT.\nname: __lockfile__\n'on':\n push:\n branches-ignore:\n - '**'\n tags-ignore:\n - '**'\npermissions: {}\njobs:\n locks:\n if: 'false'\n runs-on: nothing\n steps:\n - name: EnricoMi/publish-unit-test-result-action@v2\n uses: EnricoMi/publish-unit-test-result-action@c950f6fb443cb5af20a377fd0dfaa78838901040 # v2\n - name: actions/checkout@v6\n uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n - name: actions/create-github-app-token@v2\n uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2\n - name: actions/download-artifact@v6\n uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6\n - name: actions/setup-java@v5\n uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n - name: actions/upload-artifact@v5\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n - name: dawidd6/action-download-artifact@v11\n uses: dawidd6/action-download-artifact@ac66b43f0e6a346234dd65d4d0c8fbb31cb316e5 # v11\n - name: gradle/actions/setup-gradle@v5\n uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n" }, { "path": ".github/workflows/build.yml", "content": "# Generated from Workflow.pkl. DO NOT EDIT.\nname: Build\n'on':\n push:\n branches-ignore:\n - main\n - release/*\n - dependabot/**\n tags-ignore:\n - '**'\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: false\npermissions:\n contents: read\njobs:\n gradle-check:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: check\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true check\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-check\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-check\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n gradle-check-windows:\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: check\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true check\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-check-windows\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-check-windows\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n bench:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: bench:jmh\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true bench:jmh\n gradle-compatibility:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: :pkl-gradle:build :pkl-gradle:compatibilityTestReleases\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true :pkl-gradle:build :pkl-gradle:compatibilityTestReleases\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-compatibility\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-compatibility\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n java-executables-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - name: gradle build java executables\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:build pkl-cli:build pkl-codegen-java:build pkl-codegen-kotlin:build\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-java\n path: '*/build/executable/**/*'\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-java-executables-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-java-executables-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-macOS-amd64-snapshot:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.targetArch=amd64 \"-Dpkl.native--native-compiler-path=${GITHUB_WORKSPACE}/.github/scripts/cc_macos_amd64.sh\" pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-macOS-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-macOS-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-macOS-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-linux-amd64-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-linux-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-cli-macOS-aarch64-snapshot:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-macOS-aarch64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-macOS-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-macOS-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-linux-aarch64-snapshot:\n runs-on: ubuntu-24.04-arm\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-linux-aarch64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-linux-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-linux-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-cli-alpine-linux-amd64-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Install musl and zlib\n run: |\n set -e\n mkdir -p ~/staticdeps/\n\n ZLIB_VERSION=\"1.2.13\"\n MUSL_VERSION=\"1.2.5\"\n\n # install zlib\n if [[ ! -f ~/staticdeps/include/zlib.h ]]; then\n # Download zlib tarball and signature\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz\" -o /tmp/zlib.tar.gz\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz.asc\" -o /tmp/zlib.tar.gz.asc\n\n # Import zlib GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 5ED46A6721D365587791E2AA783FCD8E58BCAFBA\n\n # Verify GPG signature\n echo \"Verifying zlib GPG signature...\"\n gpg --verify /tmp/zlib.tar.gz.asc /tmp/zlib.tar.gz\n\n mkdir -p \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n cd \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n # shellcheck disable=SC2002\n cat /tmp/zlib.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"zlib-${ZLIB_VERSION}: configure...\" \n ./configure --static --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"zlib-${ZLIB_VERSION}: make...\" \n make -s -j4\n\n echo \"zlib-${ZLIB_VERSION}: make install...\" \n make -s install\n\n rm -rf /tmp/dep_zlib-${ZLIB_VERSION}\n fi\n\n # install musl\n if [[ ! -f ~/staticdeps/bin/x86_64-linux-musl-gcc ]]; then\n # Download musl tarball and signature\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz\" -o /tmp/musl.tar.gz\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz.asc\" -o /tmp/musl.tar.gz.asc\n\n # Import musl GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 836489290BB6B70F99FFDA0556BCDB593020450F\n\n # Verify GPG signature\n echo \"Verifying musl GPG signature...\"\n gpg --verify /tmp/musl.tar.gz.asc /tmp/musl.tar.gz\n\n mkdir -p \"/tmp/dep_musl-${MUSL_VERSION}\"\n cd \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # shellcheck disable=SC2002\n cat /tmp/musl.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"musl-${MUSL_VERSION}: configure...\" \n ./configure --disable-shared --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"musl-${MUSL_VERSION}: make...\" \n make -s -j4\n\n echo \"musl-${MUSL_VERSION}: make install...\" \n make -s install\n\n rm -rf \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # native-image expects to find an executable at this path.\n ln -s ~/staticdeps/bin/musl-gcc ~/staticdeps/bin/x86_64-linux-musl-gcc\n fi\n\n echo \"${HOME}/staticdeps/bin\" >> \"$GITHUB_PATH\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.musl=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-alpine-linux-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-alpine-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-alpine-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-windows-amd64-snapshot:\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-windows-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-windows-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-windows-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-macOS-amd64-snapshot:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.targetArch=amd64 \"-Dpkl.native--native-compiler-path=${GITHUB_WORKSPACE}/.github/scripts/cc_macos_amd64.sh\" pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-macOS-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-macOS-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-macOS-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-linux-amd64-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-linux-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-doc-macOS-aarch64-snapshot:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-macOS-aarch64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-macOS-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-macOS-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-linux-aarch64-snapshot:\n runs-on: ubuntu-24.04-arm\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-linux-aarch64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-linux-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-linux-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-doc-alpine-linux-amd64-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Install musl and zlib\n run: |\n set -e\n mkdir -p ~/staticdeps/\n\n ZLIB_VERSION=\"1.2.13\"\n MUSL_VERSION=\"1.2.5\"\n\n # install zlib\n if [[ ! -f ~/staticdeps/include/zlib.h ]]; then\n # Download zlib tarball and signature\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz\" -o /tmp/zlib.tar.gz\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz.asc\" -o /tmp/zlib.tar.gz.asc\n\n # Import zlib GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 5ED46A6721D365587791E2AA783FCD8E58BCAFBA\n\n # Verify GPG signature\n echo \"Verifying zlib GPG signature...\"\n gpg --verify /tmp/zlib.tar.gz.asc /tmp/zlib.tar.gz\n\n mkdir -p \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n cd \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n # shellcheck disable=SC2002\n cat /tmp/zlib.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"zlib-${ZLIB_VERSION}: configure...\" \n ./configure --static --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"zlib-${ZLIB_VERSION}: make...\" \n make -s -j4\n\n echo \"zlib-${ZLIB_VERSION}: make install...\" \n make -s install\n\n rm -rf /tmp/dep_zlib-${ZLIB_VERSION}\n fi\n\n # install musl\n if [[ ! -f ~/staticdeps/bin/x86_64-linux-musl-gcc ]]; then\n # Download musl tarball and signature\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz\" -o /tmp/musl.tar.gz\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz.asc\" -o /tmp/musl.tar.gz.asc\n\n # Import musl GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 836489290BB6B70F99FFDA0556BCDB593020450F\n\n # Verify GPG signature\n echo \"Verifying musl GPG signature...\"\n gpg --verify /tmp/musl.tar.gz.asc /tmp/musl.tar.gz\n\n mkdir -p \"/tmp/dep_musl-${MUSL_VERSION}\"\n cd \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # shellcheck disable=SC2002\n cat /tmp/musl.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"musl-${MUSL_VERSION}: configure...\" \n ./configure --disable-shared --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"musl-${MUSL_VERSION}: make...\" \n make -s -j4\n\n echo \"musl-${MUSL_VERSION}: make install...\" \n make -s install\n\n rm -rf \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # native-image expects to find an executable at this path.\n ln -s ~/staticdeps/bin/musl-gcc ~/staticdeps/bin/x86_64-linux-musl-gcc\n fi\n\n echo \"${HOME}/staticdeps/bin\" >> \"$GITHUB_PATH\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.musl=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-alpine-linux-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-alpine-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-alpine-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-windows-amd64-snapshot:\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-windows-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-windows-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-windows-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n publish-test-results:\n if: '!cancelled()'\n needs:\n - gradle-check\n - gradle-check-windows\n - gradle-compatibility\n - java-executables-snapshot\n - pkl-cli-macOS-amd64-snapshot\n - pkl-cli-linux-amd64-snapshot\n - pkl-cli-macOS-aarch64-snapshot\n - pkl-cli-linux-aarch64-snapshot\n - pkl-cli-alpine-linux-amd64-snapshot\n - pkl-cli-windows-amd64-snapshot\n - pkl-doc-macOS-amd64-snapshot\n - pkl-doc-linux-amd64-snapshot\n - pkl-doc-macOS-aarch64-snapshot\n - pkl-doc-linux-aarch64-snapshot\n - pkl-doc-alpine-linux-amd64-snapshot\n - pkl-doc-windows-amd64-snapshot\n permissions:\n checks: write\n runs-on: ubuntu-latest\n steps:\n - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6\n with:\n pattern: test-results-xml-*\n - name: Publish test results\n if: '!cancelled()'\n uses: EnricoMi/publish-unit-test-result-action@c950f6fb443cb5af20a377fd0dfaa78838901040 # v2\n with:\n comment_mode: 'off'\n files: test-results-xml-*/**/*.xml\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-publish-test-results\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n" }, { "path": ".github/workflows/main.yml", "content": "# Generated from Workflow.pkl. DO NOT EDIT.\nname: Build (main)\n'on':\n push:\n branches:\n - main\n tags-ignore:\n - '**'\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: false\npermissions:\n contents: read\njobs:\n gradle-check:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: check\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true check\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-check\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-check\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n gradle-check-windows:\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: check\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true check\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-check-windows\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-check-windows\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n bench:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: bench:jmh\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true bench:jmh\n gradle-compatibility:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: :pkl-gradle:build :pkl-gradle:compatibilityTestReleases\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true :pkl-gradle:build :pkl-gradle:compatibilityTestReleases\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-compatibility\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-compatibility\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n java-executables-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - name: gradle build java executables\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:build pkl-cli:build pkl-codegen-java:build pkl-codegen-kotlin:build\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-java\n path: '*/build/executable/**/*'\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-java-executables-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-java-executables-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-macOS-amd64-snapshot:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.targetArch=amd64 \"-Dpkl.native--native-compiler-path=${GITHUB_WORKSPACE}/.github/scripts/cc_macos_amd64.sh\" pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-macOS-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-macOS-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-macOS-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-linux-amd64-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-linux-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-cli-macOS-aarch64-snapshot:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-macOS-aarch64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-macOS-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-macOS-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-linux-aarch64-snapshot:\n runs-on: ubuntu-24.04-arm\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-linux-aarch64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-linux-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-linux-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-cli-alpine-linux-amd64-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Install musl and zlib\n run: |\n set -e\n mkdir -p ~/staticdeps/\n\n ZLIB_VERSION=\"1.2.13\"\n MUSL_VERSION=\"1.2.5\"\n\n # install zlib\n if [[ ! -f ~/staticdeps/include/zlib.h ]]; then\n # Download zlib tarball and signature\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz\" -o /tmp/zlib.tar.gz\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz.asc\" -o /tmp/zlib.tar.gz.asc\n\n # Import zlib GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 5ED46A6721D365587791E2AA783FCD8E58BCAFBA\n\n # Verify GPG signature\n echo \"Verifying zlib GPG signature...\"\n gpg --verify /tmp/zlib.tar.gz.asc /tmp/zlib.tar.gz\n\n mkdir -p \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n cd \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n # shellcheck disable=SC2002\n cat /tmp/zlib.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"zlib-${ZLIB_VERSION}: configure...\" \n ./configure --static --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"zlib-${ZLIB_VERSION}: make...\" \n make -s -j4\n\n echo \"zlib-${ZLIB_VERSION}: make install...\" \n make -s install\n\n rm -rf /tmp/dep_zlib-${ZLIB_VERSION}\n fi\n\n # install musl\n if [[ ! -f ~/staticdeps/bin/x86_64-linux-musl-gcc ]]; then\n # Download musl tarball and signature\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz\" -o /tmp/musl.tar.gz\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz.asc\" -o /tmp/musl.tar.gz.asc\n\n # Import musl GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 836489290BB6B70F99FFDA0556BCDB593020450F\n\n # Verify GPG signature\n echo \"Verifying musl GPG signature...\"\n gpg --verify /tmp/musl.tar.gz.asc /tmp/musl.tar.gz\n\n mkdir -p \"/tmp/dep_musl-${MUSL_VERSION}\"\n cd \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # shellcheck disable=SC2002\n cat /tmp/musl.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"musl-${MUSL_VERSION}: configure...\" \n ./configure --disable-shared --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"musl-${MUSL_VERSION}: make...\" \n make -s -j4\n\n echo \"musl-${MUSL_VERSION}: make install...\" \n make -s install\n\n rm -rf \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # native-image expects to find an executable at this path.\n ln -s ~/staticdeps/bin/musl-gcc ~/staticdeps/bin/x86_64-linux-musl-gcc\n fi\n\n echo \"${HOME}/staticdeps/bin\" >> \"$GITHUB_PATH\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.musl=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-alpine-linux-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-alpine-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-alpine-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-windows-amd64-snapshot:\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-windows-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-windows-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-windows-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-macOS-amd64-snapshot:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.targetArch=amd64 \"-Dpkl.native--native-compiler-path=${GITHUB_WORKSPACE}/.github/scripts/cc_macos_amd64.sh\" pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-macOS-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-macOS-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-macOS-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-linux-amd64-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-linux-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-doc-macOS-aarch64-snapshot:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-macOS-aarch64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-macOS-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-macOS-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-linux-aarch64-snapshot:\n runs-on: ubuntu-24.04-arm\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-linux-aarch64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-linux-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-linux-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-doc-alpine-linux-amd64-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Install musl and zlib\n run: |\n set -e\n mkdir -p ~/staticdeps/\n\n ZLIB_VERSION=\"1.2.13\"\n MUSL_VERSION=\"1.2.5\"\n\n # install zlib\n if [[ ! -f ~/staticdeps/include/zlib.h ]]; then\n # Download zlib tarball and signature\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz\" -o /tmp/zlib.tar.gz\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz.asc\" -o /tmp/zlib.tar.gz.asc\n\n # Import zlib GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 5ED46A6721D365587791E2AA783FCD8E58BCAFBA\n\n # Verify GPG signature\n echo \"Verifying zlib GPG signature...\"\n gpg --verify /tmp/zlib.tar.gz.asc /tmp/zlib.tar.gz\n\n mkdir -p \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n cd \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n # shellcheck disable=SC2002\n cat /tmp/zlib.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"zlib-${ZLIB_VERSION}: configure...\" \n ./configure --static --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"zlib-${ZLIB_VERSION}: make...\" \n make -s -j4\n\n echo \"zlib-${ZLIB_VERSION}: make install...\" \n make -s install\n\n rm -rf /tmp/dep_zlib-${ZLIB_VERSION}\n fi\n\n # install musl\n if [[ ! -f ~/staticdeps/bin/x86_64-linux-musl-gcc ]]; then\n # Download musl tarball and signature\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz\" -o /tmp/musl.tar.gz\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz.asc\" -o /tmp/musl.tar.gz.asc\n\n # Import musl GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 836489290BB6B70F99FFDA0556BCDB593020450F\n\n # Verify GPG signature\n echo \"Verifying musl GPG signature...\"\n gpg --verify /tmp/musl.tar.gz.asc /tmp/musl.tar.gz\n\n mkdir -p \"/tmp/dep_musl-${MUSL_VERSION}\"\n cd \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # shellcheck disable=SC2002\n cat /tmp/musl.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"musl-${MUSL_VERSION}: configure...\" \n ./configure --disable-shared --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"musl-${MUSL_VERSION}: make...\" \n make -s -j4\n\n echo \"musl-${MUSL_VERSION}: make install...\" \n make -s install\n\n rm -rf \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # native-image expects to find an executable at this path.\n ln -s ~/staticdeps/bin/musl-gcc ~/staticdeps/bin/x86_64-linux-musl-gcc\n fi\n\n echo \"${HOME}/staticdeps/bin\" >> \"$GITHUB_PATH\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.musl=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-alpine-linux-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-alpine-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-alpine-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-windows-amd64-snapshot:\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-windows-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-windows-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-windows-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n deploy-snapshot:\n needs:\n - gradle-check\n - gradle-check-windows\n - bench\n - gradle-compatibility\n - java-executables-snapshot\n - pkl-cli-macOS-amd64-snapshot\n - pkl-cli-linux-amd64-snapshot\n - pkl-cli-macOS-aarch64-snapshot\n - pkl-cli-linux-aarch64-snapshot\n - pkl-cli-alpine-linux-amd64-snapshot\n - pkl-cli-windows-amd64-snapshot\n - pkl-doc-macOS-amd64-snapshot\n - pkl-doc-linux-amd64-snapshot\n - pkl-doc-macOS-aarch64-snapshot\n - pkl-doc-linux-aarch64-snapshot\n - pkl-doc-alpine-linux-amd64-snapshot\n - pkl-doc-windows-amd64-snapshot\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n environment: maven-release\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6\n with:\n pattern: executable-**\n merge-multiple: true\n - env:\n ORG_GRADLE_PROJECT_signingKeyId: ${{ secrets.ORG_GRADLE_PROJECT_SIGNINGKEYID }}\n ORG_GRADLE_PROJECT_signingKey: ${{ secrets.ORG_GRADLE_PROJECT_SIGNINGKEY }}\n ORG_GRADLE_PROJECT_signingPassword: ${{ secrets.ORG_GRADLE_PROJECT_SIGNINGPASSWORD }}\n ORG_GRADLE_PROJECT_sonatypePassword: ${{ secrets.ORG_GRADLE_PROJECT_SONATYPEPASSWORD }}\n ORG_GRADLE_PROJECT_sonatypeUsername: ${{ secrets.ORG_GRADLE_PROJECT_SONATYPEUSERNAME }}\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true --no-parallel publishToSonatype\n publish-test-results:\n if: '!cancelled()'\n needs:\n - gradle-check\n - gradle-check-windows\n - gradle-compatibility\n - java-executables-snapshot\n - pkl-cli-macOS-amd64-snapshot\n - pkl-cli-linux-amd64-snapshot\n - pkl-cli-macOS-aarch64-snapshot\n - pkl-cli-linux-aarch64-snapshot\n - pkl-cli-alpine-linux-amd64-snapshot\n - pkl-cli-windows-amd64-snapshot\n - pkl-doc-macOS-amd64-snapshot\n - pkl-doc-linux-amd64-snapshot\n - pkl-doc-macOS-aarch64-snapshot\n - pkl-doc-linux-aarch64-snapshot\n - pkl-doc-alpine-linux-amd64-snapshot\n - pkl-doc-windows-amd64-snapshot\n permissions:\n checks: write\n runs-on: ubuntu-latest\n steps:\n - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6\n with:\n pattern: test-results-xml-*\n - name: Publish test results\n if: '!cancelled()'\n uses: EnricoMi/publish-unit-test-result-action@c950f6fb443cb5af20a377fd0dfaa78838901040 # v2\n with:\n comment_mode: 'off'\n files: test-results-xml-*/**/*.xml\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-publish-test-results\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n trigger-downstream-builds:\n if: github.repository_owner == 'apple'\n needs:\n - gradle-check\n - gradle-check-windows\n - bench\n - gradle-compatibility\n - java-executables-snapshot\n - pkl-cli-macOS-amd64-snapshot\n - pkl-cli-linux-amd64-snapshot\n - pkl-cli-macOS-aarch64-snapshot\n - pkl-cli-linux-aarch64-snapshot\n - pkl-cli-alpine-linux-amd64-snapshot\n - pkl-cli-windows-amd64-snapshot\n - pkl-doc-macOS-amd64-snapshot\n - pkl-doc-linux-amd64-snapshot\n - pkl-doc-macOS-aarch64-snapshot\n - pkl-doc-linux-aarch64-snapshot\n - pkl-doc-alpine-linux-amd64-snapshot\n - pkl-doc-windows-amd64-snapshot\n - deploy-snapshot\n - publish-test-results\n runs-on: ubuntu-latest\n steps:\n - name: Create app token\n id: app-token\n uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2\n with:\n app-id: ${{ secrets.PKL_CI_CLIENT_ID }}\n private-key: ${{ secrets.PKL_CI }}\n owner: ${{ github.repository_owner }}\n - name: Trigger pkl-lang.org build\n env:\n GH_TOKEN: ${{ steps.app-token.outputs.token }}\n SOURCE_RUN: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\n run: |-\n gh workflow run \\\n --repo apple/pkl-lang.org \\\n --ref main \\\n --field source_run=\"${SOURCE_RUN}\" \\\n main.yml\n" }, { "path": ".github/workflows/prb.yml", "content": "# Generated from Workflow.pkl. DO NOT EDIT.\nname: Pull Request\n'on':\n pull_request: {}\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\npermissions:\n contents: read\njobs:\n gradle-check:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: check\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true check\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-check\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-check\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n gradle-check-windows:\n if: contains(github.event.pull_request.body, '[windows]')\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: check\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true check\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-check-windows\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-check-windows\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-macOS-amd64-snapshot:\n if: (contains(github.event.pull_request.body, '[native]') || contains(github.event.pull_request.body, '[native-pkl-cli]') || contains(github.event.pull_request.body, '[native-pkl-cli-macOS]') || contains(github.event.pull_request.body, '[native-pkl-cli-macOS-amd64]') || contains(github.event.pull_request.body, '[native-pkl-cli-macOS-amd64]')) && github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.targetArch=amd64 \"-Dpkl.native--native-compiler-path=${GITHUB_WORKSPACE}/.github/scripts/cc_macos_amd64.sh\" pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-macOS-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-macOS-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-macOS-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-linux-amd64-snapshot:\n if: contains(github.event.pull_request.body, '[native]') || contains(github.event.pull_request.body, '[native-pkl-cli]') || contains(github.event.pull_request.body, '[native-pkl-cli-linux]') || contains(github.event.pull_request.body, '[native-pkl-cli-linux-amd64]') || contains(github.event.pull_request.body, '[native-pkl-cli-linux-amd64]')\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-linux-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-cli-macOS-aarch64-snapshot:\n if: (contains(github.event.pull_request.body, '[native]') || contains(github.event.pull_request.body, '[native-pkl-cli]') || contains(github.event.pull_request.body, '[native-pkl-cli-macOS]') || contains(github.event.pull_request.body, '[native-pkl-cli-macOS-aarch64]') || contains(github.event.pull_request.body, '[native-pkl-cli-macOS-aarch64]')) && github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-macOS-aarch64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-macOS-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-macOS-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-linux-aarch64-snapshot:\n if: contains(github.event.pull_request.body, '[native]') || contains(github.event.pull_request.body, '[native-pkl-cli]') || contains(github.event.pull_request.body, '[native-pkl-cli-linux]') || contains(github.event.pull_request.body, '[native-pkl-cli-linux-aarch64]') || contains(github.event.pull_request.body, '[native-pkl-cli-linux-aarch64]')\n runs-on: ubuntu-24.04-arm\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-linux-aarch64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-linux-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-linux-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-cli-alpine-linux-amd64-snapshot:\n if: contains(github.event.pull_request.body, '[native]') || contains(github.event.pull_request.body, '[native-pkl-cli]') || contains(github.event.pull_request.body, '[native-pkl-cli-linux]') || contains(github.event.pull_request.body, '[native-pkl-cli-linux-amd64]') || contains(github.event.pull_request.body, '[native-pkl-cli-linux-amd64]') || contains(github.event.pull_request.body, '[native-pkl-cli-alpine-linux-amd64]')\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Install musl and zlib\n run: |\n set -e\n mkdir -p ~/staticdeps/\n\n ZLIB_VERSION=\"1.2.13\"\n MUSL_VERSION=\"1.2.5\"\n\n # install zlib\n if [[ ! -f ~/staticdeps/include/zlib.h ]]; then\n # Download zlib tarball and signature\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz\" -o /tmp/zlib.tar.gz\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz.asc\" -o /tmp/zlib.tar.gz.asc\n\n # Import zlib GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 5ED46A6721D365587791E2AA783FCD8E58BCAFBA\n\n # Verify GPG signature\n echo \"Verifying zlib GPG signature...\"\n gpg --verify /tmp/zlib.tar.gz.asc /tmp/zlib.tar.gz\n\n mkdir -p \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n cd \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n # shellcheck disable=SC2002\n cat /tmp/zlib.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"zlib-${ZLIB_VERSION}: configure...\" \n ./configure --static --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"zlib-${ZLIB_VERSION}: make...\" \n make -s -j4\n\n echo \"zlib-${ZLIB_VERSION}: make install...\" \n make -s install\n\n rm -rf /tmp/dep_zlib-${ZLIB_VERSION}\n fi\n\n # install musl\n if [[ ! -f ~/staticdeps/bin/x86_64-linux-musl-gcc ]]; then\n # Download musl tarball and signature\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz\" -o /tmp/musl.tar.gz\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz.asc\" -o /tmp/musl.tar.gz.asc\n\n # Import musl GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 836489290BB6B70F99FFDA0556BCDB593020450F\n\n # Verify GPG signature\n echo \"Verifying musl GPG signature...\"\n gpg --verify /tmp/musl.tar.gz.asc /tmp/musl.tar.gz\n\n mkdir -p \"/tmp/dep_musl-${MUSL_VERSION}\"\n cd \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # shellcheck disable=SC2002\n cat /tmp/musl.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"musl-${MUSL_VERSION}: configure...\" \n ./configure --disable-shared --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"musl-${MUSL_VERSION}: make...\" \n make -s -j4\n\n echo \"musl-${MUSL_VERSION}: make install...\" \n make -s install\n\n rm -rf \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # native-image expects to find an executable at this path.\n ln -s ~/staticdeps/bin/musl-gcc ~/staticdeps/bin/x86_64-linux-musl-gcc\n fi\n\n echo \"${HOME}/staticdeps/bin\" >> \"$GITHUB_PATH\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.musl=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-alpine-linux-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-alpine-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-alpine-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-windows-amd64-snapshot:\n if: contains(github.event.pull_request.body, '[native]') || contains(github.event.pull_request.body, '[native-pkl-cli]') || contains(github.event.pull_request.body, '[native-pkl-cli-windows]') || contains(github.event.pull_request.body, '[native-pkl-cli-windows-amd64]') || contains(github.event.pull_request.body, '[native-pkl-cli-windows-amd64]')\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-windows-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-windows-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-windows-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-macOS-amd64-snapshot:\n if: (contains(github.event.pull_request.body, '[native]') || contains(github.event.pull_request.body, '[native-pkl-doc]') || contains(github.event.pull_request.body, '[native-pkl-doc-macOS]') || contains(github.event.pull_request.body, '[native-pkl-doc-macOS-amd64]') || contains(github.event.pull_request.body, '[native-pkl-doc-macOS-amd64]')) && github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.targetArch=amd64 \"-Dpkl.native--native-compiler-path=${GITHUB_WORKSPACE}/.github/scripts/cc_macos_amd64.sh\" pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-macOS-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-macOS-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-macOS-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-linux-amd64-snapshot:\n if: contains(github.event.pull_request.body, '[native]') || contains(github.event.pull_request.body, '[native-pkl-doc]') || contains(github.event.pull_request.body, '[native-pkl-doc-linux]') || contains(github.event.pull_request.body, '[native-pkl-doc-linux-amd64]') || contains(github.event.pull_request.body, '[native-pkl-doc-linux-amd64]')\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-linux-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-doc-macOS-aarch64-snapshot:\n if: (contains(github.event.pull_request.body, '[native]') || contains(github.event.pull_request.body, '[native-pkl-doc]') || contains(github.event.pull_request.body, '[native-pkl-doc-macOS]') || contains(github.event.pull_request.body, '[native-pkl-doc-macOS-aarch64]') || contains(github.event.pull_request.body, '[native-pkl-doc-macOS-aarch64]')) && github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-macOS-aarch64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-macOS-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-macOS-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-linux-aarch64-snapshot:\n if: contains(github.event.pull_request.body, '[native]') || contains(github.event.pull_request.body, '[native-pkl-doc]') || contains(github.event.pull_request.body, '[native-pkl-doc-linux]') || contains(github.event.pull_request.body, '[native-pkl-doc-linux-aarch64]') || contains(github.event.pull_request.body, '[native-pkl-doc-linux-aarch64]')\n runs-on: ubuntu-24.04-arm\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-linux-aarch64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-linux-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-linux-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-doc-alpine-linux-amd64-snapshot:\n if: contains(github.event.pull_request.body, '[native]') || contains(github.event.pull_request.body, '[native-pkl-doc]') || contains(github.event.pull_request.body, '[native-pkl-doc-linux]') || contains(github.event.pull_request.body, '[native-pkl-doc-linux-amd64]') || contains(github.event.pull_request.body, '[native-pkl-doc-linux-amd64]') || contains(github.event.pull_request.body, '[native-pkl-doc-alpine-linux-amd64]')\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Install musl and zlib\n run: |\n set -e\n mkdir -p ~/staticdeps/\n\n ZLIB_VERSION=\"1.2.13\"\n MUSL_VERSION=\"1.2.5\"\n\n # install zlib\n if [[ ! -f ~/staticdeps/include/zlib.h ]]; then\n # Download zlib tarball and signature\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz\" -o /tmp/zlib.tar.gz\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz.asc\" -o /tmp/zlib.tar.gz.asc\n\n # Import zlib GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 5ED46A6721D365587791E2AA783FCD8E58BCAFBA\n\n # Verify GPG signature\n echo \"Verifying zlib GPG signature...\"\n gpg --verify /tmp/zlib.tar.gz.asc /tmp/zlib.tar.gz\n\n mkdir -p \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n cd \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n # shellcheck disable=SC2002\n cat /tmp/zlib.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"zlib-${ZLIB_VERSION}: configure...\" \n ./configure --static --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"zlib-${ZLIB_VERSION}: make...\" \n make -s -j4\n\n echo \"zlib-${ZLIB_VERSION}: make install...\" \n make -s install\n\n rm -rf /tmp/dep_zlib-${ZLIB_VERSION}\n fi\n\n # install musl\n if [[ ! -f ~/staticdeps/bin/x86_64-linux-musl-gcc ]]; then\n # Download musl tarball and signature\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz\" -o /tmp/musl.tar.gz\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz.asc\" -o /tmp/musl.tar.gz.asc\n\n # Import musl GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 836489290BB6B70F99FFDA0556BCDB593020450F\n\n # Verify GPG signature\n echo \"Verifying musl GPG signature...\"\n gpg --verify /tmp/musl.tar.gz.asc /tmp/musl.tar.gz\n\n mkdir -p \"/tmp/dep_musl-${MUSL_VERSION}\"\n cd \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # shellcheck disable=SC2002\n cat /tmp/musl.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"musl-${MUSL_VERSION}: configure...\" \n ./configure --disable-shared --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"musl-${MUSL_VERSION}: make...\" \n make -s -j4\n\n echo \"musl-${MUSL_VERSION}: make install...\" \n make -s install\n\n rm -rf \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # native-image expects to find an executable at this path.\n ln -s ~/staticdeps/bin/musl-gcc ~/staticdeps/bin/x86_64-linux-musl-gcc\n fi\n\n echo \"${HOME}/staticdeps/bin\" >> \"$GITHUB_PATH\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.musl=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-alpine-linux-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-alpine-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-alpine-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-windows-amd64-snapshot:\n if: contains(github.event.pull_request.body, '[native]') || contains(github.event.pull_request.body, '[native-pkl-doc]') || contains(github.event.pull_request.body, '[native-pkl-doc-windows]') || contains(github.event.pull_request.body, '[native-pkl-doc-windows-amd64]') || contains(github.event.pull_request.body, '[native-pkl-doc-windows-amd64]')\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-windows-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-windows-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n if-no-files-found: ignore\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-windows-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n upload-event-file:\n runs-on: ubuntu-latest\n steps:\n - name: Upload event file\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-event-file\n path: ${{ github.event_path }}\n check-pkl-github-actions:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - name: Setup Pkl\n id: setup-pkl\n env:\n PKL_VERSION: 0.30.0\n PKL_FILENAME: pkl\n PKL_DOWNLOAD_URL: https://github.com/apple/pkl/releases/download/0.30.0/pkl-linux-amd64\n shell: bash\n run: |-\n DIR=\"$(mktemp -d /tmp/pkl-$PKL_VERSION-XXXXXX)\"\n PKL_EXEC=\"$DIR/$PKL_FILENAME\"\n curl -sfL -o $PKL_EXEC \"$PKL_DOWNLOAD_URL\"\n chmod +x $PKL_EXEC\n echo \"$DIR\" >> \"$GITHUB_PATH\"\n echo \"pkl_exec=$PKL_EXEC\" >> \"$GITHUB_OUTPUT\"\n - shell: bash\n run: rm -rf .github/**/[a-z]*.yml\n - shell: bash\n run: pkl eval -m .github/ --project-dir .github/ .github/index.pkl\n - name: check git status\n shell: bash\n run: |-\n if [ -n \"$(git status --porcelain)\" ]; then\n echo \"Running pkl resulted in a diff! You likely need to run 'pkl eval' and commit the changes.\"\n git diff --name-only\n exit 1\n fi\n" }, { "path": ".github/workflows/release-branch.yml", "content": "# Generated from Workflow.pkl. DO NOT EDIT.\nname: Build (release branch)\n'on':\n push:\n branches:\n - release/*\n tags-ignore:\n - '**'\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\npermissions:\n contents: read\njobs:\n gradle-check:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: check\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true check\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-check\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-check\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n gradle-check-windows:\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: check\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true check\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-check-windows\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-check-windows\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n bench:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: bench:jmh\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true bench:jmh\n gradle-compatibility:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: :pkl-gradle:build :pkl-gradle:compatibilityTestReleases\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true :pkl-gradle:build :pkl-gradle:compatibilityTestReleases\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-compatibility\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-compatibility\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n java-executables-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - name: gradle build java executables\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:build pkl-cli:build pkl-codegen-java:build pkl-codegen-kotlin:build\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-java\n path: '*/build/executable/**/*'\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-java-executables-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-java-executables-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-macOS-amd64-snapshot:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.targetArch=amd64 \"-Dpkl.native--native-compiler-path=${GITHUB_WORKSPACE}/.github/scripts/cc_macos_amd64.sh\" pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-macOS-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-macOS-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-macOS-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-linux-amd64-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-linux-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-cli-macOS-aarch64-snapshot:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-macOS-aarch64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-macOS-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-macOS-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-linux-aarch64-snapshot:\n runs-on: ubuntu-24.04-arm\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-linux-aarch64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-linux-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-linux-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-cli-alpine-linux-amd64-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Install musl and zlib\n run: |\n set -e\n mkdir -p ~/staticdeps/\n\n ZLIB_VERSION=\"1.2.13\"\n MUSL_VERSION=\"1.2.5\"\n\n # install zlib\n if [[ ! -f ~/staticdeps/include/zlib.h ]]; then\n # Download zlib tarball and signature\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz\" -o /tmp/zlib.tar.gz\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz.asc\" -o /tmp/zlib.tar.gz.asc\n\n # Import zlib GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 5ED46A6721D365587791E2AA783FCD8E58BCAFBA\n\n # Verify GPG signature\n echo \"Verifying zlib GPG signature...\"\n gpg --verify /tmp/zlib.tar.gz.asc /tmp/zlib.tar.gz\n\n mkdir -p \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n cd \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n # shellcheck disable=SC2002\n cat /tmp/zlib.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"zlib-${ZLIB_VERSION}: configure...\" \n ./configure --static --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"zlib-${ZLIB_VERSION}: make...\" \n make -s -j4\n\n echo \"zlib-${ZLIB_VERSION}: make install...\" \n make -s install\n\n rm -rf /tmp/dep_zlib-${ZLIB_VERSION}\n fi\n\n # install musl\n if [[ ! -f ~/staticdeps/bin/x86_64-linux-musl-gcc ]]; then\n # Download musl tarball and signature\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz\" -o /tmp/musl.tar.gz\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz.asc\" -o /tmp/musl.tar.gz.asc\n\n # Import musl GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 836489290BB6B70F99FFDA0556BCDB593020450F\n\n # Verify GPG signature\n echo \"Verifying musl GPG signature...\"\n gpg --verify /tmp/musl.tar.gz.asc /tmp/musl.tar.gz\n\n mkdir -p \"/tmp/dep_musl-${MUSL_VERSION}\"\n cd \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # shellcheck disable=SC2002\n cat /tmp/musl.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"musl-${MUSL_VERSION}: configure...\" \n ./configure --disable-shared --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"musl-${MUSL_VERSION}: make...\" \n make -s -j4\n\n echo \"musl-${MUSL_VERSION}: make install...\" \n make -s install\n\n rm -rf \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # native-image expects to find an executable at this path.\n ln -s ~/staticdeps/bin/musl-gcc ~/staticdeps/bin/x86_64-linux-musl-gcc\n fi\n\n echo \"${HOME}/staticdeps/bin\" >> \"$GITHUB_PATH\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.musl=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-alpine-linux-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-alpine-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-alpine-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-windows-amd64-snapshot:\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-windows-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-windows-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-windows-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-macOS-amd64-snapshot:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.targetArch=amd64 \"-Dpkl.native--native-compiler-path=${GITHUB_WORKSPACE}/.github/scripts/cc_macos_amd64.sh\" pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-macOS-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-macOS-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-macOS-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-linux-amd64-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-linux-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-doc-macOS-aarch64-snapshot:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-macOS-aarch64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-macOS-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-macOS-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-linux-aarch64-snapshot:\n runs-on: ubuntu-24.04-arm\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-linux-aarch64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-linux-aarch64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-linux-aarch64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-doc-alpine-linux-amd64-snapshot:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Install musl and zlib\n run: |\n set -e\n mkdir -p ~/staticdeps/\n\n ZLIB_VERSION=\"1.2.13\"\n MUSL_VERSION=\"1.2.5\"\n\n # install zlib\n if [[ ! -f ~/staticdeps/include/zlib.h ]]; then\n # Download zlib tarball and signature\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz\" -o /tmp/zlib.tar.gz\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz.asc\" -o /tmp/zlib.tar.gz.asc\n\n # Import zlib GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 5ED46A6721D365587791E2AA783FCD8E58BCAFBA\n\n # Verify GPG signature\n echo \"Verifying zlib GPG signature...\"\n gpg --verify /tmp/zlib.tar.gz.asc /tmp/zlib.tar.gz\n\n mkdir -p \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n cd \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n # shellcheck disable=SC2002\n cat /tmp/zlib.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"zlib-${ZLIB_VERSION}: configure...\" \n ./configure --static --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"zlib-${ZLIB_VERSION}: make...\" \n make -s -j4\n\n echo \"zlib-${ZLIB_VERSION}: make install...\" \n make -s install\n\n rm -rf /tmp/dep_zlib-${ZLIB_VERSION}\n fi\n\n # install musl\n if [[ ! -f ~/staticdeps/bin/x86_64-linux-musl-gcc ]]; then\n # Download musl tarball and signature\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz\" -o /tmp/musl.tar.gz\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz.asc\" -o /tmp/musl.tar.gz.asc\n\n # Import musl GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 836489290BB6B70F99FFDA0556BCDB593020450F\n\n # Verify GPG signature\n echo \"Verifying musl GPG signature...\"\n gpg --verify /tmp/musl.tar.gz.asc /tmp/musl.tar.gz\n\n mkdir -p \"/tmp/dep_musl-${MUSL_VERSION}\"\n cd \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # shellcheck disable=SC2002\n cat /tmp/musl.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"musl-${MUSL_VERSION}: configure...\" \n ./configure --disable-shared --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"musl-${MUSL_VERSION}: make...\" \n make -s -j4\n\n echo \"musl-${MUSL_VERSION}: make install...\" \n make -s install\n\n rm -rf \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # native-image expects to find an executable at this path.\n ln -s ~/staticdeps/bin/musl-gcc ~/staticdeps/bin/x86_64-linux-musl-gcc\n fi\n\n echo \"${HOME}/staticdeps/bin\" >> \"$GITHUB_PATH\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -Dpkl.musl=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-alpine-linux-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-alpine-linux-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-alpine-linux-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-windows-amd64-snapshot:\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-windows-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-windows-amd64-snapshot\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-windows-amd64-snapshot\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n publish-test-results:\n if: '!cancelled()'\n needs:\n - gradle-check\n - gradle-check-windows\n - gradle-compatibility\n - java-executables-snapshot\n - pkl-cli-macOS-amd64-snapshot\n - pkl-cli-linux-amd64-snapshot\n - pkl-cli-macOS-aarch64-snapshot\n - pkl-cli-linux-aarch64-snapshot\n - pkl-cli-alpine-linux-amd64-snapshot\n - pkl-cli-windows-amd64-snapshot\n - pkl-doc-macOS-amd64-snapshot\n - pkl-doc-linux-amd64-snapshot\n - pkl-doc-macOS-aarch64-snapshot\n - pkl-doc-linux-aarch64-snapshot\n - pkl-doc-alpine-linux-amd64-snapshot\n - pkl-doc-windows-amd64-snapshot\n permissions:\n checks: write\n runs-on: ubuntu-latest\n steps:\n - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6\n with:\n pattern: test-results-xml-*\n - name: Publish test results\n if: '!cancelled()'\n uses: EnricoMi/publish-unit-test-result-action@c950f6fb443cb5af20a377fd0dfaa78838901040 # v2\n with:\n comment_mode: 'off'\n files: test-results-xml-*/**/*.xml\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-publish-test-results\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n trigger-downstream-builds:\n if: github.repository_owner == 'apple'\n needs:\n - gradle-check\n - gradle-check-windows\n - bench\n - gradle-compatibility\n - java-executables-snapshot\n - pkl-cli-macOS-amd64-snapshot\n - pkl-cli-linux-amd64-snapshot\n - pkl-cli-macOS-aarch64-snapshot\n - pkl-cli-linux-aarch64-snapshot\n - pkl-cli-alpine-linux-amd64-snapshot\n - pkl-cli-windows-amd64-snapshot\n - pkl-doc-macOS-amd64-snapshot\n - pkl-doc-linux-amd64-snapshot\n - pkl-doc-macOS-aarch64-snapshot\n - pkl-doc-linux-aarch64-snapshot\n - pkl-doc-alpine-linux-amd64-snapshot\n - pkl-doc-windows-amd64-snapshot\n - publish-test-results\n runs-on: ubuntu-latest\n steps:\n - name: Create app token\n id: app-token\n uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2\n with:\n app-id: ${{ secrets.PKL_CI_CLIENT_ID }}\n private-key: ${{ secrets.PKL_CI }}\n owner: ${{ github.repository_owner }}\n - name: Trigger pkl-lang.org build\n env:\n GH_TOKEN: ${{ steps.app-token.outputs.token }}\n SOURCE_RUN: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\n run: |-\n gh workflow run \\\n --repo apple/pkl-lang.org \\\n --ref main \\\n --field source_run=\"${SOURCE_RUN}\" \\\n main.yml\n" }, { "path": ".github/workflows/release.yml", "content": "# Generated from Workflow.pkl. DO NOT EDIT.\nname: Release\n'on':\n push:\n branches-ignore:\n - '**'\n tags:\n - '**'\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: false\npermissions:\n contents: read\njobs:\n gradle-check:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: check\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true check\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-check\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-check\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n gradle-check-windows:\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: check\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true check\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-check-windows\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-check-windows\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n bench:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: bench:jmh\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true bench:jmh\n gradle-compatibility:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: :pkl-gradle:build :pkl-gradle:compatibilityTestReleases\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true :pkl-gradle:build :pkl-gradle:compatibilityTestReleases\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-gradle-compatibility\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-gradle-compatibility\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n java-executables-release:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n fetch-depth: 0\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - name: gradle build java executables\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true pkl-doc:build pkl-cli:build pkl-codegen-java:build pkl-codegen-kotlin:build\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-java\n path: '*/build/executable/**/*'\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-java-executables-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-java-executables-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-macOS-amd64-release:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true -Dpkl.targetArch=amd64 \"-Dpkl.native--native-compiler-path=${GITHUB_WORKSPACE}/.github/scripts/cc_macos_amd64.sh\" pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-macOS-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-macOS-amd64-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-macOS-amd64-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-linux-amd64-release:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-linux-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-linux-amd64-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-linux-amd64-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-cli-macOS-aarch64-release:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-macOS-aarch64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-macOS-aarch64-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-macOS-aarch64-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-linux-aarch64-release:\n runs-on: ubuntu-24.04-arm\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-linux-aarch64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-linux-aarch64-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-linux-aarch64-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-cli-alpine-linux-amd64-release:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Install musl and zlib\n run: |\n set -e\n mkdir -p ~/staticdeps/\n\n ZLIB_VERSION=\"1.2.13\"\n MUSL_VERSION=\"1.2.5\"\n\n # install zlib\n if [[ ! -f ~/staticdeps/include/zlib.h ]]; then\n # Download zlib tarball and signature\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz\" -o /tmp/zlib.tar.gz\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz.asc\" -o /tmp/zlib.tar.gz.asc\n\n # Import zlib GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 5ED46A6721D365587791E2AA783FCD8E58BCAFBA\n\n # Verify GPG signature\n echo \"Verifying zlib GPG signature...\"\n gpg --verify /tmp/zlib.tar.gz.asc /tmp/zlib.tar.gz\n\n mkdir -p \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n cd \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n # shellcheck disable=SC2002\n cat /tmp/zlib.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"zlib-${ZLIB_VERSION}: configure...\" \n ./configure --static --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"zlib-${ZLIB_VERSION}: make...\" \n make -s -j4\n\n echo \"zlib-${ZLIB_VERSION}: make install...\" \n make -s install\n\n rm -rf /tmp/dep_zlib-${ZLIB_VERSION}\n fi\n\n # install musl\n if [[ ! -f ~/staticdeps/bin/x86_64-linux-musl-gcc ]]; then\n # Download musl tarball and signature\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz\" -o /tmp/musl.tar.gz\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz.asc\" -o /tmp/musl.tar.gz.asc\n\n # Import musl GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 836489290BB6B70F99FFDA0556BCDB593020450F\n\n # Verify GPG signature\n echo \"Verifying musl GPG signature...\"\n gpg --verify /tmp/musl.tar.gz.asc /tmp/musl.tar.gz\n\n mkdir -p \"/tmp/dep_musl-${MUSL_VERSION}\"\n cd \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # shellcheck disable=SC2002\n cat /tmp/musl.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"musl-${MUSL_VERSION}: configure...\" \n ./configure --disable-shared --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"musl-${MUSL_VERSION}: make...\" \n make -s -j4\n\n echo \"musl-${MUSL_VERSION}: make install...\" \n make -s install\n\n rm -rf \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # native-image expects to find an executable at this path.\n ln -s ~/staticdeps/bin/musl-gcc ~/staticdeps/bin/x86_64-linux-musl-gcc\n fi\n\n echo \"${HOME}/staticdeps/bin\" >> \"$GITHUB_PATH\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true -Dpkl.musl=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-alpine-linux-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-alpine-linux-amd64-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-alpine-linux-amd64-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-cli-windows-amd64-release:\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true pkl-cli:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-cli-windows-amd64\n path: pkl-cli*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-cli-windows-amd64-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-cli-windows-amd64-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-macOS-amd64-release:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true -Dpkl.targetArch=amd64 \"-Dpkl.native--native-compiler-path=${GITHUB_WORKSPACE}/.github/scripts/cc_macos_amd64.sh\" pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-macOS-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-macOS-amd64-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-macOS-amd64-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-linux-amd64-release:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-linux-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-linux-amd64-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-linux-amd64-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-doc-macOS-aarch64-release:\n if: github.repository_owner == 'apple'\n runs-on:\n - self-hosted\n - macos\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-macOS-aarch64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-macOS-aarch64-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-macOS-aarch64-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-linux-aarch64-release:\n runs-on: ubuntu-24.04-arm\n env:\n LANG: en_US.UTF-8\n steps:\n - name: Install deps\n run: dnf install -y git binutils gcc glibc-devel zlib-devel libstdc++-static glibc-langpack-en\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: aarch64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Fix git ownership\n run: git status || git config --system --add safe.directory \"$GITHUB_WORKSPACE\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-linux-aarch64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-linux-aarch64-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-linux-aarch64-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n container:\n image: redhat/ubi8:8.10\n pkl-doc-alpine-linux-amd64-release:\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: Install musl and zlib\n run: |\n set -e\n mkdir -p ~/staticdeps/\n\n ZLIB_VERSION=\"1.2.13\"\n MUSL_VERSION=\"1.2.5\"\n\n # install zlib\n if [[ ! -f ~/staticdeps/include/zlib.h ]]; then\n # Download zlib tarball and signature\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz\" -o /tmp/zlib.tar.gz\n curl -Lf \"https://github.com/madler/zlib/releases/download/v${ZLIB_VERSION}/zlib-${ZLIB_VERSION}.tar.gz.asc\" -o /tmp/zlib.tar.gz.asc\n\n # Import zlib GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 5ED46A6721D365587791E2AA783FCD8E58BCAFBA\n\n # Verify GPG signature\n echo \"Verifying zlib GPG signature...\"\n gpg --verify /tmp/zlib.tar.gz.asc /tmp/zlib.tar.gz\n\n mkdir -p \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n cd \"/tmp/dep_zlib-${ZLIB_VERSION}\"\n # shellcheck disable=SC2002\n cat /tmp/zlib.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"zlib-${ZLIB_VERSION}: configure...\" \n ./configure --static --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"zlib-${ZLIB_VERSION}: make...\" \n make -s -j4\n\n echo \"zlib-${ZLIB_VERSION}: make install...\" \n make -s install\n\n rm -rf /tmp/dep_zlib-${ZLIB_VERSION}\n fi\n\n # install musl\n if [[ ! -f ~/staticdeps/bin/x86_64-linux-musl-gcc ]]; then\n # Download musl tarball and signature\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz\" -o /tmp/musl.tar.gz\n curl -Lf \"https://musl.libc.org/releases/musl-${MUSL_VERSION}.tar.gz.asc\" -o /tmp/musl.tar.gz.asc\n\n # Import musl GPG key\n gpg --batch --keyserver keyserver.ubuntu.com --recv-keys 836489290BB6B70F99FFDA0556BCDB593020450F\n\n # Verify GPG signature\n echo \"Verifying musl GPG signature...\"\n gpg --verify /tmp/musl.tar.gz.asc /tmp/musl.tar.gz\n\n mkdir -p \"/tmp/dep_musl-${MUSL_VERSION}\"\n cd \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # shellcheck disable=SC2002\n cat /tmp/musl.tar.gz | tar --strip-components=1 -xzC .\n\n echo \"musl-${MUSL_VERSION}: configure...\" \n ./configure --disable-shared --prefix=\"$HOME\"/staticdeps > /dev/null\n\n echo \"musl-${MUSL_VERSION}: make...\" \n make -s -j4\n\n echo \"musl-${MUSL_VERSION}: make install...\" \n make -s install\n\n rm -rf \"/tmp/dep_musl-${MUSL_VERSION}\"\n\n # native-image expects to find an executable at this path.\n ln -s ~/staticdeps/bin/musl-gcc ~/staticdeps/bin/x86_64-linux-musl-gcc\n fi\n\n echo \"${HOME}/staticdeps/bin\" >> \"$GITHUB_PATH\"\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true -Dpkl.musl=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-alpine-linux-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-alpine-linux-amd64-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-alpine-linux-amd64-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n pkl-doc-windows-amd64-release:\n runs-on: windows-latest\n env:\n LANG: en_US.UTF-8\n JAVA_HOME: /jdk\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - name: gradle buildNative\n shell: bash\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true pkl-doc:buildNative\n - name: Upload executable artifacts\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: executable-pkl-doc-windows-amd64\n path: pkl-doc*/build/executable/**/*\n - name: Upload Test Result XML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-xml-pkl-doc-windows-amd64-release\n path: '**/build/test-results/**/*.xml'\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-pkl-doc-windows-amd64-release\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n deploy-release:\n needs:\n - gradle-check\n - gradle-check-windows\n - bench\n - gradle-compatibility\n - java-executables-release\n - pkl-cli-macOS-amd64-release\n - pkl-cli-linux-amd64-release\n - pkl-cli-macOS-aarch64-release\n - pkl-cli-linux-aarch64-release\n - pkl-cli-alpine-linux-amd64-release\n - pkl-cli-windows-amd64-release\n - pkl-doc-macOS-amd64-release\n - pkl-doc-linux-amd64-release\n - pkl-doc-macOS-aarch64-release\n - pkl-doc-linux-aarch64-release\n - pkl-doc-alpine-linux-amd64-release\n - pkl-doc-windows-amd64-release\n runs-on: ubuntu-latest\n env:\n LANG: en_US.UTF-8\n environment: maven-release\n steps:\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5\n with:\n java-version: '21'\n distribution: temurin\n architecture: x64\n - uses: gradle/actions/setup-gradle@0723195856401067f7a2779048b490ace7a47d7c # v5\n with: {}\n - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6\n with:\n persist-credentials: false\n - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6\n with:\n pattern: executable-**\n merge-multiple: true\n - env:\n ORG_GRADLE_PROJECT_signingKeyId: ${{ secrets.ORG_GRADLE_PROJECT_SIGNINGKEYID }}\n ORG_GRADLE_PROJECT_signingKey: ${{ secrets.ORG_GRADLE_PROJECT_SIGNINGKEY }}\n ORG_GRADLE_PROJECT_signingPassword: ${{ secrets.ORG_GRADLE_PROJECT_SIGNINGPASSWORD }}\n ORG_GRADLE_PROJECT_sonatypePassword: ${{ secrets.ORG_GRADLE_PROJECT_SONATYPEPASSWORD }}\n ORG_GRADLE_PROJECT_sonatypeUsername: ${{ secrets.ORG_GRADLE_PROJECT_SONATYPEUSERNAME }}\n run: ./gradlew --info --stacktrace --no-daemon -DpklMultiJdkTesting=true -DreleaseBuild=true publishToSonatype closeAndReleaseSonatypeStagingRepository\n github-release:\n needs: deploy-release\n permissions:\n contents: write\n runs-on: ubuntu-latest\n steps:\n - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6\n with:\n pattern: executable-**\n merge-multiple: true\n - name: Publish release on GitHub\n env:\n GH_TOKEN: ${{ github.token }}\n TAG_NAME: ${{ github.ref_name }}\n GIT_SHA: ${{ github.sha }}\n GH_REPO: ${{ github.repository }}\n run: |-\n # exclude build_artifacts.txt from publish\n rm -f */build/executable/*.build_artifacts.txt\n find */build/executable/* -type d | xargs rm -rf\n gh release create ${TAG_NAME} \\\n --title \"${TAG_NAME}\" \\\n --target \"${GIT_SHA}\" \\\n --verify-tag \\\n --notes \"Release notes: https://pkl-lang.org/main/current/release-notes/changelog.html#release-${TAG_NAME}\" \\\n */build/executable/*\n publish-test-results:\n if: '!cancelled()'\n needs:\n - gradle-check\n - gradle-check-windows\n - gradle-compatibility\n - java-executables-release\n - pkl-cli-macOS-amd64-release\n - pkl-cli-linux-amd64-release\n - pkl-cli-macOS-aarch64-release\n - pkl-cli-linux-aarch64-release\n - pkl-cli-alpine-linux-amd64-release\n - pkl-cli-windows-amd64-release\n - pkl-doc-macOS-amd64-release\n - pkl-doc-linux-amd64-release\n - pkl-doc-macOS-aarch64-release\n - pkl-doc-linux-aarch64-release\n - pkl-doc-alpine-linux-amd64-release\n - pkl-doc-windows-amd64-release\n permissions:\n checks: write\n runs-on: ubuntu-latest\n steps:\n - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6\n with:\n pattern: test-results-xml-*\n - name: Publish test results\n if: '!cancelled()'\n uses: EnricoMi/publish-unit-test-result-action@c950f6fb443cb5af20a377fd0dfaa78838901040 # v2\n with:\n comment_mode: 'off'\n files: test-results-xml-*/**/*.xml\n - name: Upload Test Result HTML\n if: '!cancelled()'\n uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5\n with:\n name: test-results-html-publish-test-results\n path: '**/build/reports/tests/**/*'\n if-no-files-found: ignore\n trigger-downstream-builds:\n if: github.repository_owner == 'apple'\n needs:\n - gradle-check\n - gradle-check-windows\n - bench\n - gradle-compatibility\n - java-executables-release\n - pkl-cli-macOS-amd64-release\n - pkl-cli-linux-amd64-release\n - pkl-cli-macOS-aarch64-release\n - pkl-cli-linux-aarch64-release\n - pkl-cli-alpine-linux-amd64-release\n - pkl-cli-windows-amd64-release\n - pkl-doc-macOS-amd64-release\n - pkl-doc-linux-amd64-release\n - pkl-doc-macOS-aarch64-release\n - pkl-doc-linux-aarch64-release\n - pkl-doc-alpine-linux-amd64-release\n - pkl-doc-windows-amd64-release\n - deploy-release\n - github-release\n - publish-test-results\n runs-on: ubuntu-latest\n steps:\n - name: Create app token\n id: app-token\n uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2\n with:\n app-id: ${{ secrets.PKL_CI_CLIENT_ID }}\n private-key: ${{ secrets.PKL_CI }}\n owner: ${{ github.repository_owner }}\n - name: Trigger pkl-lang.org build\n env:\n GH_TOKEN: ${{ steps.app-token.outputs.token }}\n SOURCE_RUN: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\n run: |-\n gh workflow run \\\n --repo apple/pkl-lang.org \\\n --ref main \\\n --field source_run=\"${SOURCE_RUN}\" \\\n main.yml\n" }, { "path": ".github/workflows/test_report.yml", "content": "# Generated from Workflow.pkl. DO NOT EDIT.\nname: PR Test Reports\n'on':\n workflow_run:\n types:\n - completed\n workflows:\n - Pull Request\npermissions:\n contents: read\njobs:\n test-results:\n name: Test Results\n if: github.event.workflow_run.conclusion == 'success' || github.event.workflow_run.conclusion == 'failure'\n permissions:\n actions: read\n checks: write\n runs-on: ubuntu-latest\n steps:\n - name: Download artifacts\n uses: dawidd6/action-download-artifact@ac66b43f0e6a346234dd65d4d0c8fbb31cb316e5 # v11\n with:\n path: artifacts\n name: test-results-.*\n name_is_regexp: true\n run_id: ${{ github.event.workflow_run.id }}\n - name: Publish test results\n uses: EnricoMi/publish-unit-test-result-action@c950f6fb443cb5af20a377fd0dfaa78838901040 # v2\n with:\n commit: ${{ github.event.workflow_run.head_sha }}\n comment_mode: 'off'\n files: artifacts/**/*.xml\n event_file: artifacts/test-results-event-file/event.json\n event_name: ${{ github.event.workflow_run.event }}\n" }, { "path": ".gitignore", "content": "# macOS\n.DS_STORE\n\n# Gradle\n.gradle/\nbuild/\ngenerated/\ntestgenerated/\n\n# IntelliJ\n.idea/\n!.idea/icon.svg\n!.idea/codestyles/\n!.idea/inspectionProfiles/\n!.idea/runConfigurations/\n!.idea/scopes/\n!.idea/vcs.xml\n.intellijPlatform/\n\n.vscode/\n\n.pkl-lsp/\n\n.kotlin/\n" }, { "path": ".idea/vcs.xml", "content": "\n\n \n \n \n" }, { "path": ".java-version", "content": "21\n" }, { "path": ".mailmap", "content": "Jen Basch <421772+HT154@users.noreply.github.com>\nJen Basch \n" }, { "path": "CODE_OF_CONDUCT.md", "content": "## Code of Conduct\n\n### Our Pledge\n\nIn the interest of fostering an open and welcoming environment, we as\ncontributors and maintainers pledge to making participation in our\nproject and our community a harassment-free experience for everyone,\nregardless of age, body size, disability, ethnicity, sex\ncharacteristics, gender identity and expression, level of experience,\neducation, socio-economic status, nationality, personal appearance,\nrace, religion, or sexual identity and orientation.\n\n### Our Standards\n\nExamples of behavior that contributes to creating a positive environment\ninclude:\n\n* Using welcoming and inclusive language\n* Being respectful of differing viewpoints and experiences\n* Gracefully accepting constructive criticism\n* Focusing on what is best for the community\n* Showing empathy towards other community members\n\nExamples of unacceptable behavior by participants include:\n\n* The use of sexualized language or imagery and unwelcome sexual\nattention or advances\n* Trolling, insulting/derogatory comments, and personal or political\nattacks\n* Public or private harassment\n* Publishing others’ private information, such as a physical or\nelectronic address, without explicit permission\n* Other conduct which could reasonably be considered inappropriate in a\nprofessional setting\n\n### Our Responsibilities\n\nProject maintainers are responsible for clarifying the standards of\nacceptable behavior and are expected to take appropriate and fair\ncorrective action in response to any instances of unacceptable behavior.\n\nProject maintainers have the right and responsibility to remove, edit,\nor reject comments, commits, code, wiki edits, issues, and other\ncontributions that are not aligned to this Code of Conduct, or to ban\ntemporarily or permanently any contributor for other behaviors that they\ndeem inappropriate, threatening, offensive, or harmful.\n\n### Scope\n\nThis Code of Conduct applies within all project spaces, and it also\napplies when an individual is representing the project or its community\nin public spaces. Examples of representing a project or community\ninclude using an official project e-mail address, posting via an\nofficial social media account, or acting as an appointed representative\nat an online or offline event. Representation of a project may be\nfurther defined and clarified by project maintainers.\n\n### Enforcement\n\nInstances of abusive, harassing, or otherwise unacceptable behavior may\nbe reported by contacting the open source team at\nopensource-conduct@group.apple.com. All complaints will be reviewed and\ninvestigated and will result in a response that is deemed necessary and\nappropriate to the circumstances. The project team is obligated to\nmaintain confidentiality with regard to the reporter of an incident.\nFurther details of specific enforcement policies may be posted\nseparately.\n\nProject maintainers who do not follow or enforce the Code of Conduct in\ngood faith may face temporary or permanent repercussions as determined\nby other members of the project’s leadership.\n\n### Attribution\n\nThis Code of Conduct is adapted from the\n[Contributor Covenant](https://www.contributor-covenant.org), version 1.4, \navailable at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html\n" }, { "path": "CONTRIBUTING.adoc", "content": ":uri-github-discussion: https://github.com/apple/pkl/discussions\n:uri-github-issue-pkl: https://github.com/apple/pkl/issues/new\n:uri-seven-rules: https://cbea.ms/git-commit/#seven-rules\n\n= Pkl Contributor's Guide\n\nWelcome to the Pkl community, and thank you for contributing!\nThis guide explains how to get involved.\n\n* <>\n* <>\n* <>\n\n== Licensing\n\nPkl is released under the Apache 2.0 license.\nThis is why we require that, by submitting a pull request, you acknowledge that you have the right to license your contribution to Apple and the community, and agree that your contribution is licensed under the Apache 2.0 license.\n\n== Issue Tracking\n\nTo file a bug or feature request, use {uri-github-issue-pkl}[GitHub].\nBe sure to include the following information:\n\n* Context\n** What are/were you trying to achieve?\n** What's the impact of this bug/feature?\n\nFor bug reports, additionally include the following information:\n\n* The output of `pkl --version`.\n* The complete error message.\n* The simplest possible steps to reproduce.\n\n== Pull Requests\n\nWhen preparing a pull request, follow this checklist:\n\n* Imitate the conventions of surrounding code.\n* Format code with `./gradlew spotlessApply` (otherwise the build will fail).\n* Verify that both the JVM build (`./gradlew build`) and native build (`./gradlew buildNative`) succeed.\n* Follow the {uri-seven-rules}[seven rules] of great Git commit messages:\n** Separate subject from body with a blank line.\n** Limit the subject line to 50 characters.footnote:not-enforced[This rule is not enforced in the Pkl project.]\n** Capitalize the subject line.\n** Do not end the subject line with a period.\n** Use the imperative mood in the subject line.\n** Wrap the body at 72 characters.footnote:not-enforced[]\n** Use the body to explain what and why vs. how.\n\nIMPORTANT: If you plan to make substantial changes or add new features, \nwe encourage you to first discuss them with the wider Pkl developer community.\nYou can do this by filing a {uri-github-issue-pkl}[GitHub Issue] or by starting\n{uri-github-discussion}[GitHub Discussion].\nThis will save time and increases the chance of your pull request being accepted.\n\n== Maintainers\n\nThe project’s maintainers (those with write access to the upstream repository) are listed in link:MAINTAINERS.adoc[].\n" }, { "path": "DEVELOPMENT.adoc", "content": "= Development\n:uri-gng: https://gng.dsun.org\n:uri-jenv: https://www.jenv.be\n:uri-intellij: https://www.jetbrains.com/idea/download/\n:uri-native-prerequisites-linux: https://www.graalvm.org/latest/getting-started/linux/#prerequisites-for-native-image-on-linux\n:uri-native-prerequisites-windows: https://www.graalvm.org/latest/getting-started/windows/#prerequisites-for-native-image-on-windows\n\n== Setup\n\n. (mandatory) Install a JDK (JDK 21+ required).\n. (recommended) Install {uri-intellij}[IntelliJ IDEA] +\nTo import the project into IntelliJ, go to File->Open and select the project's root directory.\nIf the project is opened but not imported, look for a popup in the lower right corner\nand click its \"Import Gradle Project\" link.\n. (recommended) Install {uri-gng}[gng] +\n_gng_ enables you to run Gradle commands with `gw` (instead of `./gradlew`) from any subdirectory.\n. (recommended) Set up Git ignore-revs +\n`git config blame.ignoreRevsFile .git-blame-ignore-revs`\n. (recommended) Install {uri-jenv}[jenv] and plugins +\n_jenv_ uses specific JDK versions in certain subdirectories. _Pkl_ comes with a `.java-version` file specifying JDK 21. +\nEnable _jenv_ plugins for better handling by `gradle`:\n+\n[source,shell]\n----\njenv enable-plugin gradle\njenv enable-plugin export\n----\n. (optional) If you've named the original apple/pkl git repository something other than `origin`, set env var `PKL_ORIGINAL_REMOTE_NAME` to that name in your `.bashrc`, `.zshrc`, `config.fish` or however you manage your local environment.\n+\nThis will allow spotless to pick the correct starting branch when formatting source code files.\nOtherwise, you might see that _every_ file has its copyright year updated.\n\n=== Additional Linux Setup\n. (optional) To build the native executable (`./gradlew buildNative`),\ninstall {uri-native-prerequisites-linux}[Prerequisites For Native Image on Linux].\n\n=== Additional Windows Setup\n. (optional) Go to `System->For developers` and enable `Developer Mode`.\nOtherwise, some tests may fail due to insufficient file system privileges.\n. (optional) To build the native executable (`./gradlew buildNative`), \ninstall {uri-native-prerequisites-windows}[Prerequisites For Native Image on Windows].\n\n== Common Build Commands\n\n[source,shell]\n----\ngw clean\ngw test # run all tests except native executable tests\ngw spotlessApply # fix code formatting\ngw build # build everything except native executables\ngw pkl-cli:testNative # run native executable tests\ngw pkl-cli:buildNative # build native executable for current platform\n\npkl-cli/build/executable/jpkl # run Java executable\npkl-cli/build/executable/pkl-macos-aarch64 # run Mac executable\npkl-cli/build/executable/pkl-macos-amd64 # run Intel Mac executable\npkl-cli/build/executable/pkl-linux-amd64 # run Linux executable\npkl-cli/build/executable/pkl-alpine-linux-amd64 # run Alpine Linux executable \npkl-cli/build/executable/pkl-windows-amd64.exe # run Windows executable \n----\n\n== Update Gradle\n\n. Go to https://gradle.org/release-checksums/ and copy the checksum for the new Gradle version\n. Run the following command *twice* (until it prints UP-TO-DATE):\n+\n[source,shell]\n----\ngw wrapper --gradle-version [version] --gradle-distribution-sha256-sum [sha]\n----\n. Commit the updated wrapper files\n\n== Update Dependencies\n\n. (optional) Update _gradle/libs.version.toml_\nbased on version information from https://search.maven.org, https://plugins.gradle.org, and GitHub repos\n. Run `gw updateDependencyLocks`\n. Validate changes with `gw build buildNative`\n. Review and commit the updated dependency lock files\n\n== Code Generation\n\n* Truffle code generation is performed by Truffle's annotation processor, which runs as part of task `:pkl-core:compileJava`\n** Output dir is `generated/truffle/`\n\n== Remote JVM Debugging\n\nTo enable remote JVM debugging when running Gradle tasks (e.g. test), add the flag `-Djvmdebug=true`.\nThis will listen on port 5005.\n\nExample: `./gradlew test -Djvmdebug=true`\n\n== Snippet Test Plugin\n\nThere is an IntelliJ plugin meant for development on the Pkl project itself.\nThis plugin provides a split pane window when viewing snippet tests such as LanguageSnippetTests and FormatterSnippetTests.\n\nTo install:\n\n1. Run `./gradlew pkl-internal-intellij-plugin:buildPlugin`.\n2. Within IntelliJ, run the action \"Install Plugin From Disk...\".\n3. Select the zip file within `pkl-internal-intellij-plugin/build/distributions`.\n\n== Resources\n\nFor automated build setup examples see our https://github.com/apple/pkl/blob/main/.github/[GitHub Actions] jobs like our https://github.com/apple/pkl/blob/main/.github/jobs/BuildNativeJob.pkl[BuildNativeJob.pkl], where we build Pkl automatically.\n\n=== Truffle\n\n* http://ssw.jku.at/Research/Projects/JVM/Truffle.html[Homepage]\n* https://github.com/graalvm/truffle[GitHub]\n* http://lafo.ssw.uni-linz.ac.at/javadoc/truffle/latest/[Javadoc]\n* https://mail.openjdk.org/pipermail/graal-dev/[Mailing List]\n* https://medium.com/@octskyward/graal-truffle-134d8f28fb69#.2db370y2g[Graal & Truffle (Article)]\n* https://comserv.cs.ut.ee/home/files/Pool_ComputerScience_2016.pdf?study=ATILoputoo&reference=6319668E7151D556131810BC3F4A627D7FEF5F3B[Truffle Overview (see chapter 1)]\n* https://gist.github.com/smarr/d1f8f2101b5cc8e14e12[Truffle: Languages and Material]\n* https://github.com/smarr/truffle-notes[Truffle Notes]\n* https://www.graalvm.org/latest/graalvm-as-a-platform/language-implementation-framework/[Truffle Language Implementation Framework]\n\n=== Other Config Languages\n\n* https://github.com/google/jsonnet[Jsonnet]\n* https://github.com/dhall-lang/dhall-lang[Dhall]\n* https://cuelang.org[CUE]\n* https://nickel-lang.org[Nickel]\n* https://kcl-lang.io[KCL]\n* https://github.com/google/skylark[Skylark]\n* https://github.com/typesafehub/config[Typesafe Config]\n* https://www.flabbergast.org[Flabbergast]\n(defunct, http://artefacts.masella.name/2015-srecon-andre_masella.pdf[paper])\n* https://medium.com/@MrJamesFisher/nix-by-example-a0063a1a4c55[Nix by example: The Nix expression language]\n* http://lethalman.blogspot.co.at/2014/07/nix-pill-4-basics-of-language.html[Nix pill 4: the basics of the language]\n* https://docs.puppetlabs.com/puppet/latest/reference/lang_summary.html[Puppet Configuration Language]\n" }, { "path": "LICENSE.txt", "content": "\n Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity authorized by\n the copyright owner that is granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" form shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" form shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship, whether in Source or\n Object form, made available under the License, as indicated by a\n copyright notice that is included in or attached to the work\n (an example is provided in the Appendix below).\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based on (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and Derivative Works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control systems,\n and issue tracking systems that are managed by, or on behalf of, the\n Licensor for the purpose of discussing and improving the Work, but\n excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to reproduce, prepare Derivative Works of,\n publicly display, publicly perform, sublicense, and distribute the\n Work and such Derivative Works in Source or Object form.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" text file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE text file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright statement to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Additional Liability. While redistributing\n the Work or Derivative Works thereof, You may choose to offer,\n and charge a fee for, acceptance of support, warranty, indemnity,\n or other liability obligations and/or rights consistent with this\n License. However, in accepting such obligations, You may act only\n on Your own behalf and on Your sole responsibility, not on behalf\n of any other Contributor, and only if You agree to indemnify,\n defend, and hold each Contributor harmless for any liability\n incurred by, or claims asserted against, such Contributor by reason\n of your accepting any such warranty or additional liability.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in the appropriate\n comment syntax for the file format. We also recommend that a\n file or class name and description of purpose be included on the\n same \"printed page\" as the copyright notice for easier\n identification within third-party archives.\n\n Copyright [yyyy] [name of copyright owner]\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n" }, { "path": "MAINTAINERS.adoc", "content": "= MAINTAINERS\n\nThis page lists all active Maintainers of this repository.\n\nSee link:CONTRIBUTING.adoc[] for general contribution guidelines.\n\n== Maintainers (in alphabetical order)\n\n* https://github.com/bioball[Daniel Chao]\n* https://github.com/stackoverflow[Islon Scherer]\n* https://github.com/HT154[Jen Basch]\n* https://github.com/holzensp[Philip Hölzenspies]\n" }, { "path": "NOTICE.txt", "content": "Copyright © 2024-2025 Apple Inc. and the Pkl project authors\n\n\nPortions of this software were originally based on 'SnakeYAML' developed by Andrey Somov.\n(https://bitbucket.org/asomov/snakeyaml-engine/)\n\nThe Apache License\nCopyright © 2008-2010 Andrey Somov\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\nPortions of this software were originally based on 'jline3' developed by the JLine authors.\n(https://github.com/jline/jline3)\n\nCopyright (c) 2002-2023, the original author(s)\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following\nconditions are met:\n\nRedistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n\nRedistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.\n\nNeither the name of JLine nor the names of its contributors may be used to endorse or promote products derived from this\nsoftware without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT\nLIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED\nOF THE POSSIBILITY OF SUCH DAMAGE.\n\nPortions of this software were originally based on 'minimal-json' developed by EclipseSource.\n(https://github.com/ralfstx/minimal-json)\n\nCopyright (c) 2015, 2016 EclipseSource.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\nPortions of this software were originally based on 'gson' developed by the Google Inc.\n(https://github.com/google/gson)\n\nThe Apache License\nCopyright © 2008 Google Inc\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\nPortions of this software were originally based on 'guava' developed by Google Inc.\n(https://github.com/google/guava)\n\nThe Apache License\nCopyright © 2009 The Guava Authors\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\nPortions of this software were originally based on 'java-string-similarity' developed by Thibault Debatty.\n(https://github.com/tdebatty/java-string-similarity)\n\nCopyright 2015 Thibault Debatty\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\nPortions of this software were originally based on 'xerxes2-j' developed by the Apache Software Foundation.\n(https://github.com/apache/xerces2-j)\n\nThe Apache License\nCopyright © 1999-2018 The Apache Software Foundation\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\nPortions of this software were originally based on 'scroll-into-view-if-needed' developed by Cody Olsen.\n(https://github.com/scroll-into-view/scroll-into-view-if-needed)\n\n\nCopyright (c) 2023 Cody Olsen\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\nThis product ships with third party licenses that may be distributed under a different license.\nThis information is detailed in THIRD-PARTY-NOTICES.txt.\n\nPortions of this software includes code from \"Gradle\" by Gradle, Inc.\n\nCopyright 2015 the original author or authors.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n https://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n" }, { "path": "README.adoc", "content": "= image:.idea/icon.svg[Pkl,30] Pkl \n\n:uri-homepage: https://pkl-lang.org\n:uri-docs: {uri-homepage}/main/current\n:uri-docs-introduction: {uri-docs}/introduction\n:uri-docs-release-notes: {uri-docs}/release-notes\n:uri-docs-language: {uri-docs}/language\n:uri-docs-tools: {uri-docs}/tools\n:uri-github-issue: https://github.com/apple/pkl/issues\n:uri-github-discussions: https://github.com/apple/pkl/discussions\n:uri-pkl-examples: https://pkl-lang.org/main/current/examples.html\n:uri-installation: https://pkl-lang.org/main/current/pkl-cli/index.html#installation\n:uri-lang-reference: https://pkl-lang.org/main/current/language-reference/index.html\n:uri-ci-artifacts: https://s01.oss.sonatype.org/content/groups/public/org/pkl-lang/\n:uri-ci-pipeline: https://github.com/apple/pkl/actions\n\nA configuration as code language with rich validation and tooling.\n\n== Quick Links\n\n* {uri-installation}[Installation]\n* {uri-lang-reference}[Language Reference]\n\n== Documentation\n\n* {uri-homepage}[Home Page]\n** {uri-docs-introduction}[Introduction]\n** {uri-docs-language}[Language]\n** {uri-docs-tools}[Tools]\n** {uri-pkl-examples}[Examples]\n** {uri-docs-release-notes}[Release Notes]\n\n== Community\n\nWe'd love to hear from you!\n\n* Create an {uri-github-issue}[issue]\n* Ask a question on {uri-github-discussions}[GitHub Discussions]\n\n== Development\n\nimage: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\"]\n\n* link:CONTRIBUTING.adoc[] for tips on pull requests and filing issues\n* link:DEVELOPMENT.adoc[] for build instructions\n* {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).\n\n== Pkl GitHub Repositories\n\n[%autowidth]\n|===\n|Name |Description\n\n|`apple/pkl`\n|A configuration as code language with rich validation and tooling.\n\n|https://github.com/apple/pkl-evolution[`apple/pkl-evolution`]\n|Suggested Pkl Improvements, Changes, or Enhancements (SPICEs)\n\n|https://github.com/apple/pkl-go[`apple/pkl-go`]\n|Pkl bindings for the Go programming language\n\n|https://github.com/apple/pkl-go-examples[`apple/pkl-go-examples`]\n|Examples for using Pkl within Go applications\n\n|https://github.com/apple/highlightjs-pkl[`apple/highlightjs-pkl`]\n|Highlight.js syntax highlighting for Pkl\n\n|https://github.com/apple/pkl-intellij[`apple/pkl-intellij`]\n|JetBrains editor plugins providing Pkl language support\n\n|https://github.com/apple/pkl-jvm-examples[`apple/pkl-jvm-examples`]\n|Examples for using Pkl within JVM applications\n\n|https://github.com/apple/pkl-k8s[`apple/pkl-k8s`]\n|Templates for using Pkl with Kubernetes\n\n|https://github.com/apple/pkl-k8s-examples[`apple/pkl-k8s-examples`]\n|Examples for using Pkl with Kubernetes\n\n|https://github.com/apple/pkl-lang.org[`apple/pkl-lang.org`]\n|The pkl-lang.org website\n\n|https://github.com/apple/pkl-lsp[`apple/pkl-lsp`]\n|Language server for Pkl, implementing the server-side of the Language Server Protocol\n\n|https://github.com/apple/pkl-neovim[`apple/pkl-neovim`]\n|Pkl language support for Neovim\n\n|https://github.com/apple/pkl-package-docs[`apple/pkl-package-docs`]\n|Documentation for Pkl packages\n\n|https://github.com/apple/pkl-pantry[`apple/pkl-pantry`]\n|Shared Pkl packages\n\n|https://github.com/apple/pkl-project-commons[`apple/pkl-project-commons`]\n|Utility libraries for Pkl\n\n|https://github.com/apple/pkl-readers[`apple/pkl-readers`]\n|Shared Pkl https://pkl-lang.org/main/current/language-reference/index.html#external-readers[external reader] tools\n\n|https://github.com/apple/pkl-spring[`apple/pkl-spring`]\n|Spring Boot extension for configuring Boot apps with Pkl\n\n|https://github.com/apple/pkl-swift[`apple/pkl-swift`]\n|Pkl bindings for the Swift programming language\n\n|https://github.com/apple/pkl-swift-examples[`apple/pkl-swift-examples`]\n|Examples for using Pkl within Swift applications\n\n|https://github.com/apple/pkl-vscode[`apple/pkl-vscode`]\n|Pkl language support for VS Code\n\n|https://github.com/apple/pkl.tmbundle[`apple/pkl.tmbundle`]\n|TextMate bundle for Pkl\n\n|https://github.com/apple/tree-sitter-pkl[`apple/tree-sitter-pkl`]\n|Tree-sitter parser for Pkl\n\n|https://github.com/apple/rules_pkl[`apple/rules_pkl`]\n|Bazel build rules for Pkl\n|===\n" }, { "path": "SECURITY.md", "content": "# Security\n\nFor the protection of our community, the Pkl team does not disclose, discuss, or confirm security issues until our investigation is complete and any necessary updates are generally available.\n\n## Reporting a security vulnerability\n\nIf you have discovered a security vulnerability within the Pkl project, please report it to us.\nWe welcome reports from everyone, including security researchers, developers, and users.\n\nSecurity vulnerabilities may be reported on the [Report a vulnerability](https://security.apple.com/submit) form.\nWhen submitting a vulnerability, select \"Apple Devices and Software\" as the affected platform, and \"Open Source\" as the affected area.\n\nFor more information, see https://pkl-lang.org/security.html.\n" }, { "path": "THIRD-PARTY-NOTICES.txt", "content": "Pkl ships with third-party libraries that may be distributed under a different license than\nPkl's own license.\nThese libraries and their licenses are listed below:\n\n1) Clikt (https://github.com/ajalt/clikt)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © 2018 AJ Alt\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n2) JavaPoet (http://github.com/square/javapoet/)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © 2015 Square, Inc.\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n3) KotlinPoet (https://github.com/square/kotlinpoet)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © 2017 Square, Inc.\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n4) GeantyRef (https://github.com/leangen/geantyref)\nManifest license URL: https://www.apache.org/licenses/LICENSE-2.0\n\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © 2017 Kaqqao\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n5) commonmark-java core\nPOM License: The 2-Clause BSD License - https://opensource.org/licenses/BSD-2-Clause\n\nEmbedded license: \n\n **************************************** \n\nCopyright (c) 2015, Atlassian Pty Ltd\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this\n list of conditions and the following disclaimer.\n\n* Redistributions in binary form must reproduce the above copyright notice,\n this list of conditions and the following disclaimer in the documentation\n and/or other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\nOR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n6) commonmark-java extension for tables\nPOM License: The 2-Clause BSD License - https://opensource.org/licenses/BSD-2-Clause\n\nEmbedded license: \n\n **************************************** \n\nCopyright (c) 2015, Atlassian Pty Ltd\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this\n list of conditions and the following disclaimer.\n\n* Redistributions in binary form must reproduce the above copyright notice,\n this list of conditions and the following disclaimer in the documentation\n and/or other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\nOR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n7) jansi (http://fusesource.com/)\nManifest license URL: https://www.apache.org/licenses/LICENSE-2.0\n\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © Fusesource 2023\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n8) Graal Sdk (https://github.com/oracle/graal)\nPOM License: Universal Permissive License, Version 1.0 - http://opensource.org/licenses/UPL\n\n9) Truffle API (http://openjdk.java.net/projects/graal)\nPOM License: Universal Permissive License, Version 1.0 - http://opensource.org/licenses/UPL\n\n10) IntelliJ IDEA Annotations (http://www.jetbrains.org)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © Jetbrains 2023\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n11) kotlin-reflect (https://kotlinlang.org/)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © Wuseal 2018\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n12) kotlin-stdlib (https://kotlinlang.org/)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributor\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n13) kotlin-stdlib-common (https://kotlinlang.org/)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © 2023 Kotlin Team\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n14) kotlin-stdlib-jdk7 (https://kotlinlang.org/)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © 2023 Kotlin Team\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n15) kotlin-stdlib-jdk8 (https://kotlinlang.org/)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © 2023 Kotlin Team\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n16) kotlinx.html (https://github.com/Kotlin/kotlinx.html)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © 2017 Yole\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n17) kotlinx-serialization-core (https://github.com/Kotlin/kotlinx.serialization)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\n2017-2019 JetBrains s.r.o and respective authors and developers\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n18) kotlinx-serialization-json (https://github.com/Kotlin/kotlinx.serialization)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\n2017-2019 JetBrains s.r.o and respective authors and developers\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n19) JLine Reader\nManifest license URL: https://opensource.org/licenses/BSD-3-Clause\n\nPOM License: The 3-Clause BSD License - https://opensource.org/licenses/BSD-3-Clause\n\nCopyright (c) 2002-2023, the original author(s)\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following\nconditions are met:\n\nRedistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n\nRedistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.\n\nNeither the name of JLine nor the names of its contributors may be used to endorse or promote products derived from this\nsoftware without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n20) JLine Terminal\nManifest license URL: https://opensource.org/licenses/BSD-3-Clause\n\nPOM License: The 3-Clause BSD License - https://opensource.org/licenses/BSD-3-Clause\n\nCopyright (c) 2002-2023, the original author(s)\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following\nconditions are met:\n\nRedistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n\nRedistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.\n\nNeither the name of JLine nor the names of its contributors may be used to endorse or promote products derived from this\nsoftware without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n21) JLine JANSI Terminal\nManifest license URL: https://opensource.org/licenses/BSD-3-Clause\n\nPOM License: The 3-Clause BSD License - https://opensource.org/licenses/BSD-3-Clause\n\nCopyright (c) 2002-2023, the original author(s)\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following\nconditions are met:\n\nRedistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n\nRedistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.\n\nNeither the name of JLine nor the names of its contributors may be used to endorse or promote products derived from this\nsoftware without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n22) msgpack-core (https://msgpack.org/)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © 2016 Sadayuki Furuhashi, Muga Nishizawa, Taro L. Saito, Mitsunori Komatsu, Ozawa Tsuyoshi\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. \n\n23) Paguro (https://github.com/GlenKPeterson/Paguro)\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © 2021 Glen K. Peterson\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\nPOM License: Eclipse Public License - v 1.0 - http://www.eclipse.org/legal/epl-v10.html\n\nNOTE: The files in this project that came from Clojure (Persistent...) MUST only be used under the Eclipse 1.0 license.\nAt the user's choice, any other files in this project can be used under Eclipse 1.0 or the Apache 2.0 license.\n\nEclipse Public License - v 1.0\n\nTHE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC LICENSE (\"AGREEMENT\").\nANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.\n\n1. DEFINITIONS\n\n\"Contribution\" means:\n\na) in the case of the initial Contributor, the initial code and documentation distributed under this Agreement, and\n\nb) in the case of each subsequent Contributor:\n\ni) changes to the Program, and\n\nii) additions to the Program;\n\nwhere such changes and/or additions to the Program originate from and are distributed by that particular Contributor. A Contribution 'originates' from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include additions to the Program which: (i) are separate modules of software distributed in conjunction with the Program under their own license agreement, and (ii) are not derivative works of the Program.\n\n\"Contributor\" means any person or entity that distributes the Program.\n\n\"Licensed Patents\" mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.\n\n\"Program\" means the Contributions distributed in accordance with this Agreement.\n\n\"Recipient\" means anyone who receives the Program under this Agreement, including all Contributors.\n\n2. GRANT OF RIGHTS\n\na) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, distribute and sublicense the Contribution of such Contributor, if any, and such derivative works, in source code and object code form.\n\nb) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in source code and object code form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder.\n\nc) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program.\n\nd) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.\n\n3. REQUIREMENTS\n\nA Contributor may choose to distribute the Program in object code form under its own license agreement, provided that:\n\na) it complies with the terms and conditions of this Agreement; and\n\nb) its license agreement:\n\ni) effectively disclaims on behalf of all Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose;\n\nii) effectively excludes on behalf of all Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits;\n\niii) states that any provisions which differ from this Agreement are offered by that Contributor alone and not by any other party; and\n\niv) states that source code for the Program is available from such Contributor, and informs licensees how to obtain it in a reasonable manner on or through a medium customarily used for software exchange.\n\nWhen the Program is made available in source code form:\n\na) it must be made available under this Agreement; and\n\nb) a copy of this Agreement must be included with each copy of the Program.\n\nContributors may not remove or alter any copyright notices contained within the Program.\n\nEach Contributor must identify itself as the originator of its Contribution, if any, in a manner that reasonably allows subsequent Recipients to identify the originator of the Contribution.\n\n4. COMMERCIAL DISTRIBUTION\n\nCommercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor (\"Commercial Contributor\") hereby agrees to defend and indemnify every other Contributor (\"Indemnified Contributor\") against any losses, damages and costs (collectively \"Losses\") arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense.\n\nFor example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages.\n\n5. NO WARRANTY\n\nEXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement , including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.\n\n6. DISCLAIMER OF LIABILITY\n\nEXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.\n\n7. GENERAL\n\nIf any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.\n\nIf Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed.\n\nAll Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive.\n\nEveryone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency the Agreement is copyrighted and may only be modified in the following manner. The Agreement Steward reserves the right to publish new versions (including revisions) of this Agreement from time to time. No one other than the Agreement Steward has the right to modify this Agreement. The Eclipse Foundation is the initial Agreement Steward. The Eclipse Foundation may assign the responsibility to serve as the Agreement Steward to a suitable separate entity. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to distribute the Program (including its Contributions) under the new version. Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved.\n\nThis Agreement is governed by the laws of the State of New York and the intellectual property laws of the United States of America. No party to this Agreement will bring a legal action under this Agreement more than one year after the cause of action arose. Each party waives its rights to a jury trial in any resulting litigation.\n\n24) SnakeYAML Engine (http://www.snakeyaml.org)\nManifest license URL: https://www.apache.org/licenses/LICENSE-2.0\n\nPOM License: Apache License, Version 2.0 - https://www.apache.org/licenses/LICENSE-2.0\n\nThe Apache License\nCopyright © 2008-2010 Andrey Somov\nLicensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License.You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n" }, { "path": "bench/bench.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nplugins {\n pklAllProjects\n pklJavaLibrary\n id(\"me.champeau.jmh\")\n}\n\nval truffle: Configuration by configurations.creating\nval graal: Configuration by configurations.creating\n\ndependencies {\n jmh(projects.pklCore)\n jmh(projects.pklCommonsTest)\n jmh(projects.pklParser)\n truffle(libs.truffleApi)\n graal(libs.graalCompiler)\n}\n\njmh {\n // include = [\"fib_class_java\"]\n // include = [\"fib_class_constrained1\", \"fib_class_constrained2\"]\n jmhVersion.set(libs.versions.jmh)\n // jvmArgsAppend = \"-Dgraal.TruffleCompilationExceptionsAreFatal=true \" +\n // \"-Dgraal.Dump=Truffle,TruffleTree -Dgraal.TraceTruffleCompilation=true \" +\n // \"-Dgraal.TruffleFunctionInlining=false\"\n jvm.set(\"${buildInfo.graalVmAmd64.baseDir}/bin/java\")\n // see:\n // https://docs.oracle.com/en/graalvm/enterprise/20/docs/graalvm-as-a-platform/implement-language/#disable-class-path-separation\n jvmArgs.set(\n listOf(\n // one JVM arg per list element doesn't work, but the following does\n \"-Dgraalvm.locatorDisabled=true --module-path=${truffle.asPath} --upgrade-module-path=${graal.asPath}\"\n )\n )\n includeTests.set(false)\n // threads = Runtime.runtime.availableProcessors() / 2 + 1\n // synchronizeIterations = false\n}\n\ntasks.named(\"jmh\") { dependsOn(\":installGraalVmAmd64\") }\n\n// Prevent this error which occurs when building in IntelliJ:\n// \"Entry org/pkl/core/fib_class_typed.pkl is a duplicate but no duplicate handling strategy has\n// been set.\"\ntasks.processJmhResources { duplicatesStrategy = DuplicatesStrategy.EXCLUDE }\n" }, { "path": "bench/gradle.lockfile", "content": "# This is a Gradle generated file for dependency locking.\n# Manual edits can break the build and are not advised.\n# This file is expected to be part of source control.\ncom.github.ben-manes.caffeine:caffeine:2.9.3=swiftExportClasspathResolvable\ncom.google.errorprone:error_prone_annotations:2.28.0=swiftExportClasspathResolvable\nio.github.java-diff-utils:java-diff-utils:4.12=kotlinInternalAbiValidation\nio.opentelemetry:opentelemetry-api:1.41.0=swiftExportClasspathResolvable\nio.opentelemetry:opentelemetry-context:1.41.0=swiftExportClasspathResolvable\nnet.bytebuddy:byte-buddy:1.17.7=jmh,jmhRuntimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\nnet.sf.jopt-simple:jopt-simple:5.0.4=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath\norg.apache.commons:commons-math3:3.6.1=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath\norg.apiguardian:apiguardian-api:1.1.2=jmhCompileClasspath,jmhImplementationDependenciesMetadata,testCompileClasspath,testImplementationDependenciesMetadata\norg.assertj:assertj-core:3.27.6=jmh,jmhRuntimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.bouncycastle:bcpg-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcpkix-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcprov-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcutil-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.checkerframework:checker-qual:3.43.0=swiftExportClasspathResolvable\norg.graalvm.compiler:compiler:25.0.0=graal\norg.graalvm.polyglot:polyglot:25.0.0=jmh,jmhRuntimeClasspath,truffle\norg.graalvm.sdk:collections:25.0.0=graal,jmh,jmhRuntimeClasspath,truffle\norg.graalvm.sdk:graal-sdk:25.0.0=jmh,jmhRuntimeClasspath\norg.graalvm.sdk:nativeimage:25.0.0=jmh,jmhRuntimeClasspath,truffle\norg.graalvm.sdk:word:25.0.0=graal,jmh,jmhRuntimeClasspath,truffle\norg.graalvm.truffle:truffle-api:25.0.0=jmh,jmhRuntimeClasspath,truffle\norg.graalvm.truffle:truffle-compiler:25.0.0=graal\norg.jetbrains.kotlin:abi-tools-api:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:abi-tools:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-build-tools-api:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-build-tools-impl:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-compiler-runner:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-client:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-klib-commonizer-embeddable:2.2.20=kotlinKlibCommonizerClasspath\norg.jetbrains.kotlin:kotlin-metadata-jvm:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-native-prebuilt:2.0.21=kotlinNativeBundleConfiguration\norg.jetbrains.kotlin:kotlin-reflect:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-script-runtime:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathJmh,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-scripting-common:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathJmh,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathJmh,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-compiler-impl-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathJmh,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-jvm:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathJmh,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-stdlib-jdk7:2.2.20=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib-jdk8:2.2.20=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib:2.2.20=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathJmh,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:swift-export-embeddable:2.2.20=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.8.0=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-bom:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core-jvm:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3=swiftExportClasspathResolvable\norg.jetbrains:annotations:13.0=jmh,jmhCompileClasspath,jmhRuntimeClasspath,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathJmh,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable,testCompileClasspath,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-api:5.14.0=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-engine:5.14.0=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-params:5.14.0=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-commons:1.14.0=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-engine:1.14.0=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath,testRuntimeClasspath\norg.junit.platform:junit-platform-launcher:1.14.0=testRuntimeClasspath\norg.junit:junit-bom:5.14.0=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.msgpack:msgpack-core:0.9.8=jmh,jmhRuntimeClasspath\norg.openjdk.jmh:jmh-core:1.37=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath\norg.openjdk.jmh:jmh-generator-asm:1.37=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath\norg.openjdk.jmh:jmh-generator-bytecode:1.37=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath\norg.openjdk.jmh:jmh-generator-reflection:1.37=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath\norg.opentest4j:opentest4j:1.3.0=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.organicdesign:Paguro:3.10.3=jmh,jmhRuntimeClasspath\norg.ow2.asm:asm:9.0=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath\norg.snakeyaml:snakeyaml-engine:2.10=jmh,jmhRuntimeClasspath\nempty=annotationProcessor,apiDependenciesMetadata,compileClasspath,compileOnlyDependenciesMetadata,implementationDependenciesMetadata,intransitiveDependenciesMetadata,jmhAnnotationProcessor,jmhApiDependenciesMetadata,jmhCompileOnlyDependenciesMetadata,jmhIntransitiveDependenciesMetadata,jmhKotlinScriptDefExtensions,kotlinCompilerPluginClasspath,kotlinNativeCompilerPluginClasspath,kotlinScriptDefExtensions,runtimeClasspath,sourcesJar,testAnnotationProcessor,testApiDependenciesMetadata,testCompileOnlyDependenciesMetadata,testIntransitiveDependenciesMetadata,testKotlinScriptDefExtensions\n" }, { "path": "bench/src/jmh/java/org/pkl/core/Fibonacci.java", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.core;\n\nimport static org.pkl.core.ModuleSource.modulePath;\n\nimport java.util.concurrent.TimeUnit;\nimport org.openjdk.jmh.annotations.*;\n\n@SuppressWarnings(\"unused\")\n@Warmup(iterations = 5, time = 2)\n@Measurement(iterations = 5, time = 2)\n@OutputTimeUnit(TimeUnit.SECONDS)\n@Fork(1)\npublic class Fibonacci {\n @Benchmark\n public long fib_class_java() {\n return new FibJavaImpl().fib(35);\n }\n\n @Benchmark\n public long fib_class() {\n try (var evaluator = Evaluator.preconfigured()) {\n var module = evaluator.evaluate(modulePath(\"org/pkl/core/fib_class.pkl\"));\n return (long) module.getProperties().get(\"result\");\n }\n }\n\n @Benchmark\n public long fib_class_explicitThis() {\n try (var evaluator = Evaluator.preconfigured()) {\n var module = evaluator.evaluate(modulePath(\"org/pkl/core/fib_class_explicitThis.pkl\"));\n return (long) module.getProperties().get(\"result\");\n }\n }\n\n @Benchmark\n public long fib_class_typed() {\n try (var evaluator = Evaluator.preconfigured()) {\n var module = evaluator.evaluate(modulePath(\"org/pkl/core/fib_class_typed.pkl\"));\n return (long) module.getProperties().get(\"result\");\n }\n }\n\n @Benchmark\n public long fib_class_constrained1() {\n try (var evaluator = Evaluator.preconfigured()) {\n var module = evaluator.evaluate(modulePath(\"org/pkl/core/fib_class_constrained1.pkl\"));\n return (long) module.getProperties().get(\"result\");\n }\n }\n\n @Benchmark\n public long fib_class_constrained2() {\n try (var evaluator = Evaluator.preconfigured()) {\n var module = evaluator.evaluate(modulePath(\"org/pkl/core/fib_class_constrained2.pkl\"));\n return (long) module.getProperties().get(\"result\");\n }\n }\n\n @Benchmark\n public long fib_module() {\n try (var evaluator = Evaluator.preconfigured()) {\n var module = evaluator.evaluate(modulePath(\"org/pkl/core/fib_module.pkl\"));\n return (long) module.getProperties().get(\"result\");\n }\n }\n\n @Benchmark\n public long fib_module_explicitThis() {\n try (var evaluator = Evaluator.preconfigured()) {\n var module = evaluator.evaluate(modulePath(\"org/pkl/core/fib_module_explicitThis.pkl\"));\n return (long) module.getProperties().get(\"result\");\n }\n }\n\n @Benchmark\n public long fib_lambda() {\n try (var evaluator = Evaluator.preconfigured()) {\n var module = evaluator.evaluate(modulePath(\"org/pkl/core/fib_lambda.pkl\"));\n return (long) module.getProperties().get(\"result\");\n }\n }\n}\n\n// kept similar to pkl code (class, instance method, long argument)\nclass FibJavaImpl {\n long fib(long n) {\n return n < 2 ? n : fib(n - 1) + fib(n - 2);\n }\n}\n" }, { "path": "bench/src/jmh/java/org/pkl/core/ListSort.java", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.core;\n\nimport java.io.FileWriter;\nimport java.io.IOException;\nimport java.io.UncheckedIOException;\nimport java.util.*;\nimport java.util.concurrent.TimeUnit;\nimport org.openjdk.jmh.annotations.*;\nimport org.openjdk.jmh.util.TempFile;\nimport org.openjdk.jmh.util.TempFileManager;\nimport org.pkl.core.evaluatorSettings.TraceMode;\nimport org.pkl.core.http.HttpClient;\nimport org.pkl.core.module.ModuleKeyFactories;\nimport org.pkl.core.repl.ReplRequest;\nimport org.pkl.core.repl.ReplResponse;\nimport org.pkl.core.repl.ReplServer;\nimport org.pkl.core.resource.ResourceReaders;\nimport org.pkl.core.util.IoUtils;\n\n@Warmup(iterations = 5, time = 2)\n@Measurement(iterations = 5, time = 2)\n@OutputTimeUnit(TimeUnit.SECONDS)\n@Fork(1)\n@SuppressWarnings(\"unused\")\npublic class ListSort {\n private static final ReplServer repl =\n new ReplServer(\n SecurityManagers.defaultManager,\n HttpClient.dummyClient(),\n Loggers.stdErr(),\n List.of(ModuleKeyFactories.standardLibrary),\n List.of(ResourceReaders.file()),\n Map.of(),\n Map.of(),\n null,\n null,\n null,\n IoUtils.getCurrentWorkingDir(),\n StackFrameTransformers.defaultTransformer,\n false,\n TraceMode.COMPACT);\n private static final List list = new ArrayList<>(100000);\n\n static {\n var random = new Random(2786433088656064171L);\n for (var i = 0; i < 100000; i++) {\n list.add(random.nextLong());\n }\n\n TempFile tempFile;\n try {\n tempFile = new TempFileManager().create(\"bench-nums.txt\");\n } catch (IOException e) {\n throw new UncheckedIOException(e);\n }\n try (var fw = new FileWriter(tempFile.getAbsolutePath())) {\n for (var elem : list) {\n fw.append(elem.toString()).append('\\n');\n }\n fw.flush();\n } catch (IOException e) {\n throw new UncheckedIOException(e);\n }\n\n var responses =\n repl.handleRequest(\n new ReplRequest.Eval(\n \"setup\",\n \"import \\\"pkl:test\\\"\\n\"\n + \"random = test.random\\n\"\n + \"nums = read(\\\"file://\"\n + tempFile.getAbsolutePath()\n + \"\\\").text.split(\\\"\\\\n\\\").dropLast(1).map((it) -> it.toInt())\\n\"\n + \"cmp = (x, y) -> if (x < y) -1 else if (x == y) 0 else 1\",\n false,\n false));\n if (!responses.isEmpty()) {\n throw new AssertionError(responses.get(0));\n }\n }\n\n @Benchmark\n public String sortPkl() {\n var response =\n repl.handleRequest(\n // append `.length` to avoid rendering the list\n new ReplRequest.Eval(\"sort\", \"nums.sort().length\", false, false))\n .get(0);\n if (!(response instanceof ReplResponse.EvalSuccess)) {\n throw new AssertionError(response);\n }\n return ((ReplResponse.EvalSuccess) response).getResult();\n }\n\n @Benchmark\n public String sortWithPkl() {\n var response =\n repl.handleRequest(\n // append `.length` to avoid rendering the list\n new ReplRequest.Eval(\"sort\", \"nums.sortWith(cmp).length\", false, false))\n .get(0);\n if (!(response instanceof ReplResponse.EvalSuccess success)) {\n throw new AssertionError(response);\n }\n return success.getResult();\n }\n\n // note that this is an uneven comparison\n // (timsort vs. merge sort, java.util.ArrayList vs. persistent vector\n @Benchmark\n public List sortJava() {\n return sort(list);\n }\n\n private List sort(List self) {\n var array = self.toArray();\n Arrays.sort(array);\n return Arrays.asList(array);\n }\n\n // note that this is an uneven comparison\n // (timsort vs. merge sort, java.util.ArrayList vs. persistent vector\n @Benchmark\n public List sortWithJava() {\n return sortWith(list, Comparator.comparingLong(x -> (long) x));\n }\n\n private List sortWith(List self, Comparator comparator) {\n var array = self.toArray();\n Arrays.sort(array, comparator);\n return Arrays.asList(array);\n }\n}\n" }, { "path": "bench/src/jmh/java/org/pkl/core/parser/ParserBenchmark.java", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.core.parser;\n\nimport java.io.IOException;\nimport java.io.UncheckedIOException;\nimport java.nio.file.Files;\nimport java.util.concurrent.TimeUnit;\nimport org.openjdk.jmh.annotations.*;\nimport org.pkl.commons.test.FileTestUtils;\nimport org.pkl.commons.test.FileTestUtilsKt;\nimport org.pkl.core.Release;\nimport org.pkl.core.util.IoUtils;\nimport org.pkl.parser.Parser;\nimport org.pkl.parser.ParserError;\n\n@SuppressWarnings(\"unused\")\n@Warmup(iterations = 5, time = 2)\n@Measurement(iterations = 5, time = 2)\n@OutputTimeUnit(TimeUnit.SECONDS)\n@Fork(1)\npublic class ParserBenchmark {\n @Benchmark\n public void parseStdlib() {\n for (var stdlibModule : Release.current().standardLibrary().modules()) {\n try {\n var moduleSource =\n IoUtils.readClassPathResourceAsString(\n getClass(), \"/org/pkl/core/stdlib/%s.pkl\".formatted(stdlibModule.substring(4)));\n new Parser().parseModule(moduleSource);\n } catch (IOException e) {\n throw new UncheckedIOException(e);\n }\n }\n }\n\n @Benchmark\n public void parseSnippetTests() {\n var snippetTestDir =\n FileTestUtils.getRootProjectDir()\n .resolve(\"pkl-core/src/test/files/LanguageSnippetTests/input\");\n for (var snippet : FileTestUtilsKt.listFilesRecursively(snippetTestDir)) {\n try {\n var moduleSource = Files.readString(snippet);\n new Parser().parseModule(moduleSource);\n } catch (IOException e) {\n throw new UncheckedIOException(e);\n } catch (ParserError ignore) {\n }\n }\n }\n}\n" }, { "path": "bench/src/jmh/resources/org/pkl/core/fib_class.pkl", "content": "//===----------------------------------------------------------------------===//\n// Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// https://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n//===----------------------------------------------------------------------===//\n\nclass Fibonacci {\n function fib(n) = if (n < 2) n else fib(n - 1) + fib(n - 2)\n}\nresult = new Fibonacci {}.fib(35)\n" }, { "path": "bench/src/jmh/resources/org/pkl/core/fib_class_constrained1.pkl", "content": "//===----------------------------------------------------------------------===//\n// Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// https://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n//===----------------------------------------------------------------------===//\n\nclass Fibonacci {\n function fib(n: Int(this >= 0)): Int(this >= 0) = if (n < 2) n else fib(n - 1) + fib(n - 2)\n}\nresult = new Fibonacci {}.fib(35)\n" }, { "path": "bench/src/jmh/resources/org/pkl/core/fib_class_constrained2.pkl", "content": "//===----------------------------------------------------------------------===//\n// Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// https://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n//===----------------------------------------------------------------------===//\n\nclass Fibonacci {\n function fib(n: Int(isPositive)): Int(isPositive) = if (n < 2) n else fib(n - 1) + fib(n - 2)\n}\nresult = new Fibonacci {}.fib(35)\n" }, { "path": "bench/src/jmh/resources/org/pkl/core/fib_class_explicitThis.pkl", "content": "//===----------------------------------------------------------------------===//\n// Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// https://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n//===----------------------------------------------------------------------===//\n\nclass Fibonacci {\n function fib(n) = if (n < 2) n else this.fib(n - 1) + this.fib(n - 2)\n}\nresult = new Fibonacci {}.fib(35)\n" }, { "path": "bench/src/jmh/resources/org/pkl/core/fib_class_typed.pkl", "content": "//===----------------------------------------------------------------------===//\n// Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// https://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n//===----------------------------------------------------------------------===//\n\nclass Fibonacci {\n function fib(n: Int): Int = if (n < 2) n else fib(n - 1) + fib(n - 2)\n}\nresult = new Fibonacci {}.fib(35)\n" }, { "path": "bench/src/jmh/resources/org/pkl/core/fib_lambda.pkl", "content": "//===----------------------------------------------------------------------===//\n// Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// https://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n//===----------------------------------------------------------------------===//\n\nhidden fib = (n) -> if (n < 2) n else fib.apply(n - 1) + fib.apply(n - 2)\n\nresult = fib.apply(35)" }, { "path": "bench/src/jmh/resources/org/pkl/core/fib_module.pkl", "content": "//===----------------------------------------------------------------------===//\n// Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// https://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n//===----------------------------------------------------------------------===//\n\nfunction fib(n) = if (n < 2) n else fib(n - 1) + fib(n - 2)\nresult = fib(35)" }, { "path": "bench/src/jmh/resources/org/pkl/core/fib_module_explicitThis.pkl", "content": "//===----------------------------------------------------------------------===//\n// Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// https://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n//===----------------------------------------------------------------------===//\n\nfunction fib(n) = if (n < 2) n else this.fib(n - 1) + this.fib(n - 2)\nresult = fib(35)" }, { "path": "build.gradle.kts", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n// https://youtrack.jetbrains.com/issue/KTIJ-19369\nimport org.jetbrains.gradle.ext.ActionDelegationConfig\nimport org.jetbrains.gradle.ext.ActionDelegationConfig.TestRunner.PLATFORM\nimport org.jetbrains.gradle.ext.ProjectSettings\n\nplugins {\n pklAllProjects\n pklGraalVm\n\n alias(libs.plugins.ideaExt)\n alias(libs.plugins.jmh) apply false\n alias(libs.plugins.nexusPublish)\n}\n\nnexusPublishing {\n repositories {\n sonatype {\n nexusUrl.set(uri(\"https://ossrh-staging-api.central.sonatype.com/service/local/\"))\n snapshotRepositoryUrl.set(uri(\"https://central.sonatype.com/repository/maven-snapshots/\"))\n }\n }\n}\n\nidea {\n project {\n this as ExtensionAware\n configure {\n this as ExtensionAware\n configure {\n delegateBuildRunToGradle = true\n testRunner = PLATFORM\n }\n }\n }\n}\n\nval clean by tasks.existing { delete(layout.buildDirectory) }\n\nval printVersion by tasks.registering { doFirst { println(buildInfo.pklVersion) } }\n\nval message =\n \"\"\"\n====\nGradle version : ${gradle.gradleVersion}\nJava version : ${System.getProperty(\"java.version\")}\nisParallel : ${gradle.startParameter.isParallelProjectExecutionEnabled}\nmaxWorkerCount : ${gradle.startParameter.maxWorkerCount}\nArchitecture : ${buildInfo.arch}\n\nProject Version : ${project.version}\nPkl Version : ${buildInfo.pklVersion}\nPkl Non-Unique Version : ${buildInfo.pklVersionNonUnique}\nGit Commit ID : ${buildInfo.commitId}\n====\n\"\"\"\n\nval formattedMessage =\n message.replace(\"\\n====\", \"\\n\" + \"=\".repeat(message.lines().maxByOrNull { it.length }!!.length))\n\nlogger.info(formattedMessage)\n" }, { "path": "buildSrc/build.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport org.jetbrains.kotlin.gradle.dsl.JvmTarget\n\nplugins {\n `kotlin-dsl`\n `jvm-toolchains`\n}\n\n// Keep this in sync with the constants in `BuildInfo.kt` (those are not addressable here).\nval toolchainVersion = 21\n\ndependencies {\n implementation(libs.downloadTaskPlugin)\n implementation(libs.spotlessPlugin)\n implementation(libs.kotlinPlugin) { exclude(module = \"kotlin-android-extensions\") }\n implementation(libs.shadowPlugin)\n\n // fix from the Gradle team: makes version catalog symbols available in build scripts\n // see here for more: https://github.com/gradle/gradle/issues/15383\n implementation(files(libs.javaClass.superclass.protectionDomain.codeSource.location))\n}\n\njava {\n toolchain {\n languageVersion = JavaLanguageVersion.of(toolchainVersion)\n vendor = JvmVendorSpec.ADOPTIUM\n }\n}\n\ntasks.withType().configureEach { options.release = toolchainVersion }\n\nkotlin {\n jvmToolchain(toolchainVersion)\n compilerOptions {\n jvmTarget = JvmTarget.fromTarget(toolchainVersion.toString())\n freeCompilerArgs.add(\"-Xjdk-release=$toolchainVersion\")\n }\n}\n" }, { "path": "buildSrc/settings.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n@file:Suppress(\"UnstableApiUsage\")\n\nrootProject.name = \"buildSrc\"\n\npluginManagement {\n repositories {\n mavenCentral()\n gradlePluginPortal()\n }\n}\n\nplugins { id(\"org.gradle.toolchains.foojay-resolver-convention\") }\n\n// makes ~/.gradle/init.gradle unnecessary and ~/.gradle/gradle.properties optional\ndependencyResolutionManagement {\n // use same version catalog as main build\n versionCatalogs { register(\"libs\") { from(files(\"../gradle/libs.versions.toml\")) } }\n\n repositories {\n repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)\n mavenCentral()\n gradlePluginPortal()\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/BuildInfo.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n@file:Suppress(\"MemberVisibilityCanBePrivate\")\n\nimport java.io.File\nimport org.gradle.api.Project\nimport org.gradle.api.artifacts.VersionCatalog\nimport org.gradle.api.artifacts.VersionCatalogsExtension\nimport org.gradle.api.attributes.Category\nimport org.gradle.api.provider.Provider\nimport org.gradle.api.tasks.TaskProvider\nimport org.gradle.api.tasks.testing.Test\nimport org.gradle.internal.extensions.stdlib.capitalized\nimport org.gradle.jvm.toolchain.*\nimport org.gradle.kotlin.dsl.*\nimport org.gradle.kotlin.dsl.support.serviceOf\nimport org.gradle.process.CommandLineArgumentProvider\n\n/**\n * JVM bytecode target; this is pinned at a reasonable version, because downstream JVM projects\n * which consume Pkl will need a minimum Bytecode level at or above this one.\n *\n * Kotlin and Java need matching bytecode targets, so this is expressed as a build setting and\n * constant default. To override, pass `-DpklJdkToolchain=X` to the Gradle command line, where X is\n * a major Java version.\n */\nconst val PKL_JVM_TARGET_DEFAULT_MAXIMUM = 17\n\n/**\n * The Pkl build requires JDK 21+ to build, because JDK 17 is no longer within the default set of\n * supported JDKs for GraalVM. This is a build-time requirement, not a runtime requirement.\n */\nconst val PKL_JDK_VERSION_MIN = 21\n\n/**\n * The JDK minimum is set to match the bytecode minimum, to guarantee that fat JARs work against the\n * earliest supported bytecode target.\n */\nconst val PKL_TEST_JDK_MINIMUM = PKL_JVM_TARGET_DEFAULT_MAXIMUM\n\n/**\n * Maximum JDK version which Pkl is tested with; this should be bumped when new JDK stable releases\n * are issued. At the time of this writing, JDK 23 is the latest available release.\n */\nconst val PKL_TEST_JDK_MAXIMUM = 23\n\n/**\n * Test the full suite of JDKs between [PKL_TEST_JDK_MINIMUM] and [PKL_TEST_JDK_MAXIMUM]; if this is\n * set to `false` (or overridden on the command line), only LTS releases are tested by default.\n */\nconst val PKL_TEST_ALL_JDKS = false\n\n// `buildInfo` in main build scripts\n// `project.extensions.getByType()` in precompiled script plugins\nopen class BuildInfo(private val project: Project) {\n inner class GraalVm(val arch: String) {\n val homeDir: String by lazy {\n System.getenv(\"GRAALVM_HOME\") ?: \"${System.getProperty(\"user.home\")}/.graalvm\"\n }\n\n val version: String by lazy { libs.findVersion(\"graalVm\").get().toString() }\n\n val graalVmJdkVersion: String by lazy { libs.findVersion(\"graalVmJdkVersion\").get().toString() }\n\n val osName: String by lazy {\n when {\n os.isMacOsX -> \"macos\"\n os.isLinux -> \"linux\"\n os.isWindows -> \"windows\"\n else -> throw RuntimeException(\"${os.familyName} is not supported.\")\n }\n }\n\n val baseName: String by lazy {\n \"graalvm-community-jdk-${graalVmJdkVersion}_${osName}-${arch}_bin\"\n }\n\n val downloadUrl: String by lazy {\n val extension = if (os.isWindows) \"zip\" else \"tar.gz\"\n \"https://github.com/graalvm/graalvm-ce-builds/releases/download/jdk-${graalVmJdkVersion}/$baseName.$extension\"\n }\n\n val downloadFile: File by lazy {\n val extension = if (os.isWindows) \"zip\" else \"tar.gz\"\n File(homeDir, \"${baseName}.$extension\")\n }\n\n val installDir: File by lazy { File(homeDir, baseName) }\n\n val baseDir: String by lazy {\n if (os.isMacOsX) \"$installDir/Contents/Home\" else installDir.toString()\n }\n }\n\n /** The target architecture to build, defaulting to the system architecture. */\n val targetArch by lazy { System.getProperty(\"pkl.targetArch\") ?: arch }\n\n /** Tells if this is a cross-arch build (e.g. targeting amd64 when on an aarch64 machine). */\n val isCrossArch by lazy { arch != targetArch }\n\n /** Tells if cross-arch builds are supported on this machine. */\n val isCrossArchSupported by lazy { os.isMacOsX }\n\n /** Whether to build native executables using the musl toolchain or not. */\n val musl: Boolean by lazy { java.lang.Boolean.getBoolean(\"pkl.musl\") }\n\n /** Same logic as [org.gradle.internal.os.OperatingSystem#arch], which is protected. */\n val arch: String by lazy {\n when (val arch = System.getProperty(\"os.arch\")) {\n \"x86\" -> \"i386\"\n \"x86_64\" -> \"amd64\"\n \"powerpc\" -> \"ppc\"\n else -> arch\n }\n }\n\n val graalVmAarch64: GraalVm = GraalVm(\"aarch64\")\n\n val graalVmAmd64: GraalVm = GraalVm(\"x64\")\n\n val isCiBuild: Boolean by lazy { System.getenv(\"CI\") != null }\n\n val isReleaseBuild: Boolean by lazy { java.lang.Boolean.getBoolean(\"releaseBuild\") }\n\n val isNativeArch: Boolean by lazy { java.lang.Boolean.getBoolean(\"nativeArch\") }\n\n val jvmTarget: Int by lazy {\n System.getProperty(\"pklJvmTarget\")?.toInt() ?: PKL_JVM_TARGET_DEFAULT_MAXIMUM\n }\n\n // JPMS exports for Truffle; needed on some versions of Java, and transitively within some JARs.\n private val jpmsExports =\n arrayOf(\n \"org.graalvm.truffle/com.oracle.truffle.api.exception=ALL-UNNAMED\",\n \"org.graalvm.truffle/com.oracle.truffle.api=ALL-UNNAMED\",\n \"org.graalvm.truffle/com.oracle.truffle.api.nodes=ALL-UNNAMED\",\n \"org.graalvm.truffle/com.oracle.truffle.api.source=ALL-UNNAMED\",\n )\n\n // Extra JPMS modules forced onto the module path via `--add-modules` in some cases.\n private val jpmsAddModules = arrayOf(\"jdk.unsupported\")\n\n // Formats `jpmsExports` for use in JAR manifest attributes.\n val jpmsExportsForJarManifest: String by lazy {\n jpmsExports.joinToString(\" \") { it.substringBefore(\"=\") }\n }\n\n // Formats `jpmsExports` for use on the command line with `--add-exports`.\n val jpmsExportsForAddExportsFlags: Collection by lazy {\n jpmsExports.map { \"--add-exports=$it\" }\n }\n\n // Formats `jpmsAddModules` for use on the command line with `--add-modules`.\n val jpmsAddModulesFlags: Collection by lazy { jpmsAddModules.map { \"--add-modules=$it\" } }\n\n // JVM properties to set during testing.\n val testProperties =\n mapOf(\n // @TODO: this should be removed once pkl supports JPMS as a true Java Module.\n \"polyglotimpl.DisableClassPathIsolation\" to true\n )\n\n val jdkVendor: JvmVendorSpec = JvmVendorSpec.ADOPTIUM\n\n val jdkToolchainVersion: JavaLanguageVersion by lazy {\n JavaLanguageVersion.of(System.getProperty(\"pklJdkToolchain\")?.toInt() ?: PKL_JDK_VERSION_MIN)\n }\n\n val jdkTestFloor: JavaLanguageVersion by lazy { JavaLanguageVersion.of(PKL_TEST_JDK_MINIMUM) }\n\n val jdkTestCeiling: JavaLanguageVersion by lazy { JavaLanguageVersion.of(PKL_TEST_JDK_MAXIMUM) }\n\n val testAllJdks: Boolean by lazy {\n // By default, Pkl is tested against LTS JDK releases within the bounds of `PKL_TEST_JDK_TARGET`\n // and `PKL_TEST_JDK_MAXIMUM`. To test against the full suite of JDK versions, past and present,\n // set `-DpklTestAllJdks=true` on the Gradle command line. This results in non-LTS releases, old\n // releases, and \"experimental releases\" (newer than the toolchain version) being included in\n // the default `check` suite.\n System.getProperty(\"pklTestAllJdks\")?.toBoolean() ?: PKL_TEST_ALL_JDKS\n }\n\n val testExperimentalJdks: Boolean by lazy {\n System.getProperty(\"pklTestFutureJdks\")?.toBoolean() ?: false\n }\n\n val testJdkVendors: Sequence by lazy {\n // By default, only OpenJDK is tested during multi-JDK testing. Flip `-DpklTestAllVendors=true`\n // to additionally test against a suite of JDK vendors, including Azul, Oracle, and GraalVM.\n when (System.getProperty(\"pklTestAllVendors\")?.toBoolean()) {\n true -> sequenceOf(JvmVendorSpec.ADOPTIUM, JvmVendorSpec.GRAAL_VM, JvmVendorSpec.ORACLE)\n else -> sequenceOf(JvmVendorSpec.ADOPTIUM)\n }\n }\n\n private val isArmWindows: Boolean\n get() {\n if (!os.isWindows) {\n return false\n }\n // System.getProperty(\"os.arch\") returns the architecture of the JVM, not the host OS.\n val procArch = System.getenv(\"PROCESSOR_ARCHITECTURE\")\n return \"ARM64\".equals(procArch, ignoreCase = true)\n }\n\n // Assembles a collection of JDK versions which tests can be run against, considering ancillary\n // parameters like `testAllJdks` and `testExperimentalJdks`.\n val jdkTestRange: Collection by lazy {\n if (isArmWindows) {\n // Java toolchains does not work on ARM windows: https://github.com/gradle/gradle/issues/29807\n // prevent creating tasks to test different JDKs if developing on a Windows ARM machine.\n return@lazy listOf()\n }\n JavaVersionRange.inclusive(jdkTestFloor, jdkTestCeiling).toList()\n }\n\n val JavaLanguageVersion.isEnabled: Boolean\n get() = isVersionEnabled(this)\n\n fun isVersionEnabled(version: JavaLanguageVersion): Boolean {\n return when {\n testAllJdks -> true\n multiJdkTesting -> JavaVersionRange.isLTS(version)\n testExperimentalJdks -> version > jdkToolchainVersion\n else -> false\n }\n }\n\n private fun JavaToolchainSpec.pklJdkToolchain() {\n languageVersion.set(jdkToolchainVersion)\n vendor.set(jdkVendor)\n }\n\n private fun labelForVendor(vendor: JvmVendorSpec): String =\n when (vendor) {\n JvmVendorSpec.AZUL -> \"Zulu\"\n JvmVendorSpec.GRAAL_VM -> \"GraalVm\"\n JvmVendorSpec.ORACLE -> \"Oracle\"\n JvmVendorSpec.ADOPTIUM -> \"Adoptium\"\n else -> error(\"Unrecognized JDK vendor: $vendor\")\n }\n\n private fun testNamer(baseName: () -> String): (JavaLanguageVersion, JvmVendorSpec?) -> String =\n { jdkTarget, vendor ->\n val targetToken =\n when (vendor) {\n null -> \"Jdk${jdkTarget.asInt()}\"\n else -> \"Jdk${jdkTarget.asInt()}${labelForVendor(vendor).capitalized()}\"\n }\n if (jdkTarget > jdkToolchainVersion) {\n // test targets above the toolchain target are considered \"experimental\".\n \"${baseName()}${targetToken}Experimental\"\n } else {\n \"${baseName()}${targetToken}\"\n }\n }\n\n @Suppress(\"UnstableApiUsage\")\n fun multiJdkTestingWith(\n templateTask: TaskProvider,\n configurator: MultiJdkTestConfigurator = {},\n ): Iterable> =\n with(project) {\n val isMultiVendor = testJdkVendors.count() > 1\n val baseNameProvider = { templateTask.get().name }\n val namer = testNamer(baseNameProvider)\n val applyConfig: MultiJdkTestConfigurator = { (version, jdk) ->\n // 1) copy configurations from the template task\n dependsOn(templateTask)\n templateTask.get().let { template ->\n classpath = template.classpath\n testClassesDirs = template.testClassesDirs\n jvmArgs.addAll(template.jvmArgs)\n jvmArgumentProviders.addAll(template.jvmArgumentProviders)\n forkEvery = template.forkEvery\n maxParallelForks = template.maxParallelForks\n minHeapSize = template.minHeapSize\n maxHeapSize = template.maxHeapSize\n exclude(template.excludes)\n template.systemProperties.forEach { prop -> systemProperty(prop.key, prop.value) }\n }\n\n // 2) assign launcher\n javaLauncher = jdk\n\n // 3) dispatch the user's configurator\n configurator(version to jdk)\n }\n\n serviceOf().let { toolchains ->\n jdkTestRange\n .flatMap { targetVersion ->\n // multiply out by jdk vendor\n testJdkVendors.map { vendor -> (targetVersion to vendor) }\n }\n .map { (jdkTarget, vendor) ->\n if (jdkToolchainVersion == jdkTarget)\n tasks.register(namer(jdkTarget, vendor)) {\n // alias to `test`\n dependsOn(templateTask)\n group = Category.VERIFICATION\n description =\n \"Alias for regular '${baseNameProvider()}' task, on JDK ${jdkTarget.asInt()}\"\n }\n else\n tasks.register(namer(jdkTarget, vendor.takeIf { isMultiVendor }), Test::class) {\n enabled = jdkTarget.isEnabled\n group = Category.VERIFICATION\n description = \"Run tests against JDK ${jdkTarget.asInt()}\"\n applyConfig(jdkTarget to toolchains.launcherFor { languageVersion = jdkTarget })\n // fix: on jdk17, we must force the polyglot module on to the modulepath\n if (jdkTarget.asInt() == 17)\n jvmArgumentProviders.add(\n CommandLineArgumentProvider {\n buildList { listOf(\"--add-modules=org.graalvm.polyglot\") }\n }\n )\n }\n }\n .toList()\n }\n }\n\n val javaCompiler: Provider by lazy {\n project.serviceOf().let { toolchainService ->\n toolchainService.compilerFor { pklJdkToolchain() }\n }\n }\n\n val javaTestLauncher: Provider by lazy {\n project.serviceOf().let { toolchainService ->\n toolchainService.launcherFor { pklJdkToolchain() }\n }\n }\n\n val multiJdkTesting: Boolean by lazy {\n // Test Pkl against a full range of JDK versions, past and present, within the\n // supported bounds of `PKL_TEST_JDK_TARGET` and `PKL_TEST_JDK_MAXIMUM`.\n //\n // In CI, this defaults to `true` to catch potential cross-JDK compat regressions or other bugs.\n // In local dev, this defaults to `false` to speed up the build and reduce contributor load.\n System.getProperty(\"pklMultiJdkTesting\")?.toBoolean() ?: isCiBuild\n }\n\n val hasMuslToolchain: Boolean by lazy {\n // see .github/scripts/install_musl.sh\n File(System.getProperty(\"user.home\"), \"staticdeps/bin/x86_64-linux-musl-gcc\").exists()\n }\n\n val os: org.gradle.internal.os.OperatingSystem by lazy {\n org.gradle.internal.os.OperatingSystem.current()\n }\n\n // could be `commitId: Provider = project.provider { ... }`\n val commitId: String by lazy {\n // allow -DcommitId=abc123 for build environments that don't have git.\n System.getProperty(\"commitId\").let { if (it != null) return@lazy it }\n // only run command once per build invocation\n if (project === project.rootProject) {\n val process =\n ProcessBuilder()\n .command(\"git\", \"rev-parse\", \"--short\", \"HEAD\")\n .directory(project.rootDir)\n .start()\n process.waitFor().also { exitCode ->\n if (exitCode == -1) throw RuntimeException(process.errorStream.reader().readText())\n }\n process.inputStream.reader().readText().trim()\n } else {\n project.rootProject.extensions.getByType(BuildInfo::class.java).commitId\n }\n }\n\n val commitish: String by lazy { if (isReleaseBuild) project.version.toString() else commitId }\n\n val pklVersion: String by lazy {\n if (isReleaseBuild) {\n project.version.toString()\n } else {\n project.version.toString().replace(\"-SNAPSHOT\", \"-dev+$commitId\")\n }\n }\n\n val pklVersionNonUnique: String by lazy {\n if (isReleaseBuild) {\n project.version.toString()\n } else {\n project.version.toString().replace(\"-SNAPSHOT\", \"-dev\")\n }\n }\n\n // https://melix.github.io/blog/2021/03/version-catalogs-faq.html#_but_how_can_i_use_the_catalog_in_em_plugins_em_defined_in_code_buildsrc_code\n val libs: VersionCatalog by lazy {\n project.extensions.getByType().named(\"libs\")\n }\n\n init {\n if (!isReleaseBuild) {\n project.version = \"${project.version}-SNAPSHOT\"\n }\n }\n}\n\n// Shape of a function which is applied to configure multi-JDK testing.\nprivate typealias MultiJdkTestConfigurator =\n Test.(Pair>) -> Unit\n" }, { "path": "buildSrc/src/main/kotlin/ExecutableJar.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport org.gradle.api.DefaultTask\nimport org.gradle.api.file.RegularFileProperty\nimport org.gradle.api.provider.ListProperty\nimport org.gradle.api.tasks.Input\nimport org.gradle.api.tasks.InputFile\nimport org.gradle.api.tasks.OutputFile\nimport org.gradle.api.tasks.TaskAction\n\n/**\n * Builds a self-contained Pkl CLI Jar that is directly executable on Windows, macOS, and Linux.\n *\n * For direct execution, the `java` command must be on the PATH.\n *\n * Technique borrowed from [Mill](https://mill-build.org/blog/5-executable-jars.html).\n */\nabstract class ExecutableJar : DefaultTask() {\n @get:InputFile abstract val inJar: RegularFileProperty\n\n @get:OutputFile abstract val outJar: RegularFileProperty\n\n @get:Input abstract val jvmArgs: ListProperty\n\n @TaskAction\n fun buildJar() {\n val inFile = inJar.get().asFile\n val outFile = outJar.get().asFile\n val escapedJvmArgs = jvmArgs.get().joinToString(separator = \" \") { \"\\\"$it\\\"\" }\n val unixStartScript =\n \"\"\"\n @ 2>/dev/null # 2>nul & echo off & goto BOF\n :\n exec java $escapedJvmArgs -jar \"$0\" \"$@\"\n exit\n \"\"\"\n .trimIndent()\n val windowsStartScript =\n \"\"\"\n :BOF\n setlocal\n @echo off\n java $escapedJvmArgs -jar \"%~dpnx0\" %*\n endlocal\n exit /B %errorlevel%\n \"\"\"\n .trimIndent()\n // need crlf endings for Windows portion of script\n .replace(\"\\n\", \"\\r\\n\")\n val startScript = unixStartScript + \"\\r\\n\" + windowsStartScript + \"\\r\\n\".repeat(3)\n outFile.outputStream().use { outStream ->\n startScript.byteInputStream().use { it.copyTo(outStream) }\n inFile.inputStream().use { it.copyTo(outStream) }\n }\n\n // chmod a+x\n outFile.setExecutable(true, false)\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/ExecutableSpec.kt", "content": "/*\n * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport org.gradle.api.provider.Property\n\nabstract class ExecutableSpec {\n /** The main entrypoint Java class of the executable. */\n abstract val mainClass: Property\n\n /**\n * The name of the native executable.\n *\n * Not required if not building a native executable.\n */\n abstract val name: Property\n\n /** The name of the Java executable. */\n abstract val javaName: Property\n\n /** The name of the executable that shows in the description when published to Maven. */\n abstract val documentationName: Property\n\n /**\n * The base name of the Maven publication.\n *\n * This becomes the base name of the Artifact ID, with the os and arch suffixed.\n *\n * For example, `pkl` becomes `pkl-macos-aarch` for the macOS/aarch64 variant.\n */\n abstract val publicationName: Property\n\n /** The name of the artifact ID for the Java executable. */\n abstract val javaPublicationName: Property\n\n /** The website for this executable. */\n abstract val website: Property\n}\n" }, { "path": "buildSrc/src/main/kotlin/GradlePluginTests.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport org.gradle.util.GradleVersion\n\nopen class GradlePluginTests {\n lateinit var minGradleVersion: GradleVersion\n lateinit var maxGradleVersion: GradleVersion\n var skippedGradleVersions: List = listOf()\n}\n" }, { "path": "buildSrc/src/main/kotlin/GradleVersionInfo.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport groovy.json.JsonSlurper\nimport java.net.URI\nimport org.gradle.util.GradleVersion\n\n@Suppress(\"unused\")\nclass GradleVersionInfo(json: Map) {\n val version: String by json\n\n val gradleVersion: GradleVersion by lazy { GradleVersion.version(version) }\n\n val isReleaseVersion: Boolean by lazy {\n // for some reason, `gradleVersion == gradleVersion.baseVersion` is a compile error\n gradleVersion.version == gradleVersion.baseVersion.version\n }\n\n val buildTime: String by json\n\n val current: Boolean by json\n\n val snapshot: Boolean by json\n\n val nightly: Boolean by json\n\n val releaseNightly: Boolean by json\n\n val activeRc: Boolean by json\n\n val rcFor: String by json\n\n val milestoneFor: String by json\n\n val broken: Boolean by json\n\n val downloadUrl: String by json\n\n val checksumUrl: String by json\n\n val wrapperChecksumUrl: String by json\n\n companion object {\n private fun fetchAll(): List =\n fetchMultiple(\"https://services.gradle.org/versions/all\")\n\n fun fetchReleases(): List = fetchAll().filter { it.isReleaseVersion }\n\n fun fetchCurrent(): GradleVersionInfo =\n fetchSingle(\"https://services.gradle.org/versions/current\")\n\n fun fetchRc(): GradleVersionInfo? =\n fetchSingleOrNull(\"https://services.gradle.org/versions/release-candidate\")\n\n fun fetchNightly(): GradleVersionInfo =\n fetchSingle(\"https://services.gradle.org/versions/nightly\")\n\n private fun fetchSingle(url: String): GradleVersionInfo {\n @Suppress(\"UNCHECKED_CAST\")\n return GradleVersionInfo(JsonSlurper().parse(URI(url).toURL()) as Map)\n }\n\n private fun fetchSingleOrNull(url: String): GradleVersionInfo? {\n @Suppress(\"UNCHECKED_CAST\")\n val json = JsonSlurper().parse(URI(url).toURL()) as Map\n return if (json.isEmpty()) null else GradleVersionInfo(json)\n }\n\n private fun fetchMultiple(url: String): List {\n @Suppress(\"UNCHECKED_CAST\")\n return (JsonSlurper().parse(URI(url).toURL()) as List>).map {\n GradleVersionInfo(it)\n }\n }\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/HtmlValidator.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport org.gradle.api.Project\nimport org.gradle.api.file.FileCollection\n\nopen class HtmlValidator(project: Project) {\n var sources: FileCollection = project.files()\n}\n" }, { "path": "buildSrc/src/main/kotlin/InstallGraalVm.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport java.nio.file.Files\nimport java.nio.file.Paths\nimport java.nio.file.StandardCopyOption\nimport java.util.*\nimport javax.inject.Inject\nimport kotlin.io.path.createDirectories\nimport org.gradle.api.DefaultTask\nimport org.gradle.api.internal.file.FileOperations\nimport org.gradle.api.provider.Property\nimport org.gradle.api.tasks.Input\nimport org.gradle.api.tasks.TaskAction\nimport org.gradle.process.ExecOperations\n\nabstract class InstallGraalVm\n@Inject\nconstructor(\n private val fileOperations: FileOperations,\n private val execOperations: ExecOperations,\n) : DefaultTask() {\n @get:Input abstract val graalVm: Property\n\n init {\n @Suppress(\"LeakingThis\") onlyIf(\"GraalVM not installed\") { !graalVm.get().installDir.exists() }\n }\n\n @TaskAction\n @Suppress(\"unused\")\n fun run() {\n // minimize chance of corruption by extract-to-random-dir-and-flip-symlink\n val distroDir = Paths.get(graalVm.get().homeDir, UUID.randomUUID().toString())\n try {\n distroDir.createDirectories()\n println(\"Extracting ${graalVm.get().downloadFile} into $distroDir\")\n // faster and more reliable than Gradle's `copy { from tarTree() }`\n execOperations.exec {\n workingDir = distroDir.toFile()\n executable = \"tar\"\n args(\"--strip-components=1\", \"-xzf\", graalVm.get().downloadFile)\n }\n\n val os = org.gradle.internal.os.OperatingSystem.current()\n val distroBinDir =\n if (os.isMacOsX) distroDir.resolve(\"Contents/Home/bin\") else distroDir.resolve(\"bin\")\n\n println(\"Installing native-image into $distroDir\")\n val gvmVersionMajor =\n requireNotNull(graalVm.get().version.split(\".\").first().toIntOrNull()) {\n \"Invalid GraalVM JDK version: ${graalVm.get().graalVmJdkVersion}\"\n }\n if (gvmVersionMajor < 24) {\n execOperations.exec {\n val executableName = if (os.isWindows) \"gu.cmd\" else \"gu\"\n executable = distroBinDir.resolve(executableName).toString()\n args(\"install\", \"--no-progress\", \"native-image\")\n }\n }\n\n println(\"Creating symlink ${graalVm.get().installDir} for $distroDir\")\n val tempLink = Paths.get(graalVm.get().homeDir, UUID.randomUUID().toString())\n Files.createSymbolicLink(tempLink, distroDir)\n try {\n Files.move(tempLink, graalVm.get().installDir.toPath(), StandardCopyOption.ATOMIC_MOVE)\n } catch (e: Exception) {\n try {\n fileOperations.delete(tempLink.toFile())\n } catch (ignored: Exception) {}\n throw e\n }\n } catch (e: Exception) {\n try {\n fileOperations.delete(distroDir)\n } catch (ignored: Exception) {}\n throw e\n }\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/JavaVersionRange.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n@file:Suppress(\"MemberVisibilityCanBePrivate\")\n\nimport java.util.*\nimport org.gradle.jvm.toolchain.JavaLanguageVersion\n\ntypealias JavaVersionPair = Pair\n\n// All LTS releases.\nprivate val ltsReleases =\n sortedSetOf(\n JavaLanguageVersion.of(8),\n JavaLanguageVersion.of(11),\n JavaLanguageVersion.of(17),\n JavaLanguageVersion.of(21),\n )\n\n/** Describes an inclusive range of JVM versions, based on the [JavaLanguageVersion] type. */\n@JvmInline\nvalue class JavaVersionRange private constructor(private val bounds: JavaVersionPair) :\n Iterable {\n @Suppress(\"unused\")\n companion object {\n fun isLTS(version: JavaLanguageVersion): Boolean = version in ltsReleases\n\n fun inclusive(floor: JavaLanguageVersion, ceiling: JavaLanguageVersion): JavaVersionRange =\n JavaVersionRange(floor to ceiling)\n\n fun startingAt(floor: JavaLanguageVersion): JavaVersionRange =\n inclusive(floor, JavaLanguageVersion.of(PKL_TEST_JDK_MAXIMUM))\n\n fun upTo(ceiling: JavaLanguageVersion): JavaVersionRange =\n inclusive(JavaLanguageVersion.of(PKL_TEST_JDK_MINIMUM), ceiling)\n }\n\n operator fun contains(version: JavaLanguageVersion): Boolean =\n version >= bounds.first && version <= bounds.second\n\n fun asSequence(): Sequence = sequence {\n var current = bounds.first\n while (current <= bounds.second) {\n yield(current)\n current = JavaLanguageVersion.of(current.asInt() + 1)\n }\n }\n\n fun asSortedSet(): SortedSet = asSequence().toSortedSet()\n\n override fun iterator(): Iterator = asSortedSet().iterator()\n}\n" }, { "path": "buildSrc/src/main/kotlin/MergeSourcesJars.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport java.io.File\nimport java.util.regex.Matcher\nimport java.util.regex.Pattern\nimport org.gradle.api.DefaultTask\nimport org.gradle.api.file.ConfigurableFileCollection\nimport org.gradle.api.file.FileVisitDetails\nimport org.gradle.api.file.RegularFileProperty\nimport org.gradle.api.provider.ListProperty\nimport org.gradle.api.provider.MapProperty\nimport org.gradle.api.tasks.Input\nimport org.gradle.api.tasks.InputFiles\nimport org.gradle.api.tasks.OutputFile\nimport org.gradle.api.tasks.TaskAction\nimport org.gradle.kotlin.dsl.listProperty\nimport org.gradle.kotlin.dsl.mapProperty\n\nopen class MergeSourcesJars : DefaultTask() {\n @get:InputFiles val inputJars: ConfigurableFileCollection = project.objects.fileCollection()\n\n @get:InputFiles\n val mergedBinaryJars: ConfigurableFileCollection = project.objects.fileCollection()\n\n @get:Input val relocatedPackages: MapProperty = project.objects.mapProperty()\n\n @get:Input\n var sourceFileExtensions: ListProperty =\n project.objects.listProperty().convention(listOf(\".java\", \".kt\"))\n\n @get:OutputFile val outputJar: RegularFileProperty = project.objects.fileProperty()\n\n @TaskAction\n @Suppress(\"unused\")\n fun merge() {\n val binaryPaths = collectBinaryPaths()\n\n val relocatedPkgs = relocatedPackages.get()\n\n val relocatedPaths =\n relocatedPkgs.entries.associate { (key, value) -> toPath(key) to toPath(value) }\n\n // use negative lookbehind to match any that don't precede with\n // a word or a period character. should catch most cases.\n val importPattern =\n Pattern.compile(\n \"(? {\n val result = mutableSetOf()\n for (jar in mergedBinaryJars) {\n // as of Gradle 2.4 doesn't visit dirs despite the claims\n project.zipTree(jar).visit {\n val details = this\n if (details.isDirectory) return@visit // avoid adding empty dirs\n result.add(details.relativePath.parent!!.pathString)\n }\n }\n return result\n }\n\n private fun fixImports(\n relocatedPkgs: Map,\n details: FileVisitDetails,\n sourceText: String,\n importPattern: Pattern,\n ): String {\n val matcher = importPattern.matcher(sourceText)\n val buffer = StringBuffer()\n logger.debug(\"Inspecting file: {}\", details.relativePath)\n while (matcher.find()) {\n val newStat = relocatedPkgs[matcher.group(2)]\n logger.debug(\"Old: {}\", matcher.group())\n logger.debug(\"New: {}\", newStat)\n matcher.appendReplacement(buffer, Matcher.quoteReplacement(newStat))\n }\n matcher.appendTail(buffer)\n return buffer.toString()\n }\n\n private fun toPath(packageName: String): String = packageName.replace(\".\", \"/\")\n}\n" }, { "path": "buildSrc/src/main/kotlin/NativeImageBuild.kt", "content": "/*\n * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport javax.inject.Inject\nimport org.gradle.api.DefaultTask\nimport org.gradle.api.file.ConfigurableFileCollection\nimport org.gradle.api.provider.ListProperty\nimport org.gradle.api.provider.Property\nimport org.gradle.api.provider.Provider\nimport org.gradle.api.services.BuildService\nimport org.gradle.api.services.BuildServiceParameters\nimport org.gradle.api.tasks.ClasspathNormalizer\nimport org.gradle.api.tasks.Input\nimport org.gradle.api.tasks.InputFiles\nimport org.gradle.api.tasks.OutputFile\nimport org.gradle.api.tasks.PathSensitivity\nimport org.gradle.api.tasks.TaskAction\nimport org.gradle.kotlin.dsl.registerIfAbsent\nimport org.gradle.kotlin.dsl.withNormalizer\nimport org.gradle.process.ExecOperations\n\nenum class Architecture {\n AMD64,\n AARCH64,\n}\n\nabstract class NativeImageBuildService : BuildService\n\nabstract class NativeImageBuild : DefaultTask() {\n @get:Input abstract val imageName: Property\n\n @get:Input abstract val extraNativeImageArgs: ListProperty\n\n @get:Input abstract val arch: Property\n\n @get:Input abstract val mainClass: Property\n\n @get:InputFiles abstract val classpath: ConfigurableFileCollection\n\n private val outputDir = project.layout.buildDirectory.dir(\"executable\")\n\n @get:OutputFile val outputFile = outputDir.flatMap { it.file(imageName) }\n\n @get:Inject protected abstract val execOperations: ExecOperations\n\n private val graalVm: Provider =\n arch.map { a ->\n when (a) {\n Architecture.AMD64 -> buildInfo.graalVmAmd64\n Architecture.AARCH64 -> buildInfo.graalVmAarch64\n }\n }\n\n private val buildInfo: BuildInfo = project.extensions.getByType(BuildInfo::class.java)\n\n private val nativeImageCommandName =\n if (buildInfo.os.isWindows) \"native-image.cmd\" else \"native-image\"\n\n private val nativeImageExecutable = graalVm.map { \"${it.baseDir}/bin/$nativeImageCommandName\" }\n\n private val extraArgsFromProperties by lazy {\n System.getProperties()\n .filter { it.key.toString().startsWith(\"pkl.native\") }\n .map { \"${it.key}=${it.value}\".substring(\"pkl.native\".length) }\n }\n\n private val buildService =\n project.gradle.sharedServices.registerIfAbsent(\n \"nativeImageBuildService\",\n NativeImageBuildService::class,\n ) {\n maxParallelUsages.set(1)\n }\n\n init {\n // ensure native-image builds run in serial (prevent `gw buildNative` from consuming all host\n // CPU resources).\n usesService(buildService)\n\n group = \"build\"\n\n inputs\n .files(classpath)\n .withPropertyName(\"runtimeClasspath\")\n .withNormalizer(ClasspathNormalizer::class)\n inputs\n .files(nativeImageExecutable)\n .withPropertyName(\"graalVmNativeImage\")\n .withPathSensitivity(PathSensitivity.ABSOLUTE)\n }\n\n @TaskAction\n protected fun run() {\n execOperations.exec {\n val exclusions =\n listOf(buildInfo.libs.findLibrary(\"graalSdk\").get()).map { it.get().module.name }\n\n executable = nativeImageExecutable.get()\n workingDir(outputDir)\n\n args = buildList {\n // must be emitted before any experimental options are used\n add(\"-H:+UnlockExperimentalVMOptions\")\n // currently gives a deprecation warning, but we've been told\n // that the \"initialize everything at build time\" *CLI* option is likely here to stay\n add(\"--initialize-at-build-time=\")\n // needed for messagepack-java (see https://github.com/msgpack/msgpack-java/issues/600)\n add(\"--initialize-at-run-time=org.msgpack.core.buffer.DirectBufferAccess\")\n add(\"--no-fallback\")\n add(\"-H:IncludeResources=org/pkl/core/stdlib/.*\\\\.pkl\")\n add(\"-H:IncludeResources=org/jline/utils/.*\")\n add(\"-H:IncludeResourceBundles=org.pkl.core.errorMessages\")\n add(\"-H:IncludeResourceBundles=org.pkl.parser.errorMessages\")\n add(\"-H:IncludeResources=org/pkl/commons/cli/PklCARoots.pem\")\n add(\"-H:Class=${mainClass.get()}\")\n add(\"-o\")\n add(imageName.get())\n // the actual limit (currently) used by native-image is this number + 1400 (idea is to\n // compensate for Truffle's own nodes)\n add(\"-H:MaxRuntimeCompileMethods=1800\")\n add(\"-H:+EnforceMaxRuntimeCompileMethods\")\n add(\"--enable-url-protocols=http,https\")\n add(\"-H:+ReportExceptionStackTraces\")\n // disable automatic support for JVM CLI options (puts our main class in full control of\n // argument parsing)\n add(\"-H:-ParseRuntimeOptions\")\n // quick build mode: 40% faster compilation, 20% smaller (but presumably also slower)\n // executable\n if (!buildInfo.isReleaseBuild) {\n add(\"-Ob\")\n }\n if (buildInfo.isNativeArch) {\n add(\"-march=native\")\n } else {\n add(\"-march=compatibility\")\n }\n // native-image rejects non-existing class path entries -> filter\n add(\"--class-path\")\n val pathInput =\n classpath.filter {\n it.exists() && !exclusions.any { exclude -> it.name.contains(exclude) }\n }\n add(pathInput.asPath)\n // make sure dev machine stays responsive (15% slowdown on my laptop)\n val processors =\n Runtime.getRuntime().availableProcessors() /\n if (buildInfo.os.isMacOsX && !buildInfo.isCiBuild) 4 else 1\n add(\"-J-XX:ActiveProcessorCount=${processors}\")\n // Pass through all `HOMEBREW_` prefixed environment variables to allow build with shimmed\n // tools.\n addAll(environment.keys.filter { it.startsWith(\"HOMEBREW_\") }.map { \"-E$it\" })\n addAll(extraNativeImageArgs.get())\n addAll(extraArgsFromProperties)\n }\n }\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/PklFormatterSpotless.kt", "content": "/*\n * Copyright © 2025-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport com.diffplug.spotless.FormatterFunc\nimport com.diffplug.spotless.FormatterStep\nimport java.io.Serial\nimport java.io.Serializable\nimport java.net.URLClassLoader\nimport org.gradle.api.artifacts.Configuration\n\nclass PklFormatterStep(@Transient private val configuration: Configuration) : Serializable {\n companion object {\n @Serial private const val serialVersionUID: Long = 1L\n }\n\n fun create(): FormatterStep {\n return FormatterStep.createLazy(\n \"pkl\",\n { PklFormatterStep(configuration) },\n { PklFormatterFunc(configuration) },\n )\n }\n}\n\nclass PklFormatterFunc(@Transient private val configuration: Configuration) :\n FormatterFunc, Serializable {\n companion object {\n @Serial private const val serialVersionUID: Long = 1L\n }\n\n private val classLoader by lazy {\n val urls = configuration.files.map { it.toURI().toURL() }\n URLClassLoader(urls.toTypedArray())\n }\n\n private val formatterClass by lazy { classLoader.loadClass(\"org.pkl.formatter.Formatter\") }\n\n private val formatMethod by lazy { formatterClass.getMethod(\"format\", String::class.java) }\n\n private val formatterInstance by lazy { formatterClass.getConstructor().newInstance() }\n\n override fun apply(input: String): String {\n return formatMethod(formatterInstance, input) as String\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/PklPublishing.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport java.nio.charset.StandardCharsets\nimport java.util.Base64\nimport org.gradle.api.Project\nimport org.gradle.api.publish.PublishingExtension\nimport org.gradle.api.publish.maven.MavenPublication\nimport org.gradle.api.publish.maven.tasks.AbstractPublishToMaven\nimport org.gradle.api.publish.maven.tasks.GenerateMavenPom\nimport org.gradle.kotlin.dsl.*\nimport org.gradle.plugins.signing.SigningExtension\n\n/** Configures common POM metadata (licenses, developers, SCM, etc.) for all Pkl publications. */\nfun Project.configurePklPomMetadata() {\n extensions.configure {\n publications.withType().configureEach {\n pom {\n name.set(artifactId)\n licenses {\n license {\n name.set(\"The Apache Software License, Version 2.0\")\n url.set(\"https://github.com/apple/pkl/blob/main/LICENSE.txt\")\n }\n }\n developers {\n developer {\n id.set(\"pkl-authors\")\n name.set(\"The Pkl Authors\")\n email.set(\"pkl-oss@group.apple.com\")\n }\n }\n scm {\n connection.set(\"scm:git:git://github.com/apple/pkl.git\")\n developerConnection.set(\"scm:git:ssh://github.com/apple/pkl.git\")\n val buildInfo = extensions.getByType()\n url.set(\"https://github.com/apple/pkl/tree/${buildInfo.commitish}\")\n }\n issueManagement {\n system.set(\"GitHub Issues\")\n url.set(\"https://github.com/apple/pkl/issues\")\n }\n ciManagement {\n system.set(\"GitHub Actions\")\n url.set(\"https://github.com/apple/pkl/actions\")\n }\n }\n }\n }\n}\n\n/** Configures POM validation task to check for unresolved versions and snapshots in releases. */\nfun Project.configurePomValidation() {\n val validatePom by\n tasks.registering {\n if (tasks.findByName(\"generatePomFileForLibraryPublication\") == null) {\n return@registering\n }\n val generatePomFileForLibraryPublication by tasks.existing(GenerateMavenPom::class)\n val outputFile =\n layout.buildDirectory.file(\"validatePom\") // dummy output to satisfy up-to-date check\n\n dependsOn(generatePomFileForLibraryPublication)\n inputs.file(generatePomFileForLibraryPublication.get().destination)\n outputs.file(outputFile)\n\n doLast {\n outputFile.get().asFile.delete()\n\n val pomFile = generatePomFileForLibraryPublication.get().destination\n assert(pomFile.exists())\n\n val text = pomFile.readText()\n\n run {\n val unresolvedVersion = Regex(\".*[+,()\\\\[\\\\]].*\")\n val matches = unresolvedVersion.findAll(text).toList()\n if (matches.isNotEmpty()) {\n throw org.gradle.api.GradleException(\n \"\"\"\n Found unresolved version selector(s) in generated POM:\n ${matches.joinToString(\"\\n\") { it.groupValues[0] }}\n \"\"\"\n .trimIndent()\n )\n }\n }\n\n val buildInfo = project.extensions.getByType()\n if (buildInfo.isReleaseBuild) {\n val snapshotVersion = Regex(\".*-SNAPSHOT\")\n val matches = snapshotVersion.findAll(text).toList()\n if (matches.isNotEmpty()) {\n throw org.gradle.api.GradleException(\n \"\"\"\n Found snapshot version(s) in generated POM of Pkl release version:\n ${matches.joinToString(\"\\n\") { it.groupValues[0] }}\n \"\"\"\n .trimIndent()\n )\n }\n }\n\n outputFile.get().asFile.writeText(\"OK\")\n }\n }\n\n tasks.named(\"publish\") { dependsOn(validatePom) }\n}\n\n/** Configures signing for Pkl publications. */\nfun Project.configurePklSigning() {\n // Workaround for maven publish plugin not setting up dependencies correctly.\n // Taken from https://github.com/gradle/gradle/issues/26091#issuecomment-1798137734\n val dependsOnTasks = mutableListOf()\n\n tasks.withType().configureEach {\n dependsOnTasks.add(name.replace(\"publish\", \"sign\").replaceAfter(\"Publication\", \"\"))\n dependsOn(dependsOnTasks)\n }\n\n extensions.configure {\n // provided as env vars `ORG_GRADLE_PROJECT_signingKey` and\n // `ORG_GRADLE_PROJECT_signingPassword` in CI.\n val signingKey =\n (findProperty(\"signingKey\") as String?)?.let {\n Base64.getDecoder().decode(it).toString(StandardCharsets.US_ASCII)\n }\n val signingPassword = findProperty(\"signingPassword\") as String?\n if (signingKey != null && signingPassword != null) {\n useInMemoryPgpKeys(signingKey, signingPassword)\n }\n extensions.getByType().publications.findByName(\"library\")?.let { sign(it) }\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/ResolveSourcesJars.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport org.gradle.api.DefaultTask\nimport org.gradle.api.artifacts.Configuration\nimport org.gradle.api.artifacts.result.ResolvedArtifactResult\nimport org.gradle.api.artifacts.result.ResolvedDependencyResult\nimport org.gradle.api.file.DirectoryProperty\nimport org.gradle.api.provider.Property\nimport org.gradle.api.tasks.InputFiles\nimport org.gradle.api.tasks.OutputDirectory\nimport org.gradle.api.tasks.TaskAction\nimport org.gradle.jvm.JvmLibrary\nimport org.gradle.kotlin.dsl.property\nimport org.gradle.language.base.artifact.SourcesArtifact\n\nopen class ResolveSourcesJars : DefaultTask() {\n @get:InputFiles val configuration: Property = project.objects.property()\n\n @get:OutputDirectory val outputDir: DirectoryProperty = project.objects.directoryProperty()\n\n @TaskAction\n @Suppress(\"UnstableApiUsage\", \"unused\")\n fun resolve() {\n val componentIds =\n configuration.get().incoming.resolutionResult.allDependencies.map {\n (it as ResolvedDependencyResult).selected.id\n }\n\n val resolutionResult =\n project.dependencies\n .createArtifactResolutionQuery()\n .forComponents(componentIds)\n .withArtifacts(JvmLibrary::class.java, SourcesArtifact::class.java)\n .execute()\n\n val resolvedJars =\n resolutionResult.resolvedComponents\n .flatMap { it.getArtifacts(SourcesArtifact::class.java) }\n .map { (it as ResolvedArtifactResult).file }\n\n // copying to an output dir because I don't know how else to describe task outputs\n project.sync {\n from(resolvedJars)\n into(outputDir)\n }\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/pklAllProjects.gradle.kts", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport com.diffplug.gradle.spotless.KotlinGradleExtension\nimport org.gradle.accessors.dm.LibrariesForLibs\nimport org.jetbrains.kotlin.gradle.dsl.JvmTarget\nimport org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile\n\nplugins { id(\"com.diffplug.spotless\") }\n\nval buildInfo = extensions.create(\"buildInfo\", project)\n\ndependencyLocking { lockAllConfigurations() }\n\nconfigurations {\n val rejectedVersionSuffix = Regex(\"-alpha|-beta|-eap|-m|-rc|-snapshot\", RegexOption.IGNORE_CASE)\n configureEach {\n resolutionStrategy {\n componentSelection {\n all {\n if (rejectedVersionSuffix.containsMatchIn(candidate.version)) {\n reject(\n \"Rejected dependency $candidate \" +\n \"because it has a prelease version suffix matching `$rejectedVersionSuffix`.\"\n )\n }\n }\n }\n }\n }\n}\n\nconfigurations.all {\n resolutionStrategy.eachDependency {\n if (requested.group == \"org.jetbrains.kotlin\") {\n // prevent transitive deps from bumping Koltin version\n useVersion(libs.versions.kotlin.get())\n }\n }\n}\n\nplugins.withType(JavaPlugin::class).configureEach {\n tasks.withType().configureEach { options.release = 17 }\n}\n\ntasks.withType().configureEach {\n compilerOptions {\n jvmTarget = JvmTarget.JVM_17\n freeCompilerArgs.addAll(\"-Xjsr305=strict\", \"-Xjvm-default=all\")\n freeCompilerArgs.add(\"-Xjdk-release=17\")\n }\n}\n\nplugins.withType(IdeaPlugin::class).configureEach {\n val errorMessage =\n \"Use IntelliJ Gradle import instead of running the `idea` task. See README for more information.\"\n\n tasks.named(\"idea\") { doFirst { throw GradleException(errorMessage) } }\n tasks.named(\"ideaModule\") { doFirst { throw GradleException(errorMessage) } }\n if (project == rootProject) {\n tasks.named(\"ideaProject\") { doFirst { throw GradleException(errorMessage) } }\n }\n}\n\nplugins.withType(MavenPublishPlugin::class).configureEach {\n configure {\n // CI builds pick up artifacts from this repo.\n // It's important that this repo is only declared once per project.\n repositories {\n maven {\n name = \"projectLocal\" // affects task names\n url = rootDir.resolve(\"build/m2\").toURI()\n }\n }\n // use resolved/locked (e.g., `1.15`)\n // instead of declared (e.g., `1.+`)\n // dependency versions in generated POMs\n publications {\n withType(MavenPublication::class.java) {\n versionMapping { allVariants { fromResolutionResult() } }\n }\n }\n }\n}\n\n// settings.gradle.kts sets `--write-locks`\n// if Gradle command line contains this task name\nval updateDependencyLocks by\n tasks.registering {\n doLast { configurations.filter { it.isCanBeResolved }.forEach { it.resolve() } }\n }\n\nval allDependencies by tasks.registering(DependencyReportTask::class)\n\ntasks.withType(Test::class).configureEach {\n System.getProperty(\"testReportsDir\")?.let { reportsDir ->\n reports.junitXml.outputLocation.set(file(reportsDir).resolve(project.name).resolve(name))\n }\n debugOptions {\n enabled = System.getProperty(\"jvmdebug\")?.toBoolean() ?: false\n @Suppress(\"UnstableApiUsage\")\n host = \"*\"\n port = 5005\n suspend = true\n server = true\n }\n}\n\ntasks.withType(JavaExec::class).configureEach {\n debugOptions {\n enabled = System.getProperty(\"jvmdebug\")?.toBoolean() ?: false\n @Suppress(\"UnstableApiUsage\")\n host = \"*\"\n port = 5005\n suspend = true\n server = true\n }\n}\n\n// Version Catalog library symbols.\nprivate val libs = the()\n\nprivate val licenseHeaderFile by lazy {\n rootProject.file(\"buildSrc/src/main/resources/license-header.star-block.txt\")\n}\n\nprivate fun KotlinGradleExtension.configureFormatter() {\n ktfmt(libs.versions.ktfmt.get()).googleStyle()\n licenseHeaderFile(licenseHeaderFile, \"([a-zA-Z]|@file|//)\")\n}\n\nval originalRemoteName = System.getenv(\"PKL_ORIGINAL_REMOTE_NAME\") ?: \"origin\"\n// if we're running against a release branch (or a PR targeted at one), use that branch for\n// ratcheting\n// these env vars are set by GitHub actions:\n// https://docs.github.com/en/actions/reference/workflows-and-actions/variables#default-environment-variables\nval ratchetBranchName =\n (System.getenv(\"GITHUB_BASE_REF\") ?: System.getenv(\"GITHUB_REF_NAME\"))?.let {\n if (it.startsWith(\"release/\")) it else null\n } ?: \"main\"\n\nspotless {\n ratchetFrom = \"$originalRemoteName/$ratchetBranchName\"\n\n // When building root project, format buildSrc files too.\n // We need this because buildSrc is not a subproject of the root project, so a top-level\n // `spotlessApply` will not trigger `buildSrc:spotlessApply`.\n if (project === rootProject) {\n kotlinGradle {\n configureFormatter()\n target(\"*.kts\", \"buildSrc/*.kts\", \"buildSrc/src/*/kotlin/**/*.kts\")\n }\n kotlin {\n ktfmt(libs.versions.ktfmt.get()).googleStyle()\n target(\"buildSrc/src/*/kotlin/**/*.kt\")\n licenseHeaderFile(licenseHeaderFile)\n }\n } else {\n kotlinGradle {\n configureFormatter()\n target(\"*.kts\")\n }\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/pklFatJar.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport org.gradle.api.GradleException\nimport org.gradle.api.artifacts.Configuration\nimport org.gradle.api.publish.maven.MavenPublication\nimport org.gradle.api.tasks.bundling.Jar\nimport org.gradle.api.tasks.testing.Test\nimport org.gradle.kotlin.dsl.*\n\nplugins {\n `java-library`\n `maven-publish`\n id(\"com.gradleup.shadow\")\n}\n\n// make fat Jar available to other subprojects\nval fatJarConfiguration: Configuration = configurations.create(\"fatJar\")\n\nval fatJarPublication: MavenPublication = publishing.publications.create(\"fatJar\")\n\n// ideally we'd configure this automatically based on project dependencies\nval firstPartySourcesJarsConfiguration: Configuration =\n configurations.create(\"firstPartySourcesJars\")\n\nval relocations =\n mapOf(\n // pkl-core dependencies\n \"org.organicdesign.fp.\" to \"org.pkl.thirdparty.paguro.\",\n \"org.snakeyaml.engine.\" to \"org.pkl.thirdparty.snakeyaml.engine.\",\n \"org.msgpack.\" to \"org.pkl.thirdparty.msgpack.\",\n \"org.w3c.dom.\" to \"org.pkl.thirdparty.w3c.dom.\",\n \"com.oracle.svm.core.\" to \"org.pkl.thirdparty.svm.\",\n\n // pkl-cli dependencies\n \"org.jline.\" to \"org.pkl.thirdparty.jline.\",\n \"com.github.ajalt.clikt.\" to \"org.pkl.thirdparty.clikt.\",\n \"com.github.ajalt.colormath.\" to \"org.pkl.thirdparty.colormath.\",\n \"com.github.ajalt.mordant.\" to \"org.pkl.thirdparty.mordant.\",\n \"com.sun.jna.\" to \"org.pkl.thirdparty.jna.\",\n \"kotlin.\" to \"org.pkl.thirdparty.kotlin.\",\n \"kotlinx.\" to \"org.pkl.thirdparty.kotlinx.\",\n \"org.intellij.\" to \"org.pkl.thirdparty.intellij.\",\n \"org.fusesource.jansi.\" to \"org.pkl.thirdparty.jansi.\",\n \"org.fusesource.hawtjni.\" to \"org.pkl.thirdparty.hawtjni.\",\n\n // pkl-doc dependencies\n \"org.commonmark.\" to \"org.pkl.thirdparty.commonmark.\",\n \"org.jetbrains.\" to \"org.pkl.thirdparty.jetbrains.\",\n \"_COROUTINE.\" to \"org.pkl.thirdparty.kotlinx._COROUTINE.\",\n\n // pkl-config-java dependencies\n \"io.leangen.geantyref.\" to \"org.pkl.thirdparty.geantyref.\",\n\n // pkl-codegen-java dependencies\n \"com.palantir.javapoet.\" to \"org.pkl.thirdparty.javapoet.\",\n\n // pkl-codegen-kotlin dependencies\n \"com.squareup.kotlinpoet.\" to \"org.pkl.thirdparty.kotlinpoet.\",\n )\n\nfor ((key, value) in relocations) {\n if (!key.endsWith(\".\")) {\n throw GradleException(\n \"Invalid relocation `\\\"$key\\\" to \\\"$value\\\"`: `$key` should end with a dot\"\n )\n }\n if (!value.endsWith(\".\")) {\n throw GradleException(\n \"Invalid relocation `\\\"$key\\\" to \\\"$value\\\"`: `$value` should end with a dot\"\n )\n }\n}\n\nval nonRelocations = listOf(\"com/oracle/truffle/\", \"org/graalvm/\")\n\ntasks.shadowJar {\n inputs.property(\"relocations\", relocations)\n\n archiveClassifier.set(null as String?)\n\n configurations = listOf(project.configurations.runtimeClasspath.get())\n\n addMultiReleaseAttribute = true\n\n // not required at runtime / fat JARs can't be used in native-image builds anyway\n exclude(\"org/pkl/cli/svm/**\")\n\n exclude(\"META-INF/maven/**\")\n exclude(\"META-INF/upgrade/**\")\n\n exclude(\"DebugProbesKt.bin\")\n\n val info = project.extensions.getByType()\n val minimumJvmTarget = JavaVersion.toVersion(info.jvmTarget)\n\n manifest.attributes(\n // Certain exports need to be added to the Java modulepath for Java 17 to work properly with\n // shaded JARs. See the following link for an explanation of this syntax:\n // https://bugs.openjdk.org/browse/JDK-8335225\n \"Add-Exports\" to info.jpmsExportsForJarManifest\n )\n\n // effectively, this results in calls excluding:\n // `META-INF/versions/{18-25}/**`\n // at the time of this writing; multi-release JARs beyond JDK 21 break the current\n // version of the Shadow plugin, and aren't needed for Truffle's use by Pkl.\n JavaVersionRange.startingAt(JavaLanguageVersion.of(minimumJvmTarget.majorVersion.toInt() + 1))\n .forEach { exclude(\"META-INF/versions/${it.asInt()}/**\") }\n\n exclude(\"module-info.*\")\n\n for ((from, to) in relocations) {\n relocate(from, to)\n }\n\n // necessary for service files to be adapted to relocation\n mergeServiceFiles()\n}\n\nshadow { addShadowVariantIntoJavaComponent = false }\n\nval testFatJar by\n tasks.registering(Test::class) {\n testClassesDirs = files(tasks.test.get().testClassesDirs)\n classpath =\n // compiled test classes\n sourceSets.test.get().output +\n // fat Jar\n tasks.shadowJar.get().outputs.files +\n // test-only dependencies\n // (test dependencies that are also main dependencies must already be contained in fat Jar;\n // to verify that, we don't want to include them here)\n (configurations.testRuntimeClasspath.get() - configurations.runtimeClasspath.get())\n }\n\ntasks.check { dependsOn(testFatJar) }\n\nval validateFatJar by\n tasks.registering {\n val outputFile = layout.buildDirectory.file(\"validateFatJar/result.txt\")\n inputs.files(tasks.shadowJar)\n inputs.property(\"nonRelocations\", nonRelocations)\n outputs.file(outputFile)\n\n doLast {\n val unshadowedFiles = mutableListOf()\n zipTree(tasks.shadowJar.get().outputs.files.singleFile).visit {\n val fileDetails = this\n val path = fileDetails.relativePath.pathString\n if (\n !(fileDetails.isDirectory ||\n path.startsWith(\"org/pkl/\") ||\n path.startsWith(\"META-INF/\") ||\n nonRelocations.any { path.startsWith(it) })\n ) {\n // don't throw exception inside `visit`\n // as this gives a misleading \"Could not expand ZIP\" error message\n unshadowedFiles.add(path)\n }\n }\n if (unshadowedFiles.isEmpty()) {\n outputFile.get().asFile.writeText(\"SUCCESS\")\n } else {\n outputFile.get().asFile.writeText(\"FAILURE\")\n throw GradleException(\"Found unshadowed files:\\n\" + unshadowedFiles.joinToString(\"\\n\"))\n }\n }\n }\n\ntasks.check { dependsOn(validateFatJar) }\n\nval resolveSourcesJars by\n tasks.registering(ResolveSourcesJars::class) {\n configuration.set(configurations.runtimeClasspath)\n outputDir.set(layout.buildDirectory.dir(\"resolveSourcesJars\"))\n }\n\nval fatSourcesJar by\n tasks.registering(MergeSourcesJars::class) {\n plugins.withId(\"pklJavaLibrary\") { inputJars.from(tasks.named(\"sourcesJar\")) }\n inputJars.from(firstPartySourcesJarsConfiguration)\n inputJars.from(resolveSourcesJars.map { fileTree(it.outputDir) })\n\n mergedBinaryJars.from(tasks.shadowJar)\n relocatedPackages.set(relocations)\n outputJar.fileProvider(\n provider {\n file(tasks.shadowJar.get().archiveFile.get().asFile.path.replace(\".jar\", \"-sources.jar\"))\n }\n )\n }\n\nartifacts { add(\"fatJar\", tasks.shadowJar) }\n\npublishing {\n publications {\n named(\"fatJar\") {\n from(components[\"shadow\"])\n\n // sources Jar is fat\n artifact(fatSourcesJar.flatMap { it.outputJar.asFile }) { classifier = \"sources\" }\n\n plugins.withId(\"pklJavaLibrary\") {\n val javadocJar by tasks.existing(Jar::class)\n // Javadoc Jar is not fat (didn't invest effort)\n artifact(javadocJar.flatMap { it.archiveFile }) { classifier = \"javadoc\" }\n }\n }\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/pklGraalVm.gradle.kts", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport de.undercouch.gradle.tasks.download.Download\nimport de.undercouch.gradle.tasks.download.Verify\n\nplugins { id(\"de.undercouch.download\") }\n\nval buildInfo = project.extensions.getByType()\n\n// tries to minimize chance of corruption by download-to-temp-file-and-move\nval downloadGraalVmAarch64 by\n tasks.registering(Download::class) { configureDownloadGraalVm(buildInfo.graalVmAarch64) }\n\nval downloadGraalVmAmd64 by\n tasks.registering(Download::class) { configureDownloadGraalVm(buildInfo.graalVmAmd64) }\n\nfun Download.configureDownloadGraalVm(graalvm: BuildInfo.GraalVm) {\n onlyIf { !graalvm.installDir.exists() }\n doLast { println(\"Downloaded GraalVm to ${graalvm.downloadFile}\") }\n\n src(graalvm.downloadUrl)\n dest(graalvm.downloadFile)\n overwrite(false)\n tempAndMove(true)\n}\n\nval verifyGraalVmAarch64 by\n tasks.registering(Verify::class) {\n configureVerifyGraalVm(buildInfo.graalVmAarch64)\n dependsOn(downloadGraalVmAarch64)\n }\n\nval verifyGraalVmAmd64 by\n tasks.registering(Verify::class) {\n configureVerifyGraalVm(buildInfo.graalVmAmd64)\n dependsOn(downloadGraalVmAmd64)\n }\n\nfun Verify.configureVerifyGraalVm(graalvm: BuildInfo.GraalVm) {\n onlyIf { !graalvm.installDir.exists() }\n\n src(graalvm.downloadFile)\n checksum(\n buildInfo.libs.findVersion(\"graalVmSha256-${graalvm.osName}-${graalvm.arch}\").get().toString()\n )\n algorithm(\"SHA-256\")\n}\n\n@Suppress(\"unused\")\nval installGraalVmAarch64 by\n tasks.registering(InstallGraalVm::class) {\n dependsOn(verifyGraalVmAarch64)\n graalVm = buildInfo.graalVmAarch64\n }\n\n@Suppress(\"unused\")\nval installGraalVmAmd64 by\n tasks.registering(InstallGraalVm::class) {\n dependsOn(verifyGraalVmAmd64)\n graalVm = buildInfo.graalVmAmd64\n }\n" }, { "path": "buildSrc/src/main/kotlin/pklGradlePluginTest.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nplugins { java }\n\nval gradlePluginTests = extensions.create(\"gradlePluginTests\")\n\ntasks.addRule(\"Pattern: compatibilityTest[All|Releases|Latest|Candidate|Nightly|]\") {\n val taskName = this\n val matchResult = Regex(\"compatibilityTest(.+)\").matchEntire(taskName) ?: return@addRule\n\n when (val taskNameSuffix = matchResult.groupValues[1]) {\n \"All\" ->\n task(\"compatibilityTestAll\") {\n dependsOn(\n \"compatibilityTestReleases\",\n \"compatibilityTestCandidate\",\n \"compatibilityTestNightly\",\n )\n }\n // releases in configured range\n \"Releases\" ->\n task(\"compatibilityTestReleases\") {\n val versionInfos = GradleVersionInfo.fetchReleases()\n val allVersions =\n versionInfos\n .filter { versionInfo ->\n val v = versionInfo.gradleVersion\n !versionInfo.broken &&\n v in gradlePluginTests.minGradleVersion..gradlePluginTests.maxGradleVersion &&\n v !in gradlePluginTests.skippedGradleVersions\n }\n .sortedBy { it.gradleVersion }\n val versionsToTestAgainst = listOf(allVersions.first(), allVersions.last())\n\n dependsOn(versionsToTestAgainst.map { createCompatibilityTestTask(it) })\n }\n // latest release (if not developing against latest)\n \"Latest\" ->\n task(\"compatibilityTestLatest\") {\n val versionInfo = GradleVersionInfo.fetchCurrent()\n if (versionInfo.version == gradle.gradleVersion) {\n doLast {\n println(\n \"No new Gradle release available. \" +\n \"(Run `gradlew test` to test against ${versionInfo.version}.)\"\n )\n }\n } else {\n dependsOn(createCompatibilityTestTask(versionInfo))\n }\n }\n // active release candidate (if any)\n \"Candidate\" ->\n task(\"compatibilityTestCandidate\") {\n val versionInfo = GradleVersionInfo.fetchRc()\n if (versionInfo?.activeRc == true) {\n dependsOn(createCompatibilityTestTask(versionInfo))\n } else {\n doLast { println(\"No active Gradle release candidate available.\") }\n }\n }\n // latest nightly\n \"Nightly\" ->\n task(\"compatibilityTestNightly\") {\n val versionInfo = GradleVersionInfo.fetchNightly()\n dependsOn(createCompatibilityTestTask(versionInfo))\n }\n // explicit version\n else ->\n createCompatibilityTestTask(\n taskNameSuffix,\n \"https://services.gradle.org/distributions-snapshots/gradle-$taskNameSuffix-bin.zip\",\n )\n }\n}\n\nfun createCompatibilityTestTask(versionInfo: GradleVersionInfo): TaskProvider =\n createCompatibilityTestTask(versionInfo.version, versionInfo.downloadUrl)\n\nfun createCompatibilityTestTask(version: String, downloadUrl: String): TaskProvider {\n return tasks.register(\"compatibilityTest$version\", Test::class.java) {\n mustRunAfter(tasks.test)\n\n maxHeapSize = tasks.test.get().maxHeapSize\n jvmArgs = tasks.test.get().jvmArgs\n classpath = tasks.test.get().classpath\n systemProperty(\"testGradleVersion\", version)\n systemProperty(\"testGradleDistributionUrl\", downloadUrl)\n\n doFirst {\n if (version == gradle.gradleVersion && gradle.taskGraph.hasTask(tasks.test.get())) {\n // don't test same version twice\n println(\"This version has already been tested by the `test` task.\")\n throw StopExecutionException()\n }\n }\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/pklHtmlValidator.gradle.kts", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nplugins { base }\n\nval htmlValidator = extensions.create(\"htmlValidator\", project)\n\nval buildInfo = project.extensions.getByType()\n\nval validatorConfiguration: Configuration =\n configurations.create(\"validator\") {\n resolutionStrategy.eachDependency {\n if (requested.group == \"log4j\" && requested.name == \"log4j\") {\n @Suppress(\"UnstableApiUsage\") useTarget(buildInfo.libs.findLibrary(\"log4j12Api\").get())\n because(\"mitigate critical security vulnerabilities\")\n }\n }\n }\n\ndependencies {\n @Suppress(\"UnstableApiUsage\")\n validatorConfiguration(buildInfo.libs.findLibrary(\"nuValidator\").get()) {\n // we only want jetty-util and jetty-util-ajax (with the right version)\n // couldn't find a more robust way to express this\n exclude(group = \"org.eclipse.jetty\", module = \"jetty-continuation\")\n exclude(group = \"org.eclipse.jetty\", module = \"jetty-http\")\n exclude(group = \"org.eclipse.jetty\", module = \"jetty-io\")\n exclude(group = \"org.eclipse.jetty\", module = \"jetty-security\")\n exclude(group = \"org.eclipse.jetty\", module = \"jetty-server\")\n exclude(group = \"org.eclipse.jetty\", module = \"jetty-servlets\")\n exclude(group = \"javax.servlet\")\n exclude(group = \"commons-fileupload\")\n }\n}\n\nval validateHtml by\n tasks.registering(JavaExec::class) {\n val resultFile = layout.buildDirectory.file(\"validateHtml/result.txt\")\n inputs.files(htmlValidator.sources)\n outputs.file(resultFile)\n\n classpath = validatorConfiguration\n mainClass.set(\"nu.validator.client.SimpleCommandLineValidator\")\n args(\n \"--skip-non-html\"\n ) // --also-check-css doesn't work (still checks css as html), so limit to html files\n args(\"--filterpattern\", \"(.*)Consider adding “lang=(.*)\")\n args(\"--filterpattern\", \"(.*)Consider adding a “lang” attribute(.*)\")\n args(\"--filterpattern\", \"(.*)unrecognized media “amzn-kf8”(.*)\") // kindle\n // for debugging\n // args \"--verbose\"\n args(htmlValidator.sources)\n\n // write a basic result file s.t. gradle can consider task up-to-date\n // writing a result file in case validation fails is not easily possible with JavaExec, but also\n // not strictly necessary\n doFirst { project.delete(resultFile) }\n doLast { resultFile.get().asFile.writeText(\"Success.\") }\n }\n\ntasks.check { dependsOn(validateHtml) }\n" }, { "path": "buildSrc/src/main/kotlin/pklJavaExecutable.gradle.kts", "content": "/*\n * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport kotlin.io.path.createDirectories\nimport kotlin.io.path.writeText\nimport org.gradle.kotlin.dsl.support.serviceOf\n\nplugins {\n id(\"pklJavaLibrary\")\n // id(\"pklPublishLibrary\")\n id(\"com.gradleup.shadow\")\n}\n\nval executableSpec = project.extensions.create(\"executable\", ExecutableSpec::class.java)\nval buildInfo = project.extensions.getByType()\n\nval javaExecutable by\n tasks.registering(ExecutableJar::class) {\n group = \"build\"\n dependsOn(tasks.jar)\n inJar = tasks.shadowJar.flatMap { it.archiveFile }\n val effectiveJavaName =\n executableSpec.javaName.map { name -> if (buildInfo.os.isWindows) \"$name.bat\" else name }\n outJar = layout.buildDirectory.dir(\"executable\").flatMap { it.file(effectiveJavaName) }\n\n // uncomment for debugging\n // jvmArgs.addAll(\"-ea\", \"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005\")\n }\n\nfun Task.setupTestStartJavaExecutable(launcher: Provider? = null) {\n group = \"verification\"\n dependsOn(javaExecutable)\n\n // dummy output to satisfy up-to-date check\n val outputFile = layout.buildDirectory.file(\"testStartJavaExecutable/$name\")\n outputs.file(outputFile)\n\n val execOutput =\n providers.exec {\n val executablePath = javaExecutable.get().outputs.files.singleFile\n if (launcher?.isPresent == true) {\n commandLine(\n launcher.get().executablePath.asFile.absolutePath,\n \"-jar\",\n executablePath.absolutePath,\n \"--version\",\n )\n } else {\n commandLine(executablePath.absolutePath, \"--version\")\n }\n }\n\n doLast {\n val outputText = execOutput.standardOutput.asText.get()\n if (!outputText.contains(buildInfo.pklVersionNonUnique)) {\n throw GradleException(\n \"Expected version output to contain current version (${buildInfo.pklVersionNonUnique}), but got '$outputText'\"\n )\n }\n outputFile.get().asFile.toPath().apply {\n try {\n parent.createDirectories()\n } catch (ignored: java.nio.file.FileAlreadyExistsException) {}\n writeText(\"OK\")\n }\n }\n}\n\nval testStartJavaExecutable by tasks.registering { setupTestStartJavaExecutable() }\n\n// Setup `testStartJavaExecutable` tasks for multi-JDK testing.\nval testStartJavaExecutableOnOtherJdks =\n buildInfo.jdkTestRange.map { jdkTarget ->\n tasks.register(\"testStartJavaExecutableJdk${jdkTarget.asInt()}\") {\n enabled = buildInfo.isVersionEnabled(jdkTarget)\n val toolChainService: JavaToolchainService = serviceOf()\n val launcher = toolChainService.launcherFor { languageVersion = jdkTarget }\n setupTestStartJavaExecutable(launcher)\n }\n }\n\ntasks.assemble { dependsOn(javaExecutable) }\n\ntasks.check {\n dependsOn(testStartJavaExecutable)\n dependsOn(testStartJavaExecutableOnOtherJdks)\n}\n\n// publishing {\n// publications {\n// // need to put in `afterEvaluate` because `artifactId` cannot be set lazily.\n// project.afterEvaluate {\n// register(\"javaExecutable\") {\n// artifactId = executableSpec.javaPublicationName.get()\n//\n// artifact(javaExecutable.map { it.outputs.files.singleFile }) {\n// classifier = null\n// extension = \"bin\"\n// builtBy(javaExecutable)\n// }\n//\n// pom {\n// url = executableSpec.website\n// description =\n// executableSpec.documentationName.map { name ->\n// \"\"\"\n// $name executable for Java.\n// Can be executed directly, or with `java -jar `.\n// Requires Java 17 or higher.\n// \"\"\"\n// .trimIndent()\n// }\n// }\n// }\n// }\n// }\n// }\n\n// signing { project.afterEvaluate { sign(publishing.publications[\"javaExecutable\"]) } }\n" }, { "path": "buildSrc/src/main/kotlin/pklJavaLibrary.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n@file:Suppress(\"HttpUrlsUsage\", \"unused\")\n\nimport org.gradle.accessors.dm.LibrariesForLibs\n\nplugins {\n `java-library`\n `jvm-toolchains`\n `jvm-test-suite`\n id(\"pklKotlinTest\")\n id(\"com.diffplug.spotless\")\n}\n\n// make sources Jar available to other subprojects\nval sourcesJarConfiguration: Provider = configurations.register(\"sourcesJar\")\n\n// Version Catalog library symbols.\nval libs = the()\n\n// Build configuration.\nval info = project.extensions.getByType()\n\njava {\n withSourcesJar() // creates `sourcesJar` task\n withJavadocJar()\n\n toolchain {\n languageVersion = info.jdkToolchainVersion\n vendor = info.jdkVendor\n }\n}\n\nartifacts {\n // make sources Jar available to other subprojects\n add(\"sourcesJar\", tasks[\"sourcesJar\"])\n}\n\nspotless {\n java {\n googleJavaFormat(libs.versions.googleJavaFormat.get())\n target(\"src/*/java/**/*.java\")\n licenseHeaderFile(rootProject.file(\"buildSrc/src/main/resources/license-header.star-block.txt\"))\n }\n kotlin {\n ktfmt(libs.versions.ktfmt.get()).googleStyle()\n target(\"src/*/kotlin/**/*.kt\")\n licenseHeaderFile(rootProject.file(\"buildSrc/src/main/resources/license-header.star-block.txt\"))\n }\n}\n\ntasks.compileKotlin { enabled = false }\n\ntasks.jar {\n manifest {\n attributes +=\n mapOf(\n \"Automatic-Module-Name\" to \"org.${project.name.replace(\"-\", \".\")}\",\n \"Add-Exports\" to info.jpmsExportsForJarManifest,\n )\n }\n}\n\ntasks.javadoc {\n classpath = sourceSets.main.get().output + sourceSets.main.get().compileClasspath\n source = sourceSets.main.get().allJava\n title = \"${project.name} ${project.version} API\"\n (options as StandardJavadocDocletOptions).addStringOption(\"Xdoclint:none\", \"-quiet\")\n}\n\nval workAroundKotlinGradlePluginBug by\n tasks.registering {\n doLast {\n // Works around this problem, which sporadically appears and disappears in different\n // subprojects:\n // A problem was found with the configuration of task ':pkl-executor:compileJava' (type\n // 'JavaCompile').\n // > Directory '[...]/pkl/pkl-executor/build/classes/kotlin/main'\n // specified for property 'compileKotlinOutputClasses' does not exist.\n layout.buildDirectory.dir(\"classes/kotlin/main\").get().asFile.mkdirs()\n }\n }\n\nval truffleJavacArgs =\n listOf(\n // TODO: determine correct limits for Truffle specializations\n // (see https://graalvm.slack.com/archives/CNQSB2DHD/p1712380902746829)\n \"-Atruffle.dsl.SuppressWarnings=truffle-limit\"\n )\n\ntasks.compileJava {\n javaCompiler = info.javaCompiler\n dependsOn(workAroundKotlinGradlePluginBug)\n options.compilerArgs.addAll(truffleJavacArgs + info.jpmsAddModulesFlags)\n}\n\ntasks.withType().configureEach {\n javaCompiler = info.javaCompiler\n options.release = info.jvmTarget\n}\n\ntasks.withType().configureEach { jvmArgs(info.jpmsAddModulesFlags) }\n\nfun Test.configureJdkTestTask(launcher: Provider) {\n useJUnitPlatform()\n javaLauncher = launcher\n systemProperties.putAll(info.testProperties)\n jvmArgs.addAll(info.jpmsAddModulesFlags)\n}\n\ntasks.test { configureJdkTestTask(info.javaTestLauncher) }\n\n// Prepare test tasks for each JDK version which is within the test target suite for Pkl. Each task\n// uses a pinned JDK toolchain version, and is named for the major version which is tested.\n//\n// Test tasks configured in this manner are executed manually by name, e.g. `./gradlew testJdk11`,\n// and automatically as dependencies of `check`.\n//\n// We omit the current JDK from this list because it is already tested, in effect, by the default\n// `test` task.\n//\n// Pkl subprojects may elect to further configure these tasks as needed; by default, each task\n// inherits the configuration of the default `test` task (aside from an overridden launcher).\nval jdkTestTasks = info.multiJdkTestingWith(tasks.test) { (_, jdk) -> configureJdkTestTask(jdk) }\n\ntasks.check { dependsOn(jdkTestTasks) }\n" }, { "path": "buildSrc/src/main/kotlin/pklKotlinLibrary.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport org.gradle.accessors.dm.LibrariesForLibs\nimport org.jetbrains.kotlin.gradle.dsl.JvmTarget\nimport org.jetbrains.kotlin.gradle.dsl.KotlinVersion\nimport org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile\n\nplugins {\n id(\"pklJavaLibrary\")\n kotlin(\"jvm\")\n}\n\n// Build configuration.\nval buildInfo = project.extensions.getByType()\n\n// Version Catalog library symbols.\nval libs = the()\n\ndependencies {\n // At least some of our kotlin APIs contain Kotlin stdlib types\n // that aren't compiled away by kotlinc (e.g., `kotlin.Function`).\n // So let's be conservative and default to `api` for now.\n // For Kotlin APIs that only target Kotlin users (e.g., pkl-config-kotlin),\n // it won't make a difference.\n api(buildInfo.libs.findLibrary(\"kotlinStdLib\").get())\n}\n\ntasks.compileKotlin {\n enabled = true // disabled by pklJavaLibrary\n}\n\ntasks.withType().configureEach {\n compilerOptions {\n languageVersion = KotlinVersion.KOTLIN_2_1\n jvmTarget = JvmTarget.fromTarget(buildInfo.jvmTarget.toString())\n freeCompilerArgs.addAll(\"-Xjdk-release=${buildInfo.jvmTarget}\")\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/pklKotlinTest.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport java.net.URI\nimport org.gradle.accessors.dm.LibrariesForLibs\nimport org.gradle.api.tasks.testing.logging.TestExceptionFormat\n\nplugins {\n `jvm-test-suite`\n kotlin(\"jvm\")\n}\n\nval buildInfo = project.extensions.getByType()\n\nval libs = the()\n\ndependencies {\n testImplementation(libs.assertj)\n testImplementation(libs.junitApi)\n testImplementation(libs.junitParams)\n testImplementation(libs.kotlinStdLib)\n\n testRuntimeOnly(libs.junitEngine)\n testRuntimeOnly(libs.junitLauncher)\n}\n\ntasks.withType().configureEach {\n val testTask = this\n\n useJUnitPlatform()\n\n // enable checking of stdlib return types\n systemProperty(\"org.pkl.testMode\", \"true\")\n\n reports.named(\"html\") { enabled = true }\n\n testLogging { exceptionFormat = TestExceptionFormat.FULL }\n\n addTestListener(\n object : TestListener {\n override fun beforeSuite(suite: TestDescriptor) {}\n\n override fun beforeTest(testDescriptor: TestDescriptor) {}\n\n override fun afterTest(testDescriptor: TestDescriptor, result: TestResult) {}\n\n // print report link at end of task, not just at end of build\n override fun afterSuite(descriptor: TestDescriptor, result: TestResult) {\n if (descriptor.parent != null) return // only interested in overall result\n\n if (result.resultType == TestResult.ResultType.FAILURE) {\n println(\n \"\\nThere were failing tests. See the report at: ${fixFileUri(testTask.reports.html.entryPoint.toURI())}\"\n )\n }\n }\n\n // makes links clickable on macOS\n private fun fixFileUri(uri: URI): URI {\n if (\"file\" == uri.scheme && !uri.schemeSpecificPart.startsWith(\"//\")) {\n return URI.create(\"file://\" + uri.schemeSpecificPart)\n }\n return uri\n }\n }\n )\n}\n" }, { "path": "buildSrc/src/main/kotlin/pklNativeExecutable.gradle.kts", "content": "/*\n * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport java.lang.Runtime.Version\nimport kotlin.io.path.createDirectories\nimport kotlin.io.path.writeText\nimport org.gradle.accessors.dm.LibrariesForLibs\n\nplugins {\n id(\"pklGraalVm\")\n id(\"pklJavaLibrary\")\n id(\"pklNativeLifecycle\")\n id(\"pklPublishLibrary\")\n id(\"com.gradleup.shadow\")\n}\n\n// assumes that `pklJavaExecutable` is also applied\nval executableSpec = project.extensions.getByType()\nval buildInfo = project.extensions.getByType()\n\nval stagedMacAmd64Executable: Configuration by configurations.creating\nval stagedMacAarch64Executable: Configuration by configurations.creating\nval stagedLinuxAmd64Executable: Configuration by configurations.creating\nval stagedLinuxAarch64Executable: Configuration by configurations.creating\nval stagedAlpineLinuxAmd64Executable: Configuration by configurations.creating\nval stagedWindowsAmd64Executable: Configuration by configurations.creating\n\nval nativeImageClasspath by\n configurations.creating {\n extendsFrom(configurations.runtimeClasspath.get())\n // Ensure native-image version uses GraalVM C SDKs instead of Java FFI or JNA\n // (comes from artifact `mordant-jvm-graal-ffi`).\n exclude(\"com.github.ajalt.mordant\", \"mordant-jvm-ffm\")\n exclude(\"com.github.ajalt.mordant\", \"mordant-jvm-ffm-jvm\")\n exclude(\"com.github.ajalt.mordant\", \"mordant-jvm-jna\")\n exclude(\"com.github.ajalt.mordant\", \"mordant-jvm-jna-jvm\")\n }\n\nval libs = the()\n\ndependencies {\n fun executableFile(suffix: String) =\n files(\n layout.buildDirectory.dir(\"executable\").map { dir ->\n dir.file(executableSpec.name.map { \"$it-$suffix\" })\n }\n )\n nativeImageClasspath(libs.truffleRuntime)\n nativeImageClasspath(libs.graalSdk)\n\n stagedMacAarch64Executable(executableFile(\"macos-aarch64\"))\n stagedMacAmd64Executable(executableFile(\"macos-amd64\"))\n stagedLinuxAmd64Executable(executableFile(\"linux-amd64\"))\n stagedLinuxAarch64Executable(executableFile(\"linux-aarch64\"))\n stagedAlpineLinuxAmd64Executable(executableFile(\"alpine-linux-amd64\"))\n stagedWindowsAmd64Executable(executableFile(\"windows-amd64.exe\"))\n}\n\nprivate fun NativeImageBuild.amd64() {\n arch = Architecture.AMD64\n dependsOn(\":installGraalVmAmd64\")\n}\n\nprivate fun NativeImageBuild.aarch64() {\n arch = Architecture.AARCH64\n dependsOn(\":installGraalVmAarch64\")\n}\n\nprivate fun NativeImageBuild.setClasspath() {\n classpath.from(sourceSets.main.map { it.output })\n classpath.from(\n project(\":pkl-commons-cli\").extensions.getByType(SourceSetContainer::class)[\"svm\"].output\n )\n classpath.from(nativeImageClasspath)\n}\n\nval macExecutableAmd64 by\n tasks.registering(NativeImageBuild::class) {\n imageName = executableSpec.name.map { \"$it-macos-amd64\" }\n mainClass = executableSpec.mainClass\n amd64()\n setClasspath()\n }\n\nval macExecutableAarch64 by\n tasks.registering(NativeImageBuild::class) {\n imageName = executableSpec.name.map { \"$it-macos-aarch64\" }\n mainClass = executableSpec.mainClass\n aarch64()\n setClasspath()\n }\n\nval linuxExecutableAmd64 by\n tasks.registering(NativeImageBuild::class) {\n imageName = executableSpec.name.map { \"$it-linux-amd64\" }\n mainClass = executableSpec.mainClass\n amd64()\n setClasspath()\n }\n\nval linuxExecutableAarch64 by\n tasks.registering(NativeImageBuild::class) {\n imageName = executableSpec.name.map { \"$it-linux-aarch64\" }\n mainClass = executableSpec.mainClass\n aarch64()\n setClasspath()\n // Ensure compatibility for kernels with page size set to 4k, 16k and 64k\n // (e.g. Raspberry Pi 5, Asahi Linux)\n extraNativeImageArgs.add(\"-H:PageSize=65536\")\n }\n\nval alpineExecutableAmd64 by\n tasks.registering(NativeImageBuild::class) {\n imageName = executableSpec.name.map { \"$it-alpine-linux-amd64\" }\n mainClass = executableSpec.mainClass\n amd64()\n setClasspath()\n extraNativeImageArgs.addAll(listOf(\"--static\", \"--libc=musl\"))\n }\n\nval windowsExecutableAmd64 by\n tasks.registering(NativeImageBuild::class) {\n imageName = executableSpec.name.map { \"$it-windows-amd64\" }\n mainClass = executableSpec.mainClass\n amd64()\n setClasspath()\n }\n\nval assembleNative by tasks.existing\n\nval testStartNativeExecutable by\n tasks.registering {\n dependsOn(assembleNative)\n\n // dummy file for up-to-date checking\n val outputFile = project.layout.buildDirectory.file(\"testStartNativeExecutable/output.txt\")\n outputs.file(outputFile)\n\n val execOutput =\n providers.exec { commandLine(assembleNative.get().outputs.files.singleFile, \"--version\") }\n\n doLast {\n val outputText = execOutput.standardOutput.asText.get()\n if (!outputText.contains(buildInfo.pklVersionNonUnique)) {\n throw GradleException(\n \"Expected version output to contain current version (${buildInfo.pklVersionNonUnique}), but got '$outputText'\"\n )\n }\n outputFile.get().asFile.toPath().apply {\n try {\n parent.createDirectories()\n } catch (ignored: java.nio.file.FileAlreadyExistsException) {}\n writeText(\"OK\")\n }\n }\n }\n\nval requiredGlibcVersion: Version = Version.parse(\"2.17\")\n\nval checkGlibc by\n tasks.registering {\n enabled = buildInfo.os.isLinux && !buildInfo.musl\n dependsOn(assembleNative)\n doLast {\n val exec =\n providers.exec {\n commandLine(\"objdump\", \"-T\", assembleNative.get().outputs.files.singleFile)\n }\n val output = exec.standardOutput.asText.get()\n val minimumGlibcVersion =\n output\n .split(\"\\n\")\n .mapNotNull { line ->\n val match = Regex(\"GLIBC_([.0-9]*)\").find(line)\n match?.groups[1]?.let { Version.parse(it.value) }\n }\n .maxOrNull()\n if (minimumGlibcVersion == null) {\n throw GradleException(\n \"Could not determine glibc version from executable. objdump output: $output\"\n )\n }\n if (minimumGlibcVersion > requiredGlibcVersion) {\n throw GradleException(\n \"Incorrect glibc version. Found: $minimumGlibcVersion, required: $requiredGlibcVersion\"\n )\n }\n }\n }\n\n// Expose underlying task's outputs\nprivate fun Task.wraps(other: TaskProvider) {\n dependsOn(other)\n outputs.files(other)\n}\n\nval testNative by tasks.existing { dependsOn(testStartNativeExecutable, checkGlibc) }\n\nval assembleNativeMacOsAarch64 by tasks.existing { wraps(macExecutableAarch64) }\n\nval assembleNativeMacOsAmd64 by tasks.existing { wraps(macExecutableAmd64) }\n\nval assembleNativeLinuxAarch64 by tasks.existing { wraps(linuxExecutableAarch64) }\n\nval assembleNativeLinuxAmd64 by tasks.existing { wraps(linuxExecutableAmd64) }\n\nval assembleNativeAlpineLinuxAmd64 by tasks.existing { wraps(alpineExecutableAmd64) }\n\nval assembleNativeWindowsAmd64 by tasks.existing { wraps(windowsExecutableAmd64) }\n\npublishing {\n publications {\n // need to put in `afterEvaluate` because `artifactId` cannot be set lazily.\n project.afterEvaluate {\n create(\"macExecutableAmd64\") {\n artifactId = \"${executableSpec.publicationName.get()}-macos-amd64\"\n artifact(stagedMacAmd64Executable.singleFile) {\n classifier = null\n extension = \"bin\"\n builtBy(stagedMacAmd64Executable)\n }\n pom {\n name = \"${executableSpec.publicationName.get()}-macos-amd64\"\n url = executableSpec.website\n description =\n executableSpec.documentationName.map { name ->\n \"Native $name executable for macOS/amd64.\"\n }\n }\n }\n\n create(\"macExecutableAarch64\") {\n artifactId = \"${executableSpec.publicationName.get()}-macos-aarch64\"\n artifact(stagedMacAarch64Executable.singleFile) {\n classifier = null\n extension = \"bin\"\n builtBy(stagedMacAarch64Executable)\n }\n pom {\n name = \"${executableSpec.publicationName.get()}-macos-aarch64\"\n url = executableSpec.website\n description =\n executableSpec.documentationName.map { name ->\n \"Native $name executable for macOS/aarch64.\"\n }\n }\n }\n\n create(\"linuxExecutableAmd64\") {\n artifactId = \"${executableSpec.publicationName.get()}-linux-amd64\"\n artifact(stagedLinuxAmd64Executable.singleFile) {\n classifier = null\n extension = \"bin\"\n builtBy(stagedLinuxAmd64Executable)\n }\n pom {\n name = \"${executableSpec.publicationName.get()}-linux-amd64\"\n url = executableSpec.website\n description =\n executableSpec.documentationName.map { name ->\n \"Native $name executable for linux/amd64.\"\n }\n }\n }\n\n create(\"linuxExecutableAarch64\") {\n artifactId = \"${executableSpec.publicationName.get()}-linux-aarch64\"\n artifact(stagedLinuxAarch64Executable.singleFile) {\n classifier = null\n extension = \"bin\"\n builtBy(stagedLinuxAarch64Executable)\n }\n pom {\n name = \"${executableSpec.publicationName.get()}-linux-aarch64\"\n url = executableSpec.website\n description =\n executableSpec.documentationName.map { name ->\n \"Native $name executable for linux/aarch64.\"\n }\n }\n }\n\n create(\"alpineLinuxExecutableAmd64\") {\n artifactId = \"${executableSpec.publicationName.get()}-alpine-linux-amd64\"\n artifact(stagedAlpineLinuxAmd64Executable.singleFile) {\n classifier = null\n extension = \"bin\"\n builtBy(stagedAlpineLinuxAmd64Executable)\n }\n pom {\n name = \"${executableSpec.publicationName.get()}-alpine-linux-amd64\"\n url = executableSpec.website\n description =\n executableSpec.documentationName.map { name ->\n \"Native $name executable for linux/amd64 and statically linked to musl.\"\n }\n }\n }\n\n create(\"windowsExecutableAmd64\") {\n artifactId = \"${executableSpec.publicationName.get()}-windows-amd64\"\n artifact(stagedWindowsAmd64Executable.singleFile) {\n classifier = null\n extension = \"exe\"\n builtBy(stagedWindowsAmd64Executable)\n }\n pom {\n name = \"${executableSpec.publicationName.get()}-windows-amd64\"\n url = executableSpec.website\n description =\n executableSpec.documentationName.map { name ->\n \"Native $name executable for windows/amd64.\"\n }\n }\n }\n }\n }\n}\n\nsigning {\n project.afterEvaluate {\n sign(publishing.publications[\"linuxExecutableAarch64\"])\n sign(publishing.publications[\"linuxExecutableAmd64\"])\n sign(publishing.publications[\"macExecutableAarch64\"])\n sign(publishing.publications[\"macExecutableAmd64\"])\n sign(publishing.publications[\"alpineLinuxExecutableAmd64\"])\n sign(publishing.publications[\"windowsExecutableAmd64\"])\n }\n}\n" }, { "path": "buildSrc/src/main/kotlin/pklNativeLifecycle.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nval assembleNativeMacOsAarch64 by tasks.registering { group = \"build\" }\n\nval assembleNativeMacOsAmd64 by tasks.registering { group = \"build\" }\n\nval assembleNativeLinuxAarch64 by tasks.registering { group = \"build\" }\n\nval assembleNativeLinuxAmd64 by tasks.registering { group = \"build\" }\n\nval assembleNativeAlpineLinuxAmd64 by tasks.registering { group = \"build\" }\n\nval assembleNativeWindowsAmd64 by tasks.registering { group = \"build\" }\n\nval testNativeMacOsAarch64 by tasks.registering { group = \"verification\" }\n\nval testNativeMacOsAmd64 by tasks.registering { group = \"verification\" }\n\nval testNativeLinuxAarch64 by tasks.registering { group = \"verification\" }\n\nval testNativeLinuxAmd64 by tasks.registering { group = \"verification\" }\n\nval testNativeAlpineLinuxAmd64 by tasks.registering { group = \"verification\" }\n\nval testNativeWindowsAmd64 by tasks.registering { group = \"verification\" }\n\nval buildInfo = project.extensions.getByType()\n\nprivate fun Task.wraps(other: TaskProvider) {\n dependsOn(other)\n outputs.files(other)\n}\n\nval assembleNative by\n tasks.registering {\n group = \"build\"\n\n if (!buildInfo.isCrossArchSupported && buildInfo.isCrossArch) {\n throw GradleException(\"Cross-arch builds are not supported on ${buildInfo.os.name}\")\n }\n\n when {\n buildInfo.os.isMacOsX && buildInfo.targetArch == \"aarch64\" -> {\n wraps(assembleNativeMacOsAarch64)\n }\n buildInfo.os.isMacOsX && buildInfo.targetArch == \"amd64\" -> {\n wraps(assembleNativeMacOsAmd64)\n }\n buildInfo.os.isLinux && buildInfo.targetArch == \"aarch64\" -> {\n wraps(assembleNativeLinuxAarch64)\n }\n buildInfo.os.isLinux && buildInfo.targetArch == \"amd64\" -> {\n if (buildInfo.musl) wraps(assembleNativeAlpineLinuxAmd64)\n else wraps(assembleNativeLinuxAmd64)\n }\n buildInfo.os.isWindows && buildInfo.targetArch == \"amd64\" -> {\n wraps(assembleNativeWindowsAmd64)\n }\n else -> {\n doLast {\n throw GradleException(\n \"Cannot build targeting ${buildInfo.os.name}/${buildInfo.targetArch} with musl=${buildInfo.musl}\"\n )\n }\n }\n }\n }\n\nval testNative by\n tasks.registering {\n group = \"verification\"\n dependsOn(assembleNative)\n\n if (!buildInfo.isCrossArchSupported && buildInfo.isCrossArch) {\n throw GradleException(\"Cross-arch builds are not supported on ${buildInfo.os.name}\")\n }\n\n when {\n buildInfo.os.isMacOsX && buildInfo.targetArch == \"aarch64\" -> {\n dependsOn(testNativeMacOsAarch64)\n }\n buildInfo.os.isMacOsX && buildInfo.targetArch == \"amd64\" -> {\n dependsOn(testNativeMacOsAmd64)\n }\n buildInfo.os.isLinux && buildInfo.targetArch == \"aarch64\" -> {\n dependsOn(testNativeLinuxAarch64)\n }\n buildInfo.os.isLinux && buildInfo.targetArch == \"amd64\" -> {\n if (buildInfo.musl) dependsOn(testNativeAlpineLinuxAmd64)\n else dependsOn(testNativeLinuxAmd64)\n }\n buildInfo.os.isWindows && buildInfo.targetArch == \"amd64\" -> {\n dependsOn(testNativeWindowsAmd64)\n }\n else -> {\n doLast {\n throw GradleException(\n \"Cannot build targeting ${buildInfo.os.name}/${buildInfo.targetArch} with musl=${buildInfo.musl}\"\n )\n }\n }\n }\n }\n\nval checkNative by\n tasks.registering {\n group = \"verification\"\n dependsOn(testNative)\n }\n\nval buildNative by\n tasks.registering {\n group = \"build\"\n dependsOn(checkNative)\n }\n" }, { "path": "buildSrc/src/main/kotlin/pklPublishLibrary.gradle.kts", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nplugins {\n `maven-publish`\n signing\n}\n\npublishing {\n publications {\n components.findByName(\"java\")?.let { javaComponent ->\n create(\"library\") { from(javaComponent) }\n }\n }\n}\n\nconfigurePklPomMetadata()\n\nconfigurePomValidation()\n\nconfigurePklSigning()\n\nartifacts {\n project.tasks.findByName(\"javadocJar\")?.let { archives(it) }\n project.tasks.findByName(\"sourcesJar\")?.let { archives(it) }\n}\n" }, { "path": "buildSrc/src/main/kotlin/pklSpotlessFormat.gradle.kts", "content": "/*\n * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nplugins { id(\"com.diffplug.spotless\") }\n\nval pklFormatter by configurations.creating\n\ndependencies { pklFormatter(rootProject.project(\"pkl-formatter\")) }\n\nspotless {\n format(\"pkl\") {\n target(\"**/*.pkl\")\n addStep(PklFormatterStep(pklFormatter).create())\n licenseHeaderFile(\n rootProject.file(\"buildSrc/src/main/resources/license-header.line-comment.txt\"),\n \"/// \",\n )\n // disable ratcheting for Pkl sources\n // make any change to pkl-formatter reformat the stdlib\n ratchetFrom = null\n }\n}\n\nfor (taskName in\n listOf(\"spotlessPkl\", \"spotlessPklApply\", \"spotlessPklCheck\", \"spotlessPklDiagnose\")) {\n tasks.named(taskName) { dependsOn(\":pkl-formatter:assemble\") }\n}\n" }, { "path": "buildSrc/src/main/resources/license-header.line-comment.txt", "content": "//===----------------------------------------------------------------------===//\n// Copyright © $YEAR Apple Inc. and the Pkl project authors. All rights reserved.\n//\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n// https://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n//===----------------------------------------------------------------------===//\n\n" }, { "path": "buildSrc/src/main/resources/license-header.star-block.txt", "content": "/*\n * Copyright © $YEAR Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n" }, { "path": "docs/antora.yml", "content": "name: main\ntitle: Main Project\nversion: 0.32.0-dev\nprerelease: true\nnav:\n- nav.adoc\n" }, { "path": "docs/docs.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension\n\nplugins {\n pklAllProjects\n pklKotlinTest\n}\n\nsourceSets {\n test {\n java {\n srcDir(file(\"modules/pkl-core/examples\"))\n srcDir(file(\"modules/pkl-config-java/examples\"))\n srcDir(file(\"modules/java-binding/examples\"))\n }\n val kotlin = project.extensions.getByType().sourceSets[name].kotlin\n kotlin.srcDir(file(\"modules/kotlin-binding/examples\"))\n }\n}\n\ndependencies {\n testImplementation(projects.pklCore)\n testImplementation(projects.pklConfigJava)\n testImplementation(projects.pklConfigKotlin)\n testImplementation(projects.pklCommonsTest)\n testImplementation(projects.pklParser)\n testImplementation(libs.junitEngine)\n}\n\ntasks.test {\n inputs\n .files(fileTree(\"modules\").matching { include(\"**/pages/*.adoc\") })\n .withPropertyName(\"asciiDocFiles\")\n .withPathSensitivity(PathSensitivity.RELATIVE)\n}\n" }, { "path": "docs/gradle.lockfile", "content": "# This is a Gradle generated file for dependency locking.\n# Manual edits can break the build and are not advised.\n# This file is expected to be part of source control.\ncom.github.ben-manes.caffeine:caffeine:2.9.3=swiftExportClasspathResolvable\ncom.google.errorprone:error_prone_annotations:2.28.0=swiftExportClasspathResolvable\nio.github.java-diff-utils:java-diff-utils:4.12=kotlinInternalAbiValidation\nio.leangen.geantyref:geantyref:1.3.16=testRuntimeClasspath\nio.opentelemetry:opentelemetry-api:1.41.0=swiftExportClasspathResolvable\nio.opentelemetry:opentelemetry-context:1.41.0=swiftExportClasspathResolvable\nnet.bytebuddy:byte-buddy:1.17.7=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.apiguardian:apiguardian-api:1.1.2=testCompileClasspath,testImplementationDependenciesMetadata\norg.assertj:assertj-core:3.27.6=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.bouncycastle:bcpg-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcpkix-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcprov-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcutil-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.checkerframework:checker-qual:3.43.0=swiftExportClasspathResolvable\norg.graalvm.polyglot:polyglot:25.0.0=testRuntimeClasspath\norg.graalvm.sdk:collections:25.0.0=testRuntimeClasspath\norg.graalvm.sdk:graal-sdk:25.0.0=testRuntimeClasspath\norg.graalvm.sdk:nativeimage:25.0.0=testRuntimeClasspath\norg.graalvm.sdk:word:25.0.0=testRuntimeClasspath\norg.graalvm.truffle:truffle-api:25.0.0=testRuntimeClasspath\norg.jetbrains.kotlin:abi-tools-api:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:abi-tools:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-build-tools-api:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-build-tools-impl:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-compiler-runner:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-client:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-klib-commonizer-embeddable:2.2.20=kotlinKlibCommonizerClasspath\norg.jetbrains.kotlin:kotlin-metadata-jvm:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-native-prebuilt:2.0.21=kotlinNativeBundleConfiguration\norg.jetbrains.kotlin:kotlin-reflect:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-script-runtime:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-scripting-common:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-compiler-impl-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-jvm:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-stdlib-jdk7:2.2.20=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib-jdk8:2.2.20=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:swift-export-embeddable:2.2.20=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.8.0=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-bom:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core-jvm:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3=swiftExportClasspathResolvable\norg.jetbrains:annotations:13.0=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable,testCompileClasspath,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-api:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-engine:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-params:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-commons:1.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-engine:1.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-launcher:1.14.0=testRuntimeClasspath\norg.junit:junit-bom:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.msgpack:msgpack-core:0.9.8=testRuntimeClasspath\norg.opentest4j:opentest4j:1.3.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.organicdesign:Paguro:3.10.3=testRuntimeClasspath\norg.snakeyaml:snakeyaml-engine:2.10=testRuntimeClasspath\nempty=annotationProcessor,apiDependenciesMetadata,compileClasspath,compileOnlyDependenciesMetadata,implementationDependenciesMetadata,intransitiveDependenciesMetadata,kotlinCompilerPluginClasspath,kotlinNativeCompilerPluginClasspath,kotlinScriptDefExtensions,runtimeClasspath,testAnnotationProcessor,testApiDependenciesMetadata,testCompileOnlyDependenciesMetadata,testIntransitiveDependenciesMetadata,testKotlinScriptDefExtensions\n" }, { "path": "docs/modules/ROOT/pages/community.adoc", "content": "= Community\n:uri-github-issue: https://github.com/apple/pkl/issues\n:uri-github-discussions: https://github.com/apple/pkl/discussions\n\nWe'd love to hear from you!\n\n* Create an {uri-github-issue}[issue]\n* Ask questions on {uri-github-discussions}[GitHub Discussions]\n" }, { "path": "docs/modules/ROOT/pages/evolution-and-roadmap.adoc", "content": "= Evolution and Roadmap\n\n:uri-pkl-roadmap: https://github.com/orgs/apple/projects/12/views/1\n:uri-pkl-evolution: https://github.com/apple/pkl-evolution\n\n== Evolution\n\nSometimes, a change to Pkl is large enough that it makes sense to create a proposal for the change so that it can be discussed in detail and vetted.\n\nPkl has a process for managing such designs in a repository called {uri-pkl-evolution}[Pkl Evolution].\n\n== Roadmap\n\nTo discover what might be coming in future versions, reference the {uri-pkl-roadmap}[Pkl Roadmap] project on GitHub.\n\nThe roadmap describes estimates.\nThe Pkl team aims to cut a release in February, June, and October of each year.\nIf an item is not complete by the release cutoff date, the roadmap item may be bumped to the next release.\n\nAdditionally, as priorities change, it is possible that items can be moved around or backlogged.\n" }, { "path": "docs/modules/ROOT/pages/examples.adoc", "content": "= Examples\n\n:uri-github-apple: https://github.com/apple\n:uri-jvm-examples: {uri-github-apple}/pkl-jvm-examples\n:uri-go-examples: {uri-github-apple}/pkl-go-examples\n:uri-swift-examples: {uri-github-apple}/pkl-swift-examples\n:uri-k8s-examples: {uri-github-apple}/pkl-k8s-examples\n\nFor ready-to-go examples with full source code, see the various repositories that are available for you.\n\n* {uri-jvm-examples}[pkl-jvm-examples] -- for using Pkl within the JVM\n* {uri-swift-examples}[pkl-swift-examples] -- for using Pkl with Swift\n* {uri-go-examples}[pkl-go-examples] -- for using Pkl with Go\n* {uri-k8s-examples}[pkl-k8s-examples] -- for using Pkl with Kubernetes\n" }, { "path": "docs/modules/ROOT/pages/index.adoc", "content": "= User Manual\ninclude::../partials/component-attributes.adoc[]\n\nQuick Links:\nxref:pkl-cli:index.adoc#installation[Installation] \n| xref:language-reference:index.adoc[Language Reference]\n| https://pkl-lang.org/package-docs/pkl/current/index.html[Standard Library]\n\nPkl -- pronounced _Pickle_ -- is an embeddable configuration language which provides rich support for data templating and validation.\nIt can be used from the command line, integrated in a build pipeline, or embedded in a program.\nPkl scales from small to large, simple to complex, ad-hoc to repetitive configuration tasks.\n\nxref:introduction:index.adoc[Introduction]:: Why we created Pkl and what it can do for you.\nxref:language.adoc[Language]:: Get to know the language and standard library.\nxref:language-bindings.adoc[Bindings]:: Libraries for embedding Pkl into general-purpose languages.\nxref:tools.adoc[Tools]:: CLI, Gradle plugin, code generators, and other tools.\nlink:{uri-pkl-examples-repo}[Examples]:: Ready-to-go examples with full source code.\nxref:release-notes:index.adoc[Release Notes]:: What's new in each release.\n" }, { "path": "docs/modules/ROOT/pages/integrations.adoc", "content": "= Framework Integrations\n\n* xref:spring:ROOT:index.adoc[Spring (Boot) Integration]\n" }, { "path": "docs/modules/ROOT/pages/language-bindings.adoc", "content": "= Language Bindings\n\n* xref:java-binding:index.adoc[Java]\n* xref:kotlin-binding:index.adoc[Kotlin]\n* xref:swift:ROOT:index.adoc[Swift]\n* xref:go:ROOT:index.adoc[Go]\n* xref:bindings-specification:index.adoc[Specification]\n** xref:bindings-specification:message-passing-api.adoc[Message Passing API]\n** xref:bindings-specification:binary-encoding.adoc[Pkl Binary Encoding]\n" }, { "path": "docs/modules/ROOT/pages/language.adoc", "content": "= Language\n\n* xref:language-tutorial:index.adoc[Tutorial]\n* xref:language-reference:index.adoc[Language Reference]\n* xref:standard-library.adoc[Standard Library]\n" }, { "path": "docs/modules/ROOT/pages/resources.adoc", "content": "= Resources\ninclude::../partials/component-attributes.adoc[]\n\nThere's more to explore!\n\n* Visit Pkl's repositories on https://github.com/apple?q=pkl[GitHub]\n* Browse the standard library's https://pkl-lang.org/package-docs/pkl/{pkl-version}/[API Docs]\n" }, { "path": "docs/modules/ROOT/pages/standard-library.adoc", "content": "= Standard Library\ninclude::../partials/component-attributes.adoc[]\n\nThe standard library is a set of Pkl modules, versioned and distributed together with the language.\nIt is documented in the link:{uri-pkl-stdlib-docs-index}[API Docs].\n\nTo import a standard library module, use `import \"pkl:\"`.\nFor example, `import \"pkl:json\"` imports the `pkl.json` module.\n\nThe `pkl.base` module defines the most fundamental properties, methods, and classes for using Pkl.\nIts members are automatically available in every module and hence, it does not need to be imported.\n\nThe default module allowlist (`--allowed-modules`) grants access to all standard library modules.\n" }, { "path": "docs/modules/ROOT/pages/tools.adoc", "content": "= Tools\ninclude::ROOT:partial$component-attributes.adoc[]\n\n* xref:pkl-cli:index.adoc[CLI]\n* xref:pkl-doc:index.adoc[Pkldoc]\n* xref:pkl-gradle:index.adoc[Gradle Plugin]\n* Editor support\n** xref:intellij:ROOT:index.adoc[IntelliJ]\n** xref:vscode:ROOT:index.adoc[VSCode]\n** xref:neovim:ROOT:index.adoc[Neovim]\n" }, { "path": "docs/modules/ROOT/partials/component-attributes.adoc", "content": "// TODO: move to antora.yml once supported\n\n// the following attributes must be updated immediately before a release\n\n// pkl version corresponding to current git commit without -dev suffix or git hash\n:pkl-version-no-suffix: 0.32.0\n// tells whether pkl version corresponding to current git commit\n// is a release version (:is-release-version: '') or dev version (:!is-release-version:)\n:!is-release-version:\n\n// the remaining attributes do not need to be updated regularly\n\n:pkl-version: {pkl-version-no-suffix}-dev\nifdef::is-release-version[]\n:pkl-version: {pkl-version-no-suffix}\nendif::[]\n\n// use non-unique snapshot version because we have no way to determine unique snapshot version here\n:pkl-artifact-version: {pkl-version-no-suffix}-SNAPSHOT\nifdef::is-release-version[]\n:pkl-artifact-version: {pkl-version}\nendif::[]\n\n:uri-maven-docsite: https://central.sonatype.com\n\n:uri-snapshot-repo: https://central.sonatype.com/repository/maven-snapshots\n\n:uri-maven-repo: https://central.sonatype.com/repository/maven-snapshots\nifdef::is-release-version[]\n:uri-maven-repo: https://repo1.maven.org/maven2\nendif::[]\n\n:symbolic-version-name: latest\nifdef::is-release-version[]\n:symbolic-version-name: current\nendif::[]\n:uri-pkl-docs-base: https://pkl-lang.org/package-docs\n:uri-pkl-stdlib-docs-base: {uri-pkl-docs-base}/pkl\n:uri-pkl-stdlib-docs: {uri-pkl-stdlib-docs-base}/{pkl-version}\n:uri-pkl-stdlib-docs-index: {uri-pkl-stdlib-docs}/\n\n:github-branch: main\nifdef::is-release-version[]\n:github-branch: {pkl-version-no-suffix}\nendif::[]\n:uri-github-tree: https://github.com/apple/pkl/tree/{github-branch}\n:uri-pkl-stdlib-sources: {uri-github-tree}/stdlib\n\n:github-releases-base: https://github.com/apple/pkl/releases\n:github-releases: {github-releases-base}/download/{pkl-artifact-version}\n\n:uri-pkl-core-main-sources: {uri-github-tree}/pkl-core/src/main/java/org/pkl/core\n:uri-pkl-cli-main-sources: {uri-github-tree}/pkl-cli/src/main/kotlin/org/pkl/cli\n:uri-pkl-doc-main-sources: {uri-github-tree}/pkl-doc/src/main/kotlin/org/pkl/doc\n\n// This attribute is used as language for Pkl code blocks.\n// It can then be mapped to different languages in different environments (e.g., IntelliJ vs. Antora).\n:pkl: pkl\n:pkl-expr: pkl expression\n\n:uri-pkl-examples-repo: https://github.com/apple/pkl-jvm-examples\n:uri-pkl-examples-tree: {uri-pkl-examples-repo}/tree/main\n:uri-build-eval-example: {uri-pkl-examples-tree}/build-eval\n:uri-codegen-java-example: {uri-pkl-examples-tree}/codegen-java\n:uri-codegen-kotlin-example: {uri-pkl-examples-tree}/codegen-kotlin\n:uri-config-java-example: {uri-pkl-examples-tree}/config-java\n:uri-config-kotlin-example: {uri-pkl-examples-tree}/config-kotlin\n:uri-pkldoc-example: {uri-pkl-examples-tree}/pkldoc\n\n:uri-stdlib-baseModule: {uri-pkl-stdlib-docs}/base\n:uri-stdlib-CommandModule: {uri-pkl-stdlib-docs}/Command\n:uri-stdlib-analyzeModule: {uri-pkl-stdlib-docs}/analyze\n:uri-stdlib-jsonnetModule: {uri-pkl-stdlib-docs}/jsonnet\n:uri-stdlib-reflectModule: {uri-pkl-stdlib-docs}/reflect\n:uri-stdlib-mathModule: {uri-pkl-stdlib-docs}/math\n:uri-stdlib-xmlModule: {uri-pkl-stdlib-docs}/xml\n:uri-stdlib-protobufModule: {uri-pkl-stdlib-docs}/protobuf\n:uri-stdlib-pklbinaryModule: {uri-pkl-stdlib-docs}/pklbinary\n:uri-stdlib-yamlModule: {uri-pkl-stdlib-docs}/yaml\n:uri-stdlib-YamlParser: {uri-stdlib-yamlModule}/Parser\n:uri-stdlib-evaluatorSettingsModule: {uri-pkl-stdlib-docs}/EvaluatorSettings\n:uri-stdlib-evaluatorSettingsHttpClass: {uri-stdlib-evaluatorSettingsModule}/Http\n:uri-stdlib-Boolean: {uri-stdlib-baseModule}/Boolean\n:uri-stdlib-xor: {uri-stdlib-baseModule}/Boolean#xor()\n:uri-stdlib-implies: {uri-stdlib-baseModule}/Boolean#implies()\n:uri-stdlib-Any: {uri-stdlib-baseModule}/Any\n:uri-stdlib-String: {uri-stdlib-baseModule}/String\n:uri-stdlib-Collection: {uri-stdlib-baseModule}/Collection\n:uri-stdlib-StringToInt: {uri-stdlib-baseModule}/String#toInt()\n:uri-stdlib-Int: {uri-stdlib-baseModule}/Int\n:uri-stdlib-Float: {uri-stdlib-baseModule}/Float\n:uri-stdlib-Number: {uri-stdlib-baseModule}/Number\n:uri-stdlib-NaN: {uri-stdlib-baseModule}/#NaN\n:uri-stdlib-Infinity: {uri-stdlib-baseModule}/#Infinity\n:uri-stdlib-isBetween: {uri-stdlib-baseModule}/Number#isBetween\n:uri-stdlib-isFinite: {uri-stdlib-baseModule}/Number#isFinite\n:uri-stdlib-Int8: {uri-stdlib-baseModule}/#Int8\n:uri-stdlib-Int16: {uri-stdlib-baseModule}/#Int16\n:uri-stdlib-Int32: {uri-stdlib-baseModule}/#Int32\n:uri-stdlib-UInt8: {uri-stdlib-baseModule}/#UInt8\n:uri-stdlib-UInt16: {uri-stdlib-baseModule}/#UInt16\n:uri-stdlib-UInt32: {uri-stdlib-baseModule}/#UInt32\n:uri-stdlib-UInt: {uri-stdlib-baseModule}/#UInt\n:uri-stdlib-Uri: {uri-stdlib-baseModule}/#Uri\n:uri-stdlib-matches: {uri-stdlib-baseModule}/String#matches()\n:uri-stdlib-Null: {uri-stdlib-baseModule}/Null\n:uri-stdlib-ifNonNull: {uri-stdlib-baseModule}/Null#ifNonNull()\n:uri-stdlib-List: {uri-stdlib-baseModule}/List\n:uri-stdlib-Set: {uri-stdlib-baseModule}/Set\n:uri-stdlib-Map: {uri-stdlib-baseModule}/Map\n:uri-stdlib-Listing: {uri-stdlib-baseModule}/Listing\n:uri-stdlib-Listing-default: {uri-stdlib-baseModule}/Listing#default\n:uri-stdlib-Listing-isDistinct: {uri-stdlib-baseModule}/Listing#isDistinct\n:uri-stdlib-Listing-isDistinctBy: {uri-stdlib-baseModule}/Listing#isDistinctBy()\n:uri-stdlib-Mapping: {uri-stdlib-baseModule}/Mapping\n:uri-stdlib-Mapping-default: {uri-stdlib-baseModule}/Mapping#default\n:uri-stdlib-Duration: {uri-stdlib-baseModule}/Duration\n:uri-stdlib-Duration-value: {uri-stdlib-baseModule}/Duration#value\n:uri-stdlib-Duration-unit: {uri-stdlib-baseModule}/Duration#unit\n:uri-stdlib-DurationUnit: {uri-stdlib-baseModule}/#DurationUnit\n:uri-stdlib-DataSize: {uri-stdlib-baseModule}/DataSize\n:uri-stdlib-DataSize-value: {uri-stdlib-baseModule}/DataSize#value\n:uri-stdlib-DataSize-unit: {uri-stdlib-baseModule}/DataSize#unit\n:uri-stdlib-DataSizeUnit: {uri-stdlib-baseModule}/#DataSizeUnit\n:uri-stdlib-Dynamic: {uri-stdlib-baseModule}/Dynamic\n:uri-stdlib-Dynamic-toTyped: {uri-stdlib-baseModule}/Dynamic#toTyped()\n:uri-stdlib-Typed: {uri-stdlib-baseModule}/Typed\n:uri-stdlib-Regex: {uri-stdlib-baseModule}/Regex\n:uri-stdlib-Regex-method: {uri-stdlib-baseModule}/#Regex()\n:uri-stdlib-Regex-match: {uri-stdlib-baseModule}/Regex#match\n:uri-stdlib-RegexMatch: {uri-stdlib-baseModule}/RegexMatch\n:uri-stdlib-Pair: {uri-stdlib-baseModule}/Pair\n:uri-stdlib-IntSeq: {uri-stdlib-baseModule}/IntSeq\n:uri-stdlib-Class: {uri-stdlib-baseModule}/Class\n:uri-stdlib-TypeAlias: {uri-stdlib-baseModule}/TypeAlias\n:uri-stdlib-Deprecated: {uri-stdlib-baseModule}/Deprecated\n:uri-stdlib-BaseValueRenderer: {uri-stdlib-baseModule}/BaseValueRenderer\n:uri-stdlib-ValueRenderer: {uri-stdlib-baseModule}/ValueRenderer\n:uri-stdlib-BytesRenderer: {uri-stdlib-baseModule}/BytesRenderer\n:uri-stdlib-YamlRenderer: {uri-stdlib-baseModule}/YamlRenderer\n:uri-stdlib-PcfRenderer-converters: {uri-stdlib-baseModule}/PcfRenderer#converters\n:uri-stdlib-Function: {uri-stdlib-baseModule}/Function\n:uri-stdlib-Function0: {uri-stdlib-baseModule}/Function0\n:uri-stdlib-Function1: {uri-stdlib-baseModule}/Function1\n:uri-stdlib-Function1-apply: {uri-stdlib-baseModule}/Function1#apply()\n:uri-stdlib-Function2: {uri-stdlib-baseModule}/Function2\n:uri-stdlib-Function3: {uri-stdlib-baseModule}/Function3\n:uri-stdlib-Function4: {uri-stdlib-baseModule}/Function4\n:uri-stdlib-Function5: {uri-stdlib-baseModule}/Function5\n:uri-stdlib-Bytes: {uri-stdlib-baseModule}/Bytes\n:uri-stdlib-Resource: {uri-stdlib-baseModule}/Resource\n:uri-stdlib-outputFiles: {uri-stdlib-baseModule}/ModuleOutput#files\n:uri-stdlib-FileOutput: {uri-stdlib-baseModule}/FileOutput\n:uri-stdlib-Annotation: {uri-stdlib-baseModule}/Annotation\n:uri-stdlib-ConvertProperty: {uri-stdlib-baseModule}/ConvertProperty\n:uri-stdlib-Command-Flag: {uri-stdlib-CommandModule}/Flag\n:uri-stdlib-Command-BooleanFlag: {uri-stdlib-CommandModule}/BooleanFlag\n:uri-stdlib-Command-CountedFlag: {uri-stdlib-CommandModule}/CountedFlag\n:uri-stdlib-Command-Argument: {uri-stdlib-CommandModule}/Argument\n:uri-stdlib-Command-Import: {uri-stdlib-CommandModule}/Import\n\n:uri-messagepack: https://msgpack.org/index.html\n:uri-messagepack-spec: https://github.com/msgpack/msgpack/blob/master/spec.md\n\n:uri-pkl-roadmap: https://github.com/orgs/apple/projects/12/views/1\n\n// TODO: figure out what the correct URL should be\n:uri-sonatype-snapshot-download: https://s01.oss.sonatype.org/service/local/artifact/maven/redirect?r=snapshots&g=org.pkl-lang&v={pkl-artifact-version}\n" }, { "path": "docs/modules/bindings-specification/pages/binary-encoding.adoc", "content": "= `pkl-binary` Encoding\ninclude::ROOT:partial$component-attributes.adoc[]\ninclude::partial$component-attributes.adoc[]\n\n:uri-pkl-core-Evaluator: {uri-pkl-core-main-sources}/Evaluator.java\n\nPkl values can be encoded into a binary format called \"pkl-binary\".\nThis format is a lossless serialization of the underlying Pkl values.\n\nPkl code can be rendered into this format using the {uri-stdlib-pklbinaryModule}[pkl:pklbinary] standard library module.\n\nAlternatively, 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].\n\nThe binary format is uses link:{uri-messagepack}[MessagePack] encoding.\n\n== Primitives\n\nAll Pkl primitives turn into their respective MessagePack primitive.\n\n|===\n|Pkl Type|MessagePack format\n\n|link:{uri-stdlib-Int}[Int]\n|link:{uri-messagepack-int}[int]\n\n|link:{uri-stdlib-Float}[Float]\n|link:{uri-messagepack-float}[float]\n\n|link:{uri-stdlib-String}[String]\n|link:{uri-messagepack-str}[string]\n\n|link:{uri-stdlib-Boolean}[Boolean]\n|link:{uri-messagepack-bool}[bool]\n\n|link:{uri-stdlib-Null}[Null]\n|link:{uri-messagepack-nil}[nil]\n|===\n\nNOTE: Pkl integers are encoded into the smallest int type that the number will fit into.\nFor example, value `8` gets encoded as MessagePack `int8` format.\n\n== Non-primitives\n\nAll non-primitive values are encoded as MessagePack arrays.\nThe first slot of the array designates the value's type.\nThe remaining slots have fixed meanings depending on the type.\nAdditional slots may be added to types in future Pkl releases. Decoders *must* be designed to defensively discard values beyond the number of known slots for a type or provide meaningful error messages.\n\nThe array's length is the number of slots that are filled. For example, xref:{uri-stdlib-List}[List] is encoded as an MessagePack array with two elements.\n\n|===\n|Pkl type |Slot 1 2+|Slot 2 2+|Slot 3 2+|Slot 4\n\n||code |type |description |type |description |type |description\n\n|link:{uri-stdlib-Typed}[Typed], link:{uri-stdlib-Dynamic}[Dynamic]\n|`0x01`\n|link:{uri-messagepack-str}[str]\n|<>\n|link:{uri-messagepack-str}[str]\n|Enclosing module URI\n|link:{uri-messagepack-array}[array]\n|Array of <>\n\n|link:{uri-stdlib-Map}[Map]\n|`0x02`\n|link:{uri-messagepack-map}[map]\n|Map of `` to ``\n|\n|\n|\n|\n\n|link:{uri-stdlib-Mapping}[Mapping]\n|`0x03`\n|link:{uri-messagepack-map}[map]\n|Map of `` to ``\n|\n|\n|\n|\n\n|link:{uri-stdlib-List}[List]\n|`0x04`\n|link:{uri-messagepack-array}[array]\n|Array of ``\n|\n|\n|\n|\n\n|link:{uri-stdlib-Listing}[Listing]\n|`0x05`\n|link:{uri-messagepack-array}[array]\n|Array of ``\n|\n|\n|\n|\n\n|link:{uri-stdlib-Set}[Set]\n|`0x06`\n|link:{uri-messagepack-array}[array]\n|Array of ``\n|\n|\n|\n|\n\n|link:{uri-stdlib-Duration}[Duration]\n|`0x07`\n|{uri-messagepack-float}[float64]\n|Duration value\n|link:{uri-messagepack-str}[str]\n|link:{uri-stdlib-DurationUnit}[Duration unit] (`\"ns\"`, `\"ms\"`, etc.)\n|\n|\n\n|link:{uri-stdlib-DataSize}[DataSize]\n|`0x08`\n|link:{uri-messagepack-float}[float64]\n|Value (float64)\n|link:{uri-messagepack-str}[str]\n|link:{uri-stdlib-DataSizeUnit}[DataSize unit] (`\"b\"`, `\"kb\"`, etc.)\n|\n|\n\n|link:{uri-stdlib-Pair}[Pair]\n|`0x09`\n|``\n|First value\n|``\n|Second value\n|\n|\n\n|link:{uri-stdlib-IntSeq}[IntSeq]\n|`0x0A`\n|link:{uri-messagepack-int}[int]\n|Start\n|link:{uri-messagepack-int}[int]\n|End\n|link:{uri-messagepack-int}[int]\n|Step\n\n|link:{uri-stdlib-Regex}[Regex]\n|`0x0B`\n|link:{uri-messagepack-str}[str]\n|Regex string representation\n|\n|\n|\n|\n\n|link:{uri-stdlib-Class}[Class]\n|`0x0C`\n|link:{uri-messagepack-str}[str]\n|<>\n|link:{uri-messagepack-str}[str]\n|Module URI\n|\n|\n\n|link:{uri-stdlib-TypeAlias}[TypeAlias]\n|`0x0D`\n|link:{uri-messagepack-str}[str]\n|<>\n|link:{uri-messagepack-str}[str]\n|Module URI\n|\n|\n\n|link:{uri-stdlib-Function}[Function]\n|`0x0E`\n|\n|\n|\n|\n|\n|\n\n|link:{uri-stdlib-Bytes}[Bytes]\n|`0x0F`\n|link:{uri-messagepack-bin}[bin]\n|Binary contents\n|\n|\n|\n|\n|===\n\n[[type-name-encoding]]\n[NOTE]\n====\nType names have specific encoding rules:\n\n* When the module URI is `pkl:base`:\n** If the type name is `ModuleClass`, this type represents the module class of `pkl:base`.\n** Otherwise, the type name corresponds to a type in `pkl:base`.\n* For all other module URIs:\n** When the type name contains `\\#`, the string after the `#` character corresponds to a type in that module. The string before the `#` is the name of the module.\n** Otherwise, the type name is the name of the module and represents the class of the module.\n====\n\n[[object-members]]\n== Object Members\n\nLike non-primitive values, object members are encoded as MessagePack arrays, where the first slot designates the value's type.\n\n|===\n|Member type |Slot 1 2+|Slot 2 2+|Slot 3\n\n| |code |type |description |type |description\n\n|Property\n|`0x10`\n|link:{uri-messagepack-str}[str]\n|key\n|``\n|property value\n\n|Entry\n|`0x11`\n|``\n|entry key\n|``\n|entry value\n\n|Element\n|`0x12`\n|link:{uri-messagepack-int}[int]\n|index\n|``\n|element value\n|===\n" }, { "path": "docs/modules/bindings-specification/pages/index.adoc", "content": "= Language Binding Specification\n\n:uri-pkl-go-github: https://github.com/apple/pkl-go\n:uri-pkl-swift-github: https://github.com/apple/pkl-swift\n\nPkl can be embedded within any host application.\nThe host application has access to low level controls.\nIt is able to manage the lifecycle of evaluators, as well as provide custom modules and resources to Pkl.\n\nCurrently, Pkl must be embedded as a child process, by shelling out to the CLI using the xref:pkl-cli:index.adoc#command-server[`pkl server`] command. In the future, a C library will also be provided.\n\nWhen embedded, communication between a host application and Pkl happens via message passing.\nThe message passing specification can be found in xref:message-passing-api.adoc[].\n\nFor examples of language bindings in practice, review the link:{uri-pkl-go-github}[pkl-go], or the link:{uri-pkl-swift-github}[pkl-swift] codebases.\n\nNOTE: Pkl's Java and Kotlin libraries binds to Pkl directly, and do not use message passing.\n\n== Features of a language binding\n\nA language binding for Pkl should generally have the following components:\n\n. A client that spawns `pkl server`, and talks to it using message passing.\n. A deserializer that turns xref:binary-encoding.adoc[pkl binary encoding] into a structure in the host language.\n. A code generator that transforms Pkl schemas into schemas written in the host language.\n The code generator is mostly written in Pkl, with a lightweight executable that acts as the glue layer.\n For examples of code generators, consult link:{uri-pkl-go-github}/tree/main/codegen[pkl-go] and link:{uri-pkl-swift-github}/tree/main/codegen[pkl-swift].\n\n== Sample flow\n\nHere is a sample flow for evaluating a module with the following contents:\n\n.\\file:///path/to/myModule.pkl\n[source,{pkl}]\n----\nmodule MyModule\n\ntheModules = import*(\"customfs:/*.pkl\")\n----\n\n. Client sends xref:message-passing-api.adoc#create-evaluator-request[Create Evaluator Request], including `customfs` as a custom module reader.\n+\n[source,json]\n----\n[\n 0x20,\n {\n \"requestId\": 135,\n \"allowedModules\": [\"pkl:\", \"repl:\", \"file:\", \"customfs:\"],\n \"clientModuleReaders\": [\n {\n \"scheme\": \"customfs\",\n \"hasHierarchicalUris\": true,\n \"isGlobbable\": true,\n \"isLocal\": true\n }\n ]\n }\n]\n----\n. Server sends xref:message-passing-api.adoc#create-evaluator-response[Create Evaluator Response], with an evaluator id.\n+\n[source,json]\n----\n[\n 0x21,\n {\n \"requestId\": 135,\n \"evaluatorId\": -135901\n }\n]\n----\n. Client sends xref:message-passing-api.adoc#evaluate-request[Evaluate Request], providing the module's URI.\n+\n[source,json]\n----\n[\n 0x23,\n {\n \"requestId\": 9805131,\n \"evaluatorId\": -13901,\n \"moduleUri\": \"file:///path/to/myModule.pkl\"\n }\n]\n----\n. During evaluation, server evaluates `import*(\"customfs:/*.pkl\")`, and sends xref:message-passing-api.adoc#list-modules-request[List Modules Request].\n+\n[source,json]\n----\n[\n 0x2c,\n {\n \"requestId\": -6478924,\n \"evaluatorId\": -13901,\n \"uri\": \"customfs:/\"\n }\n]\n----\n. Client responds with xref:message-passing-api.adoc#list-modules-response[List Modules Response].\nIn our pretend scenario, there is only one file; `foo.pkl`.\n+\n[source,json]\n----\n[\n 0x2d,\n {\n \"requestId\": -6478924,\n \"evaluatorId\": -13901,\n \"pathElements\": [\n {\n \"name\": \"foo.pkl\",\n \"isDirectory\": false\n }\n ]\n }\n]\n----\n. Server sends xref:message-passing-api.adoc#read-module-request[Read Module Request] to read `foo.pkl`.\n+\n[source,json]\n----\n[\n 0x28,\n {\n \"requestId\": 36408291,\n \"evaluatorId\": -13901,\n \"uri\": \"customfs:/foo.pkl\"\n }\n]\n----\n. Client responds with the module's contents\n+\n[source,json]\n----\n[\n 0x29,\n {\n \"requestId\": 36408291,\n \"evaluatorId\": -13901,\n \"contents\": \"foo = 1\"\n }\n]\n----\n. Server finishes evaluation, and responds with the xref:message-passing-api.adoc#evaluate-response[Evaluate Response].\n+\n[source,json]\n----\n[\n 0x24,\n {\n \"requestId\": 9805131,\n \"evaluatorId\": -13901,\n \"result\": \n }\n]\n----\n. Client sends xref:message-passing-api.adoc#close-evaluator[Close Evaluator].\n+\n[source,json]\n----\n[\n 0x22,\n {\n \"evaluatorId\": -13901\n }\n]\n----\n\n== Debug logs\n\nSet the env var `PKL_DEBUG=1` to enable more verbose logging from Pkl.\nIt is recommended that clients also use this environment variable to enable debug logs of their own.\n\n" }, { "path": "docs/modules/bindings-specification/pages/message-passing-api.adoc", "content": "= Message Passing API\n\ninclude::ROOT:partial$component-attributes.adoc[]\ninclude::partial$component-attributes.adoc[]\n\nAll messages are encoded in link:{uri-messagepack}[MessagePack], as an array with two elements.\n\nThe first element of the array is a code that designates the message's type, encoded as an int.\nThe second element of the array is the message body, encoded as a map.\n\nMessages are passed between the _client_ and the _server_.\nWhen hosting Pkl (for example, the Swift application when using pkl-swift), the _client_ is the host program and the _server_ is the entity that provides controls for interacting with Pkl.\nWhen implementing an xref:language-reference:index.adoc#external-readers[external reader], the _client_ is the external reader process and the _server_ is the Pkl evaluator.\n\nFor example, in JSON representation:\n\n[source,json]\n----\n[\n 1, // <1>\n { \"someKey\": \"someValue\" } // <2>\n]\n----\n<1> Code indicating message type\n<2> Message body\n\n== Message types\n\n[[client-message]]\n=== Client Message\nA message passed from the client to the server.\n\n[[server-message]]\n=== Server Message\nA message passed from the server to the client.\n\n[[request-message]]\n=== Request Message\nA message sent with a `requestId` value.\nThe `requestId` should be a unique number at the time of message send.\nThe other side is expected to respond with a <> with the same `requestId`.\n\n[[response-message]]\n=== Response Message\nA message that is the response to a <>.\nIt contains the same `requestId` of the request message.\n\n[[one-way-message]]\n=== One Way Message\n\nA fire-and-forget message where no response is expected.\n\n== Messages\n\nAll messages have their schema described in Pkl.\nA nullable type means that the property should be omitted (as opposed to the property's value being `nil`).\n\n[[create-evaluator-request]]\n=== Create Evaluator Request\n\nCode: `0x20` +\nType: <> <>\n\nCreate an evaluator with the provided evaluator settings.\nUpon creating the evaluator, the server sends back a <> message.\n\nSchema:\n[source,pkl]\n----\n/// A number identifying this request\nrequestId: Int\n\n/// Regex patterns to determine which modules are allowed for import.\n///\n/// API version of the CLI's `--allowed-modules` flag\nallowedModules: Listing?\n\n/// Regex patterns to determine which resources are allowed to be read.\n///\n/// API version of the CLI's `--allowed-resources` flag\nallowedResources: Listing?\n\n/// Register client-side module readers.\nclientModuleReaders: Listing?\n\n/// Register client-side resource readers.\nclientResourceReaders: Listing?\n\n/// Directories, ZIP archives, or JAR archives\n/// to search when resolving `modulepath:` URIs.\n///\n/// API version of the CLI's `--module-path` flag.\nmodulePaths: Listing?\n\n/// Environment variable to set.\n///\n/// API version of the CLI's `--env-var` flag.\nenv: Mapping?\n\n/// External properties to set.\n///\n/// API version of the CLI's `--properties` flag.\nproperties: Mapping?\n\n/// Duration, in seconds, after which evaluation of a source module will be timed out.\n///\n/// API version of the CLI's `--timeout` flag.\ntimeoutSeconds: Int?\n\n/// Restricts access to file-based modules and resources to those located under the root directory.\nrootDir: String?\n\n/// The cache directory for storing packages.\ncacheDir: String?\n\n/// The format to generate.\n///\n/// This sets the `pkl.outputFormat` external property.\noutputFormat: String?\n\n/// The project dependency settings.\nproject: Project?\n\n/// Configuration of outgoing HTTP(s) requests.\n///\n/// Added in Pkl 0.26.0.\nhttp: Http?\n\nclass ClientResourceReader {\n /// The URI scheme this reader is responsible for reading.\n scheme: String\n\n /// Tells whether the path part of this URI has a\n /// [hier-part](https://datatracker.ietf.org/doc/html/rfc3986#section-3).\n ///\n /// An example of a hierarchical URI is `file:///path/to/my/file`, where\n /// `/path/to/my/file` designates a nested path through the `/` character.\n ///\n /// An example of a non-hierarchical URI is `pkl.base`, where the `base` does not denote\n /// any form of hierarchy.\n hasHierarchicalUris: Boolean\n\n /// Tells whether this reader supports globbing.\n isGlobbable: Boolean\n}\n\nclass ClientModuleReader {\n /// The URI scheme this reader is responsible for reading.\n scheme: String\n\n /// Tells whether the path part of this URI has a\n /// [hier-part](https://datatracker.ietf.org/doc/html/rfc3986#section-3).\n ///\n /// An example of a hierarchical URI is `file:///path/to/my/file`, where\n /// `/path/to/my/file` designates a nested path through the `/` character.\n ///\n /// An example of a non-hierarchical URI is `pkl.base`, where the `base` does not denote\n /// any form of hierarchy.\n hasHierarchicalUris: Boolean\n\n /// Tells whether this reader supports globbing.\n isGlobbable: Boolean\n\n /// Tells whether the module is local to the system.\n ///\n /// A local resource that [hasHierarchicalUris] supports triple-dot imports.\n isLocal: Boolean\n}\n\nclass Project {\n type: \"local\"\n\n /// The canonical URI of this project's package\n packageUri: String?\n\n /// The URI pointing to the location of the project file.\n projectFileUri: String\n\n /// The dependencies of this project.\n dependencies: Mapping\n}\n\nclass RemoteDependency {\n type: \"remote\"\n\n /// The canonical URI of this dependency\n packageUri: String?\n\n /// The checksums of this remote dependency\n checksums: Checksums?\n}\n\nclass Checksums {\n /// The sha-256 checksum of this dependency's metadata.\n sha256: String\n}\n\nclass Http {\n /// PEM format certificates to trust when making HTTP requests.\n ///\n /// If [null], Pkl will trust its own built-in certificates.\n caCertificates: Bytes? // <1>\n\n /// Configuration of the HTTP proxy to use.\n ///\n /// If [null], uses the operating system's proxy configuration.\n proxy: Proxy?\n\n /// HTTP rewrites, from source prefix to target prefix.\n ///\n /// Each rewrite must start with `http://` or `https://`, and must end with `/`.\n rewrites: Mapping?\n}\n\n/// Settings that control how Pkl talks to HTTP proxies.\nclass Proxy {\n /// The proxy to use for HTTP(S) connections.\n ///\n /// At the moment, only HTTP proxies are supported.\n ///\n /// Example:\n /// ```\n /// address = \"http://my.proxy.example.com:5080\"\n /// ```\n address: Uri(startsWith(\"http://\"))?\n\n /// Hosts to which all connections should bypass a proxy.\n ///\n /// Values can be either hostnames, or IP addresses.\n /// IP addresses can optionally be provided using [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation).\n ///\n /// The only wildcard is `\"*\"`, which disables all proxying.\n ///\n /// A hostname matches all subdomains.\n /// For example, `example.com` matches `foo.example.com`, but not `fooexample.com`.\n /// A hostname that is prefixed with a dot matches the hostname itself,\n /// so `.example.com` matches `example.com`.\n ///\n /// Optionally, a port can be specified.\n /// If a port is omitted, all ports are matched.\n ///\n /// Example:\n ///\n /// ```\n /// noProxy {\n /// \"127.0.0.1\"\n /// \"169.254.0.0/16\"\n /// \"example.com\"\n /// \"localhost:5050\"\n /// }\n /// ```\n noProxy: Listing(isDistinct)\n}\n----\n<1> link:{uri-messagepack-bin}[bin format]\n\nExample:\n[source,json5]\n----\n[\n 0x20,\n {\n \"requestId\": 193501,\n \"allowedModules\": [\"pkl:\", \"repl:\"],\n \"allowedResources\": [\"file:\", \"package:\", \"projectpackage:\"]\n }\n]\n----\n\n[[create-evaluator-response]]\n=== Create Evaluator Response\n\nCode: `0x21` +\nType: <> <>\n\nThe response for a <>.\nIf the evaluator was created successfully, `evaluatorId` is set. Otherwise, `error` is set to the resulting error.\n\n[source,pkl]\n----\n/// A number identifying this request\nrequestId: Int\n\n/// A number identifying the created evaluator.\nevaluatorId: Int?\n\n/// A message detailing why the evaluator was not created.\nerror: String?\n----\n\n[[close-evaluator]]\n=== Close Evaluator\n\nCode: `0x22` +\nType: <> <>\n\nTells the Pkl server to close an evaluator, releasing any resources it may be holding.\n\n[source,pkl]\n----\n/// A number identifying this evaluator.\nevaluatorId: Int\n----\n\n[[evaluate-request]]\n=== Evaluate Request\n\nCode: `0x23` +\nType: <> <>\n\nEvaluate a module.\n\n[source,pkl]\n----\n/// A number identifying this request\nrequestId: Int\n\n/// A number identifying this evaluator.\nevaluatorId: Int\n\n/// The absolute URI of the module to be evaluated.\nmoduleUri: String\n\n/// The module's contents.\n///\n/// If [null], Pkl will load the module at runtime.\nmoduleText: String?\n\n/// The Pkl expression to be evaluated within the module.\n///\n/// If [null], evaluates the whole module.\nexpr: String?\n----\n\n[[evaluate-response]]\n=== Evaluate Response\n\nCode: `0x24` +\nType: <> <>\n\nThe server's response to <>.\nIf the evaluation is successful, the response is the Pkl value encoded in xref:binary-encoding.adoc[binary encoding].\n\n[source,pkl]\n----\n/// The requestId of the Evaluate request\nrequestId: Int\n\n/// A number identifying this evaluator.\nevaluatorId: Int\n\n/// The evaluation contents, if successful.\nresult: Bytes? // <1>\n\n/// A message detailing why evaluation failed.\nerror: String?\n----\n<1> xref:binary-encoding.adoc[Pkl Binary Encoding] in link:{uri-messagepack-bin}[bin format]\n\n[[log]]\n=== Log\n\nCode: `0x25` +\nType: <> <>\n\nTells the client to emit a log message, during the execution of a Pkl program.\nA log can occur through a xref:language-reference:index.adoc#debugging[trace()] expression, or through a warning (for example, when encountering a link:{uri-stdlib-Deprecated}[Deprecated] value.)\n\n[source,pkl]\n----\n/// A number identifying this evaluator.\nevaluatorId: Int\n\n/// A number identifying the log level.\n///\n/// - 0: trace\n/// - 1: warn\nlevel: Int(this == 0 || this == 1)\n\n/// The message to be logged\nmessage: String\n\n/// A string representing the source location within Pkl code producing this log output.\nframeUri: String\n----\n\n[[read-resource-request]]\n=== Read Resource Request\n\nCode: `0x26` +\nType: <> <>\n\nRead a resource at the given URI.\nThis message occurs when a read expression (`read`/`read?`/`read*`) is encountered within a program, and its scheme matches a client resource reader.\n\n[source,pkl]\n----\n/// A number identifying this request.\nrequestId: Int\n\n/// A number identifying this evaluator.\nevaluatorId: Int\n\n/// The URI of the resource.\nuri: String\n----\n\n[[read-resource-response]]\n=== Read Resource Response\n\nCode: `0x27` +\nType: <> <>\n\nThe response to <>.\nIf successful, `contents` is set.\nOtherwise, `error` is set.\n\nIf neither is set, `contents` defaults to an empty byte array.\n\n[source,pkl]\n----\n/// A number identifying this request.\nrequestId: Int\n\n/// A number identifying this evaluator.\nevaluatorId: Int\n\n/// The contents of the resource.\ncontents: Bytes? // <1>\n\n/// The description of the error that occurred when reading this resource.\nerror: String?\n----\n<1> MessagePack's link:https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family[bin format family]\n\n[[read-module-request]]\n=== Read Module Request\n\nCode: `0x28` +\nType: <> <>\n\nRead a module at the given URI.\nThis message occurs during the evaluation of an import statement or expression (`import`/`import*`), when a scheme matches a client module reader.\n\n[source,pkl]\n----\n/// A number identifying this request.\nrequestId: Int\n\n/// A number identifying this evaluator.\nevaluatorId: Int\n\n/// The URI of the module.\nuri: String\n----\n\n[[read-module-response]]\n=== Read Module Response\n\nCode: `0x29` +\nType: <> <>\n\nThe response to <>.\nIf successful, `contents` is set.\nOtherwise, `error` is set.\n\nIf neither is set, `contents` defaults to an empty string.\n\n[source,pkl]\n----\n/// A number identifying this request.\nrequestId: Int\n\n/// A number identifying this evaluator.\nevaluatorId: Int\n\n/// The string contents of the module.\ncontents: String?\n\n/// The description of the error that occurred when reading this resource.\nerror: String?\n----\n\n[[list-resources-request]]\n=== List Resources Request\n\nCode: `0x2a` +\nType: <> <>\n\nList resources at the specified base path.\nThis message occurs during the evaluation of a xref:language-reference:index.adoc#globbed-reads[globbed read], when a scheme matches a client resource reader's scheme.\n\nIf the resource reader does not have hierarchical URIs, `dummy` is used as the path, and the response is expected to contain all resource elements for that scheme.\n\n[source,pkl]\n----\n/// A number identifying this request.\nrequestId: Int\n\n/// A number identifying this evaluator.\nevaluatorId: Int\n\n/// The base URI to list resources.\nuri: String\n----\n\n[[list-resources-response]]\n=== List Resources Response\n\nCode: `0x2b` +\nType: <> <>\n\nThe response to <>.\nIf successful, `pathElements` is set.\nOtherwise, `error` is set.\n\nIf neither are set, `pathElements` default to an empty list.\n\n[source,pkl]\n----\n/// A number identifying this request.\nrequestId: Int\n\n/// A number identifying this evaluator.\nevaluatorId: Int\n\n/// The elements at the provided base path.\npathElements: Listing?\n\n/// The description of the error that occurred when listing elements.\nerror: String?\n\nclass PathElement {\n /// The name of the element at this path\n name: String\n\n /// Tells whether the element is a directory.\n isDirectory: Boolean\n}\n----\n\n[[list-modules-request]]\n=== List Modules Request\n\nCode: `0x2c` +\nType: <> <>\n\nList modules at the specified base path.\nThis message occurs during the evaluation of a xref:language-reference:index.adoc#globbed-imports[globbed import], when a scheme matches a client resource reader's scheme.\n\nIf the module reader does not have hierarchical URIs, `dummy` is used as the path, and the response is expected to contain all module elements for that scheme.\n\n[source,pkl]\n----\n/// A number identifying this request.\nrequestId: Int\n\n/// A number identifying this evaluator.\nevaluatorId: Int\n\n/// The base URI to list modules.\nuri: String\n----\n\n[[list-modules-response]]\n=== List Modules Response\n\nCode: `0x2d` +\nType: <> <>\n\nThe response to <>.\nIf successful, `pathElements` is set.\nOtherwise, `error` is set.\n\nIf neither are set, `pathElements` default to an empty list.\n\n[source,pkl]\n----\n/// A number identifying this request.\nrequestId: Int\n\n/// A number identifying this evaluator.\nevaluatorId: Int\n\n/// The elements at the provided base path.\npathElements: Listing?\n\n/// The description of the error that occurred when listing elements.\nerror: String?\n\nclass PathElement {\n /// The name of the element at this path\n name: String\n\n /// Tells whether the element is a directory.\n isDirectory: Boolean\n}\n----\n\n[[initialize-module-reader-request]]\n=== Initialize Module Reader Request\n\nCode: `0x2e` +\nType: <> <>\n\nInitialize an xref:language-reference:index.adoc#external-readers[External Module Reader].\nThis message is sent to external reader processes the first time a module scheme it is registered for is read.\n\n[source,pkl]\n----\n/// A number identifying this request.\nrequestId: Int\n\n/// The module scheme to initialize.\nscheme: String\n----\n\n[[initialize-module-reader-response]]\n=== Initialize Module Reader Response\n\nCode: `0x2f` +\nType: <> <>\n\nReturn the requested external module reader specification.\nThe `spec` field should be set to `null` when the external process does not implement the requested module scheme.\n\n[source,pkl]\n----\n/// A number identifying this request.\nrequestId: Int\n\n/// Client-side module reader spec.\n///\n/// Null when the external process does not implement the requested module scheme.\nspec: ClientModuleReader?\n----\n\n`ClientModuleReader` is defined above by <>.\n\n[[initialize-resource-reader-request]]\n=== Initialize Resource Reader Request\n\nCode: `0x30` +\nType: <> <>\n\nInitialize an xref:language-reference:index.adoc#external-readers[External Resource Reader].\nThis message is sent to external reader processes the first time a resource scheme it is registered for is read.\n\n[source,pkl]\n----\n/// A number identifying this request.\nrequestId: Int\n\n/// The resource scheme to initialize.\nscheme: String\n----\n\n[[initialize-resource-reader-response]]\n=== Initialize Resource Reader Response\n\nCode: `0x31` +\nType: <> <>\n\nReturn the requested external resource reader specification.\nThe `spec` field should be set to `null` when the external process does not implement the requested resource scheme.\n\n[source,pkl]\n----\n/// A number identifying this request.\nrequestId: Int\n\n/// Client-side resource reader spec.\n///\n/// Null when the external process does not implement the requested resource scheme.\nspec: ClientResourceReader?\n----\n\n`ClientResourceReader` is defined above by <>. \n\n[[close-external-process]]\n=== Close External Process\n\nCode: `0x32` +\nType: <> <> \n\nInitiate graceful shutdown of the external reader process.\n\n[source,pkl]\n----\n/// This message has no properties.\n----\n" }, { "path": "docs/modules/bindings-specification/partials/component-attributes.adoc", "content": ":uri-github-binary-encoding-snippet-tests: {uri-github-tree}/pkl-server/src/test/files/SnippetTests\n:uri-messagepack-bool: {uri-messagepack-spec}#bool-format-family\n:uri-messagepack-int: {uri-messagepack-spec}#int-format-family\n:uri-messagepack-float: {uri-messagepack-spec}#float-format-family\n:uri-messagepack-str: {uri-messagepack-spec}#str-format-family\n:uri-messagepack-bin: {uri-messagepack-spec}#bin-format-family\n:uri-messagepack-array: {uri-messagepack-spec}#array-format-family\n:uri-messagepack-map: {uri-messagepack-spec}#map-format-family\n:uri-messagepack-nil: {uri-messagepack-spec}#nil-format\n" }, { "path": "docs/modules/introduction/pages/comparison.adoc", "content": "= Comparison\ninclude::ROOT:partial$component-attributes.adoc[]\n:uri-jsonnet: https://jsonnet.org\n:uri-hcl: https://github.com/hashicorp/hcl\n:uri-dhall: https://dhall-lang.org\n:uri-pkl-spring: https://github.com/apple/pkl-spring\n:uri-graalvm: https://www.graalvm.org\n\nConfiguration is often described in a static configuration format or is generated with a general-purpose programming language.\nThis page lists shortcomings of these approaches and explains how Pkl addresses them.\nAlso, Pkl's strong and weak points in comparison to other configuration languages are discussed in this document.\n\n[[static-config-formats]]\n== Pkl vs. Static Config Formats\n\nStatic configuration formats such as JSON, YAML, TOML, and XML work reasonably well for simple configuration needs.\nHowever, they do have some shortcomings, including:\n\n. They are not very human-friendly to read and write. (JSON, XML)\n. They do not provide a way to split a large file into multiple smaller ones. (JSON, YAML, TOML)\n. They offer no way or very limited ways to abstract over repetitive configuration. (JSON, YAML, TOML, XML)\n. They do not offer standardized or widely available schema validators. (JSON, YAML, TOML)\n. They offer little or no schema-aware tooling. (JSON, YAML, TOML)\n\nPkl addresses these shortcomings as follows:\n\n. It has a clutter-free and familiar syntax with nestable comments.\n. Modules can import other modules from local and remote locations.\n. Every object can act as a template for other objects.\n The standard library offers strong support for data manipulation.\n. It has strong built-in support for describing and validating configuration schemas.\n. It is designed to enable schema-aware tooling, such as REPLs and editors with code completion support.\n\n[[general-purpose-langs]]\n== Pkl vs. General-purpose Languages\n\nWhen configuration needs outgrow the capabilities of static configuration formats,\nprojects often turn to generate configuration with a general-purpose programming language such as Python.\nGiven enough effort, this approach can satisfy complex configuration needs.\nHowever, expressing configuration in a full-blown programming language does have some shortcomings, including:\n\n. Reading, writing, and debugging configuration can become as challenging as reading, writing, and debugging application code.\n. The host language may not be a good fit for describing, manipulating, and abstracting over hierarchical configuration.\n. Configuration code may not visually resemble the configuration it generates.\n. The host language may not be a good fit for defining and validating configuration schemas.\n. Development environments may offer little help for developing and validating configuration written in the host language.\n. General-purpose languages are powerful and often difficult to sandbox.\n Are you certain your configuration script isn't erasing your hard disk or launching a rocket?\n\nPkl addresses these shortcomings as follows:\n\n. As an expression-oriented and side-effect free language, it eliminates many potential sources of errors.\n. It is specifically designed for describing, manipulating, and abstracting over hierarchical configuration.\n. Pkl code often resembles the configuration it generates.\n. It has strong built-in support for defining and validating configuration schemas.\n. It is designed to enable advanced and schema-aware tooling.\n. It is comparatively powerless and strictly sandboxed, making fatal configuration mistakes and exploits less likely.\n Till now, we haven't spotted any Pkl script capable of erasing your hard disk.\n\n[[other-config-langs]]\n== Pkl vs. Other Config Languages\n\nCompared to open-source configuration languages such as link:{uri-jsonnet}[Jsonnet],\nlink:{uri-hcl}[HCL], and link:{uri-dhall}[Dhall], Pkl's strong points are:\n\nGeneral::\n+\n* Pkl has a clean and familiar syntax, which makes it easier to read and learn.\n* Pkl supports writing sophisticated schemas, which enables config validation, code and documentation generation, and advanced IDE support.\n This is Pkl's most significant differentiator, and is the main reason why we created it.\n* Pkl has stronger templating capabilities than other config languages, reducing user code to the absolute minimum.\n\nEmbedding::\n+\n* Pkl is great for embedding into JVM applications.\n* Pkl offers modern xref:java-binding:pkl-config-java.adoc[JVM libraries] for runtime application configuration.\n* Pkl supports xref:java-binding:codegen.adoc[code generation] to enable statically typed access to configuration from programming languages.\n* Pkl integrates with third-party (link:{uri-pkl-spring}[Spring Boot]) JVM libraries and frameworks.\n\nTooling::\n+\n* Pkl has a polished xref:pkl-doc:index.adoc[documentation generator] that produces highly navigable and searchable documentation.\n* Pkl offers a xref:pkl-gradle:index.adoc[Gradle plugin] to easily integrate code evaluation, documentation generation, and code generation into your builds.\n* Pkl's native executables have a link:{uri-graalvm}[JIT compiler] that can speed up evaluation up to hundred times.\n\nOn the other hand, we believe that Pkl's weak points are:\n\n* Pkl's native binaries are larger than those of other config languages.\n* Pkl is less known and has a smaller community than some other config languages.\n\nWe are working towards making Pkl overcome these weakness. Please support us in reaching this goal!\n\nWe hope that you will enjoy Pkl, and that you trust us to gradually improve its weak points.\n" }, { "path": "docs/modules/introduction/pages/concepts.adoc", "content": "= Concepts\ninclude::ROOT:partial$component-attributes.adoc[]\n:uri-property-list: https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/PropertyLists/UnderstandXMLPlist/UnderstandXMLPlist.html\n\nLet's get to know Pkl by discussing some of its concepts and features.\n\n[[abstraction]]\n== Abstraction\n\nConfiguration tends to grow larger and more complex over time, making it increasingly difficult to understand and maintain.\nPkl can reduce the size and complexity of configuration by\n\n* describing similar configuration elements in terms of their differences\n* introducing abstractions for common configuration elements\n* separating configuration structure from configuration data\n* computing instead of enumerating configuration\n\n[[evaluation]]\n== Evaluation\n\nPkl code lives in _modules_, a more fancy and general term for _files_.\nEvaluating a module produces an in-memory _data model_ that is roughly comparable to a JSON data model.\nIf evaluation completes successfully, the Pkl evaluator converts the data model to an external representation and terminates with the status code zero.\nOtherwise, the evaluator prints an error message and terminates with a non-zero status code.\n\n[[immutability]]\n== Immutability\n\nAll Pkl data is immutable.\nManipulating a value always returns a new value, leaving the original value unchanged.\nImmutability eliminates many potential sources of errors.\n\n[[isolation]]\n== Isolation\n\nEvaluation of Pkl code is strictly sandboxed.\nExcept for a few well-defined and well-controlled exceptions, Pkl code cannot interact with the outside world.\nLeaving 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.\nOver time, sandboxing will be further strengthened to cover fine-grained CPU and memory boxing.\n\n[[rendering]]\n== Rendering\n\nConverting a data model to an external representation is called _rendering_ the model.\nPkl ships with renderers for the following data formats:\n\n* JSON\n* Jsonnet\n* Pcf (a static subset of Pkl)\n* (Java) Properties\n* {uri-property-list}[Property List]\n* XML\n* YAML\n\nSupport for other formats can be added by writing a custom renderer in Pkl or Java.\nSee xref:language-reference:index.adoc#module-output[Module Output] and xref:pkl-core:index.adoc#value-visitor[Value Visitor] for more information.\n\n[[resemblance]]\n== Resemblance\n\nBy design, Pkl code tends to structurally and visually resemble the configuration it generates.\nThis makes the code easier to read and write.\n\n[[reuse]]\n== Reuse\n\nModules can reuse other modules by xref:language-reference:index.adoc#import-module[importing] them from local or remote locations.\nImports can also be used to split up one large module into multiple smaller ones, increasing maintainability.\nA configurable security policy helps to keep imports under control.\n\n[[schema]]\n== Schema\n\nConfiguration is structured data.\nPkl 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.\nWriting and maintaining a configuration schema takes some effort but, in return, provides these benefits:\n\n* Independent evolution of configuration schema and configuration data, often by different teams (for example service providers and service consumers).\n* Automatic xref:pkl-doc:index.adoc[documentation generation].\n* Strong validation of configuration, both during development time and runtime.\n* Statically typed access to configuration from xref:java-binding:codegen.adoc[Java] and other languages through code generation.\n* Schema-aware development tools, for example REPLs and editors with code completion support.\n\n[[template]]\n== Templating\n\nPkl supports writing templates for objects and entire modules.\nTemplates can be repeatedly turned into concrete configuration by filling in the blanks, and -- when necessary -- overriding defaults.\nSharing template modules over the network can streamline complex configuration tasks for entire teams, organizations, and communities.\n\n[[usability]]\n== Usability\n\nEverybody needs a configuration solution, but nobody wants to spend a lot of time learning it.\nTo reflect this reality, Pkl has a strong focus on usability.\nFor example, error messages explain causes and possible solutions and object properties maintain definition order to avoid surprises.\nWe 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.\n" }, { "path": "docs/modules/introduction/pages/index.adoc", "content": "= Introduction\ninclude::ROOT:partial$component-attributes.adoc[]\n\nPkl -- pronounced _Pickle_ -- is a configuration-as-code language with rich validation and tooling.\nIt can be used as a command line tool, software library, or build plugin.\nPkl scales from small to large, simple to complex, ad-hoc to recurring configuration tasks.\n\nWe created Pkl because we believe that configuration is best expressed in a special-purpose configuration language;\na blend between a static configuration format, and a general-purpose programming language.\n\n* xref:use-cases.adoc[Use Cases]\n* xref:concepts.adoc[Concepts]\n* xref:comparison.adoc[Comparison]\n" }, { "path": "docs/modules/introduction/pages/use-cases.adoc", "content": "= Use Cases\ninclude::ROOT:partial$component-attributes.adoc[]\n:uri-kotlin-homepage: https://kotlinlang.org\n:uri-xml-property-lists: https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/PropertyLists/UnderstandXMLPlist/UnderstandXMLPlist.html\n\nPkl is a good fit for:\n\nGenerating Static Configuration::\nAre you using a tool, service, or application that is configured with JSON, YAML, or any other static configuration format?\n+\nBy generating this configuration with Pkl, you can reduce verbosity and increase maintainability through xref:concepts.adoc#reuse[reuse], xref:concepts.adoc#template[templating], and xref:concepts.adoc#abstraction[abstraction].\nJSON, YAML, and {uri-xml-property-lists}[XML property lists] are supported out of the box; xref:concepts.adoc#rendering[renderers] for other configuration formats can be developed and shared by anyone.\nAutomatic defaults, strong validation, and sensible error messages come in reach with configuration xref:concepts.adoc#schema[schemas].\n+\nGeneration can be triggered manually, by an automation pipeline, or by the target application.\n\nApplication Runtime Configuration::\nAre you the author of a tool, service, or application that consumes configuration?\n+\nBy adopting Pkl as your \"native\" configuration solution (rather than, say, using it to generate JSON files), you benefit from a modern xref:java-binding:pkl-config-java.adoc[configuration library] that is safe, easy, and enjoyable to use.\nAt the same time, anyone configuring your application -- whether that's your users, site reliability engineers (SREs), or yourself -- benefit from a well-defined, well-documented, and scalable configuration language.\n+\nAt the time of writing, Pkl offers configuration libraries for the JVM runtime, Swift, and also for Golang.\n+\nWe maintain the following libraries:\n+\n* xref:java-binding:pkl-config-java.adoc[pkl-config-java] for Java compatible languages\n* xref:kotlin-binding:pkl-config-kotlin.adoc[pkl-config-kotlin] for the {uri-kotlin-homepage}[Kotlin] language.\n* xref:swift:ROOT:index.adoc[pkl-swift] for the Swift language.\n* xref:go:ROOT:index.adoc[pkl-go] for the Go language.\n\nIn the future, we hope to add support for other popular languages and platforms, realizing our vision of a polyglot config solution based on a single config language.\n\n::\nWe are just getting started. Tell us about _your_ Pkl success story!\n" }, { "path": "docs/modules/java-binding/examples/JavaConfigExample.java", "content": "import org.pkl.config.java.Config;\nimport org.pkl.config.java.ConfigEvaluator;\nimport org.pkl.config.java.JavaType;\nimport org.pkl.core.ModuleSource;\nimport org.junit.jupiter.api.Test;\n\n@SuppressWarnings({\"unused\", \"NewClassNamingConvention\"})\n// the pkl-jvm-examples repo has a similar example\npublic class JavaConfigExample {\n @Test\n public void usage() {\n // tag::usage[]\n Config config;\n try (var evaluator = ConfigEvaluator.preconfigured()) { // <1>\n config = evaluator.evaluate(\n ModuleSource.text(\"pigeon { age = 5; diet = new Listing { \\\"Seeds\\\" } }\")); // <2>\n }\n var pigeon = config.get(\"pigeon\"); // <3>\n var age = pigeon.get(\"age\").as(int.class); // <4>\n var diet = pigeon.get(\"diet\").as(JavaType.listOf(String.class)); // <5>\n // end::usage[]\n }\n}\n" }, { "path": "docs/modules/java-binding/pages/codegen.adoc", "content": "= Java Code Generator\ninclude::ROOT:partial$component-attributes.adoc[]\n:uri-pkl-codegen-java-maven-module: {uri-maven-docsite}/artifact/org.pkl-lang/pkl-codegen-java\n\n:uri-pkl-codegen-java-download: {uri-sonatype-snapshot-download}&a=pkl-cli-codegen-java&e=jar\n\nifdef::is-release-version[]\n:uri-pkl-codegen-java-download: {github-releases}/pkl-codegen-java\nendif::[]\n\nThe Java source code generator takes Pkl class definitions as an input, and generates corresponding Java classes with equally named properties.\n\nThe benefits of code generation are:\n\n* Configuration can be conveniently consumed as statically typed Java objects.\n* The entire configuration tree can be code-completed in Java IDEs.\n* Any drift between Java code and Pkl configuration structure is caught at compile time.\n\nThe generated classes are immutable and have component-wise implementations of `equals()`, `hashCode()`, and `toString()`.\n\n== Installation\n\nThe code generator is offered as Gradle plugin, Java library, and CLI.\n\n=== Gradle Plugin\n\nSee xref:pkl-gradle:index.adoc#installation[Installation] in the Gradle plugin chapter.\n\n[[install-library]]\n=== Java Library\n\nThe `pkl-codegen-java` library is available {uri-pkl-codegen-java-maven-module}[from Maven Central].\nIt requires Java 17 or higher.\n\nifndef::is-release-version[]\nNOTE: Snapshots are published to repository `{uri-snapshot-repo}`.\nendif::[]\n\n==== Gradle\n\nTo use the library in a Gradle project, declare the following dependency:\n\n[tabs]\n====\nKotlin::\n+\n.build.gradle.kts\n[source,kotlin,subs=\"+attributes\"]\n----\ndependencies {\n implementation(\"org.pkl-lang:pkl-codegen-java:{pkl-artifact-version}\")\n}\n\nrepositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven(url = \"{uri-sonatype}\")\nendif::[]\n}\n----\n\nGroovy::\n+\n.build.gradle\n[source,groovy,subs=\"+attributes\"]\n----\ndependencies {\n implementation \"org.pkl-lang:pkl-codegen-java:{pkl-artifact-version}\"\n}\n\nrepositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven { url \"{uri-sonatype}\" }\nendif::[]\n}\n----\n====\n\n==== Maven\n\nTo use the library in a Maven project, declare the following dependency:\n\n.pom.xml\n[source,xml,subs=\"+attributes\"]\n----\n\n \n org.pkl-lang\n pkl-codegen-java\n {pkl-artifact-version}\n \nifndef::is-release-version[]\n \n \n sonatype-s01\n Sonatype S01\n {uri-sonatype}\n \n \nendif::[]\n\n----\n\n[[install-cli]]\n=== CLI\n\nThe CLI is available as a Java executable.\n\nIt works on multiple platforms, and requires a Java 17 (or higher) runtime on the system path.\n\nTo download:\n\n[tabs]\n====\nmacOS/Linux::\n+\n[source,shell]\n[subs=\"+attributes\"]\n----\ncurl -L -o pkl-codegen-java '{uri-pkl-codegen-java-download}'\nchmod +x pkl-codegen-java\n./pkl-codegen-java --version\n----\n\nWindows::\n+\n[source,PowerShell]\n[subs=\"+attributes\"]\n----\nInvoke-WebRequest '{uri-pkl-codegen-java-download}' -OutFile pkl-codegen-java.bat\n.\\pkl-codegen-java --version\n----\n====\n\nThis should print something similar to:\n\n[source,shell]\n[subs=\"+attributes\"]\n----\npkl-codegen-java {pkl-version} (macOS 14.2, Java 17.0.10)\n----\n\n[[codegen-java-usage]]\n== Usage\n\nThe code generator is offered as Gradle plugin, Java library, and CLI.\n\n=== Gradle Plugin\n\nSee xref:pkl-gradle:index.adoc#java-code-gen[Java Code Generation] in the Gradle plugin chapter.\n\n=== Java Library\n\nThe Java library offers two APIs: a high-level API that corresponds to the CLI, and a lower-level API that provides additional features and control.\nThe entry points for these APIs are `org.pkl.codegen.java.CliJavaCodeGenerator` and `org.pkl.codegen.java.JavaCodeGenerator`, respectively.\nFor more information, refer to the Javadoc documentation.\n\n=== CLI\n\n*Synopsis:* `pkl-codegen-java [] `\n\n``::\nThe absolute or relative URIs of the modules to generate classes for.\nRelative URIs are resolved against the working directory.\n\n==== Options\n\n.--generate-getters\n[%collapsible]\n====\nDefault: (flag not set) +\nFlag that indicates to generate private final fields and public getter methods instead of public final fields.\n====\n\n.--generate-javadoc\n[%collapsible]\n====\nDefault: (flag not set) +\nFlag that indicates to preserve Pkl doc comments by generating corresponding Javadoc comments.\n====\n\n.--params-annotation\n[%collapsible]\n====\nDefault: `none` if `--generate-spring-boot` is set, `org.pkl.config.java.mapper.Named` otherwise +\nFully qualified name of the annotation type to use for annotating constructor parameters with their name. +\nThe specified annotation type must have a `value` parameter of type `String` or the generated code may not compile.\nIf set to `none`, constructor parameters are not annotated.\nWhether and how constructor parameters should be annotated depends on the library that instantiates the generated classes.\nFor Spring Boot applications, and for users of `pkl-config-java` compiling the generated classes with `-parameters`, no annotation is required.\n====\n\n.--non-null-annotation\n[%collapsible]\n====\nDefault: `org.pkl.config.java.mapper.NonNull` +\nFully qualified name of the annotation type to use for annotating non-null types. +\nThe specified annotation type must be annotated with `@java.lang.annotation.Target(ElementType.TYPE_USE)`\nor the generated code may not compile.\n====\n\nCommon code generator options:\n\ninclude::{partialsdir}/cli-codegen-options.adoc[]\n\nCommon CLI options:\n\ninclude::../../pkl-cli/partials/cli-common-options.adoc[]\n\n[[full-example]]\n== Full Example\n\nFor a ready-to-go example with full source code,\nsee link:{uri-codegen-java-example}[codegen-java] in the _pkl-jvm-examples_ repository.\n" }, { "path": "docs/modules/java-binding/pages/index.adoc", "content": "= Integration with Java\n\nPkl provides rich integration with Java. Our integration allows you to embed the Pkl runtime into your Java program, and also provides code generation from Pkl source files.\n\n" }, { "path": "docs/modules/java-binding/pages/pkl-config-java.adoc", "content": "= pkl-config-java Library\ninclude::ROOT:partial$component-attributes.adoc[]\n:uri-pkl-core-PklException: {uri-pkl-core-main-sources}/PklException.java\n\n:uri-pkl-config-java-maven-module: {uri-maven-docsite}/artifact/org.pkl-lang/pkl-config-java-all\n:uri-pkl-config-java-main-sources: {uri-github-tree}/pkl-config-java/src/main/java/org/pkl/config/java\n:uri-pkl-config-java-test-sources: {uri-github-tree}/pkl-config-java/src/test/java/org/pkl/config/java\n:uri-pkl-config-java-test-resources: {uri-github-tree}/pkl-config-java/src/test/resources/org/pkl/config/java\n:uri-pkl-config-java-ConfigEvaluator: {uri-pkl-config-java-main-sources}/ConfigEvaluator.java\n:uri-pkl-config-java-Config: {uri-pkl-config-java-main-sources}/Config.java\n:uri-pkl-config-java-ValueMapper: {uri-pkl-config-java-main-sources}/mapper/ValueMapper.java\n:uri-pkl-config-java-Named: {uri-pkl-config-java-main-sources}/mapper/Named.java\n:uri-pkl-config-java-Conversion: {uri-pkl-config-java-main-sources}/mapper/Conversion.java\n:uri-pkl-config-java-Conversions: {uri-pkl-config-java-main-sources}/mapper/Conversions.java\n:uri-pkl-config-java-ConverterFactories: {uri-pkl-config-java-main-sources}/mapper/ConverterFactories.java\n:uri-pkl-config-java-Converter: {uri-pkl-config-java-main-sources}/mapper/Converter.java\n:uri-pkl-config-java-ConverterFactory: {uri-pkl-config-java-main-sources}/mapper/ConverterFactory.java\n:uri-pkl-config-java-PObjectToDataObjectTestJava: {uri-pkl-config-java-test-sources}/mapper/PObjectToDataObjectTest.java\n\nThe _pkl-config-java_ library builds upon xref:pkl-core:index.adoc[pkl-core].\nIt offers a higher-level API specifically designed for consuming application runtime configuration.\n\n== Installation\n\nThe _pkl-config-java_ library is available {uri-pkl-config-java-maven-module}[from Maven Central].\nIt requires Java 17 or higher.\n\n=== Gradle\n\nTo use the library in a Gradle project, declare the following dependency:\n\n[tabs]\n====\nKotlin::\n+\n.build.gradle.kts\n[source,kotlin,subs=\"+attributes\"]\n----\ndependencies {\n implementation(\"org.pkl-lang:pkl-config-java:{pkl-artifact-version}\")\n}\n\nrepositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven(url = \"{uri-sonatype}\")\nendif::[]\n}\n----\n\nGroovy::\n+\n.build.gradle\n[source,groovy,subs=\"+attributes\"]\n----\ndependencies {\n implementation \"org.pkl-lang:pkl-config-java:{pkl-artifact-version}\"\n}\n\nifdef::is-release-version[]\nrepositories {\n mavenCentral()\n}\nendif::[]\nifndef::is-release-version[]\nrepositories {\n maven { url \"{uri-sonatype}\" }\n}\nendif::[]\n----\n====\n\nUnlike `pkl-config-java`, `pkl-config-java__-all__` is a fat Jar with renamed third-party packages to avoid version conflicts.\n\n=== Maven\n\nTo use the library in a Maven project, declare the following dependency:\n\n.pom.xml\n[source,xml,subs=\"+attributes\"]\n----\n\n \n org.pkl-lang\n pkl-config-java\n {pkl-artifact-version}\n \nifndef::is-release-version[]\n \n \n sonatype-s01\n Sonatype S01\n {uri-sonatype}\n \n \nendif::[]\n\n----\n\nUnlike `pkl-config-java`, `pkl-config-java__-all__` is a fat Jar with renamed third-party packages to avoid version conflicts.\n\n== Usage\n\n=== Consuming Configuration\n\nThe {uri-pkl-config-java-ConfigEvaluator}[`ConfigEvaluator`] class loads and evaluates Pkl modules.\nIf evaluation succeeds, a {uri-pkl-config-java-Config}[`Config`] object is returned.\nOtherwise, a {uri-pkl-core-PklException}[`PklException`] with error details is thrown.\n\nThe returned `Config` object represents the root of the Pkl configuration tree.\nIntermediate and leaf nodes are also represented as `Config` objects.\n\n`Config` objects offer methods to\n\n* convert their Pkl value to a Java value of the specified type.\n* navigate to child nodes.\n\nLet's see this in action:\n\n[[config-evaluator-java-example]]\n[source,java,indent=0]\n----\ninclude::{examplesdir}/JavaConfigExample.java[tags=usage]\n----\n<1> Create a preconfigured `ConfigEvaluator`.\nTo create a customized evaluator, start from `ConfigEvaluatorBuilder.preconfigured()` or `ConfigEvaluatorBuilder.unconfigured()`.\nThe evaluator should be closed once it is no longer needed.\nIn this example, this is done with a try-with-resources statement.\nNote that objects returned by the evaluator remain valid after calling `close()`.\n<2> Evaluate the given text.\nOther `evaluate` methods read from files, URLs, and other sources.\nIf evaluation fails, an {uri-pkl-core-PklException}[`PklException`] is thrown.\n<3> Navigate from the config root to its `\"pigeon\"` child.\n<4> Navigate from `\"pigeon\"` to `\"age\"` and get the latter's value as an `int`.\nIf conversion to the requested type fails, a `ConversionException` is thrown.\n<5> Navigate from `\"pigeon\"` to `\"diet\"` and get the latter's value as a `List`.\nNote the use of `JavaType.listOf()` for creating a parameterized type literal.\nSimilar methods exist for sets, maps, and other generic types.\n\nA `ConfigEvaluator` caches module sources and evaluation results.\nTo clear the cache, for example to evaluate the same module again, close the evaluator and create a new one.\n\nFor a ready-to-go example with full source code,\nsee link:{uri-config-java-example}[config-java] in the _pkl-jvm-examples_ repository.\n\n[[object-mapping]]\n=== Object Mapping\n\nWhen a `Config` object needs to convert its Pkl value to a Java value, it delegates the conversion to {uri-pkl-config-java-ValueMapper}[`ValueMapper`].\n`ValueMapper` can convert an entire `PModule` or any part thereof.\n\nA `ValueMapper` instance can be configured with many different Pkl-to-Java value conversions.\n`ValueMapper.preconfigured()` creates an instance configured with conversions from Pkl values to:\n\n* Number types\n* Strings\n* Enums\n* Collections\n* Arrays\n* `java.util.Optional`\n* `java.time.Duration`\n* `java.net.URI/URL`\n* etc.\n\nAdditionally, a preconfigured `ValueMapper` instance can convert Pkl objects to Java objects with equally named properties that are settable through a constructor.\nThis conversion works as follows:\n\n. Find the Java class constructor with the highest number of parameters.\n. Match constructor parameters with Pkl object properties by name.\n+\nUnmatched constructor parameters result in a conversion error.\nUnmatched Pkl object properties are ignored.\n+\n. Convert each Pkl property value to the corresponding constructor parameter's type.\n. Invoke the constructor.\n\nThe Pkl object's runtime type is irrelevant to this conversion.\nHence, typed and dynamic Pkl objects are equally supported.\n\nTo perform this conversion, `ValueMapper` needs a way to obtain the Java constructor's parameter names.\nThey need to be provided in one of the following ways:\n\n* Annotate constructor with `java.beans.ConstructorProperties`.\n* Annotate parameters with {uri-pkl-config-java-Named}[`Named`].\n* Annotate parameters with `javax.inject.Named`.\n* Set the Java compiler flag `-parameters`.\n\nFor a complete object mapping example, see:\n\n* {uri-pkl-config-java-PObjectToDataObjectTestJava}[`PObjectToDataObjectTest.java`]\n\nTIP: Together with xref:java-binding:codegen.adoc[code generation], object mapping provides a complete solution for consuming Pkl configuration as statically typed Java objects.\nJava code never drifts from the configuration structure defined in Pkl, and the entire configuration tree can be code-completed in Java IDEs.\n\n==== Value Conversions\n\nThe Pkl-to-Java value conversions that ship with the library are defined in {uri-pkl-config-java-Conversions}[`Conversions`] (for individual conversions) and {uri-pkl-config-java-ConverterFactories}[`ConverterFactories`] (for families of conversions).\nTo implement and register your own conversions, follow these steps:\n\n. For conversions from a single source type to a single target type, implement a {uri-pkl-config-java-Conversion}[`Conversion`].\n+\nExample: `Conversions.pStringToCharacter` converts a single-character `pkl.base#String` to `java.lang.Character`.\n\n. For conversions from one or multiple source types to one or multiple target types, implement a {uri-pkl-config-java-ConverterFactory}[`ConverterFactory`].\n+\nExample: `ConverterFactories.pCollectionToCollection` converts any `pkl.base#Collection` to any implementation of `java.util.Collection`, for any `E`.\n+\nConverter factories are called once per combination of source type and (possibly parameterized) target type.\nThe returned `Converter`s are cached.\n\n. Create a `ValueMapperBuilder`, add all desired conversions, and build a `ValueMapper`.\n\n. Either use the `ValueMapper` directly, or connect it to a `ConfigEvaluator` through `ConfigEvaluatorBuilder`.\n\n== Further Information\n\nRefer to the Javadoc and sources published with the library, or browse the library's {uri-pkl-config-java-main-sources}[main] and {uri-pkl-config-java-test-sources}[test] sources.\n" }, { "path": "docs/modules/java-binding/partials/cli-codegen-options.adoc", "content": ".--indent\n[%collapsible]\n====\nDefault: `\" \"` (two spaces) +\nExample: `\"\\t\"` (one tab) +\nThe characters to use for indenting generated source code.\n====\n\n.-o, --output-dir\n[%collapsible]\n====\nDefault: (not set) +\nExample: `generated/` +\nThe directory where generated source code is placed.\nRelative paths are resolved against the working directory.\n====\n\n.--generate-spring-boot\n[%collapsible]\n====\nDefault: (not set) +\nFlag that indicates to generate config classes for use with Spring Boot.\n====\n\n.--implement-serializable\n[%collapsible]\n====\nDefault: (not set) +\nFlag that indicates to generate classes that implement `java.io.Serializable`.\n====\n\n.--add-generated-annotation\n[%collapsible]\n====\nDefault: (not set) +\nFlag that indicates to add the `org.pkl.config.java.Generated` annotation to generated types.\n====\n\n.--rename\n[%collapsible]\n====\nDefault: (none) +\nExample: `foo.=com.example.foo.` +\nAllows to change default class and package names (derived from Pkl module names) in the generated code.\n\nWhen you need the generated class or package names to be different from the default names derived from the Pkl module names, you can define a rename mapping, where the key is the original Pkl module name prefix, and the value is its replacement.\nWhen you do, the generated code's `package` declarations, class names, as well as file locations, will be modified according to this mapping.\n\nThe prefixes are replaced literally, which means that dots at the end are important.\nIf you want to rename packages only, in most cases, you must ensure that you have an ending dot on both sides of a mapping (except for an empty mapping, if you use it), otherwise you may get unexpected results:\n\n----\n// Assuming the following arguments:\n--rename com.foo.=x // Dot on the left only\n--rename org.bar=y. // Dot on the right only\n--rename net.baz=z // No dots\n\n// The following renames will be made:\n\"com.foo.bar\" -> \"xbar\" // Target prefix merged into the suffix\n\"org.bar.baz\" -> \"y..baz\" // Double dot, invalid name\n\"net.baz.qux\" -> \"z.qux\" // Looks okay, but...\n\"net.bazqux\" -> \"zqux\" // ...may cut the name in the middle.\n----\n\nWhen computing the appropriate target name, the longest matching prefix is used:\n\n----\n// Assuming the following arguments:\n--rename com.foo.Main=w.Main\n--rename com.foo.=x.\n--rename com.=y.\n--rename =z.\n\n// The following renames will be made:\ncom.foo.Main -> w.Main\ncom.foo.bar -> x.bar\ncom.baz.qux -> y.baz.qux\norg.foo.bar -> z.org.foo.bar\n----\n\nRepeat this option to define multiple mappings.\nKeys can be arbitrary strings, including an empty string.\nValues must be valid dot-separated fully qualified class name prefixes, possibly terminated by a dot.\n====\n" }, { "path": "docs/modules/kotlin-binding/examples/KotlinConfigExample.kt", "content": "@file:Suppress(\"UNUSED_VARIABLE\")\n\nimport org.pkl.config.java.ConfigEvaluator\nimport org.pkl.config.kotlin.forKotlin\nimport org.pkl.config.kotlin.to\nimport org.pkl.core.ModuleSource\nimport org.junit.jupiter.api.Test\n\n// the pkl-jvm-examples repo has a similar example\nclass KotlinConfigExample {\n @Test\n fun usage() {\n // tag::usage[]\n val evaluator = ConfigEvaluator.preconfigured().forKotlin() // <1>\n val config = evaluator.use { // <2>\n it.evaluate(ModuleSource.text(\"\"\"pigeon { age = 5; diet = new Listing { \"Seeds\" } }\"\"\"))\n }\n val pigeon = config[\"pigeon\"] // <3>\n val age = pigeon[\"age\"].to() // <4>\n val hobbies = pigeon[\"diet\"].to>() // <5>\n // end::usage[]\n }\n \n @Test\n fun nullable() {\n // tag::nullable[]\n val evaluator = ConfigEvaluator.preconfigured().forKotlin()\n val config = evaluator.use {\n it.evaluate(ModuleSource.text(\"name = null\")) // <1>\n }\n val name = config[\"name\"].to() // <2>\n // end::nullable[]\n }\n}\n" }, { "path": "docs/modules/kotlin-binding/pages/codegen.adoc", "content": "= Kotlin Code Generator\ninclude::ROOT:partial$component-attributes.adoc[]\n:uri-pkl-codegen-kotlin-maven-module: {uri-maven-docsite}/artifact/org.pkl-lang/pkl-codegen-kotlin\n:uri-pkl-codegen-kotlin-download: {uri-sonatype-snapshot-download}&a=pkl-cli-codegen-kotlin&e=jar\n\nifdef::is-release-version[]\n:uri-pkl-codegen-kotlin-download: {github-releases}/pkl-codegen-kotlin\nendif::[]\n\nThe Kotlin source code generator reads Pkl classes and generates corresponding Kotlin classes with equally named properties.\n\nTogether with xref:java-binding:pkl-config-java.adoc#object-mapping[Object Mapping], code generation provides a complete solution for consuming Pkl configuration as statically typed Kotlin objects.\nKotlin code never drifts from the configuration structure defined in Pkl, and the entire configuration tree can be code-completed in Kotlin IDEs.\n\n== Installation\n\nThe code generator is offered as Gradle plugin, Java library, and CLI.\n\n=== Gradle Plugin\n\nSee xref:pkl-gradle:index.adoc#installation[Installation] in the Gradle plugin chapter.\n\n[[install-library]]\n=== Java Library\n\nThe `pkl-codegen-kotlin` library is available {uri-pkl-codegen-kotlin-maven-module}[from Maven Central].\nIt requires Java 17 or higher and Kotlin 1.3 or higher.\n\n==== Gradle\n\nTo use the library in a Gradle project, declare the following dependency:\n\n[tabs]\n====\nKotlin::\n+\n.build.gradle.kts\n[source,kotlin,subs=\"+attributes\"]\n----\ndependencies {\n implementation(\"org.pkl-lang:pkl-codegen-kotlin:{pkl-artifact-version}\")\n}\n\nrepositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven(url = \"{uri-sonatype}\")\nendif::[]\n}\n----\n\nGroovy::\n+\n.build.gradle\n[source,groovy,subs=\"+attributes\"]\n----\ndependencies {\n implementation \"org.pkl-lang:pkl-codegen-kotlin:{pkl-artifact-version}\"\n}\n\nrepositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven { url \"{uri-sonatype}\" }\nendif::[]\n}\n----\n====\n\n==== Maven\n\nTo use the library in a Maven project, declare the following dependency:\n\n.pom.xml\n[source,xml,subs=\"+attributes\"]\n----\n\n org.pkl-lang\n pkl-codegen-kotlin\n {pkl-artifact-version}\n\n----\n\n[[install-cli]]\n=== CLI\n\nThe CLI is available as a Java executable.\n\nIt works on multiple platforms, and requires a Java 17 (or higher) runtime on the system path.\n\nTo download:\n\n[tabs]\n====\nmacOS/Linux::\n+\n[source,shell]\n[subs=\"+attributes\"]\n----\ncurl -L -o pkl-codegen-kotlin '{uri-pkl-codegen-kotlin-download}'\nchmod +x pkl-codegen-kotlin\n./pkl-codegen-kotlin --version\n----\n\nWindows::\n+\n[source,PowerShell]\n[subs=\"+attributes\"]\n----\nInvoke-WebRequest '{uri-pkl-codegen-kotlin-download}' -OutFile pkl-codegen-kotlin.bat\n.\\pkl-codegen-kotlin --version\n----\n====\n\nThis should print something similar to:\n\n[source,shell]\n[subs=\"+attributes\"]\n----\npkl-codegen-kotlin {pkl-version} (macOS 14.2, Java 17.0.10)\n----\n\n[[usage]]\n== Usage\n\nThe code generator is offered as Gradle plugin, Java library, and CLI.\n\n=== Gradle Plugin\n\nSee xref:pkl-gradle:index.adoc#kotlin-code-gen[Kotlin Code Generation] in the Gradle plugin chapter.\n\n=== Java Library\n\nThe library offers two APIs: a high-level API that corresponds to the CLI, and a lower-level API that provides additional features and control.\nThe entry points for these APIs are `org.pkl.codegen.kotlin.CliKotlinCodeGenerator` and `org.pkl.codegen.kotlin.KotlinCodeGenerator`, respectively.\nFor more information, refer to the KDoc documentation.\n\n=== CLI\n\n*Synopsis:* `pkl-codegen-kotlin [] `\n\n``::\nThe absolute or relative URIs of the modules to generate classes for.\nRelative URIs are resolved against the working directory.\n\n==== Options\n\n.--generate-kdoc\n[%collapsible]\n====\nDefault: (flag not set) +\nFlag that indicates to preserve Pkl doc comments by generating corresponding KDoc comments.\n====\n\nCommon code generator options:\n\ninclude::../../java-binding/partials/cli-codegen-options.adoc[]\n\nCommon CLI options:\n\ninclude::../../pkl-cli/partials/cli-common-options.adoc[]\n\n[[full-example]]\n== Full Example\n\nFor a ready-to-go example with full source code,\nsee link:{uri-codegen-kotlin-example}[codegen-kotlin] in the _pkl-jvm-examples_ repository.\n" }, { "path": "docs/modules/kotlin-binding/pages/index.adoc", "content": "= Integration with Kotlin\n\nPkl provides rich integration with Kotlin. Our integration allows you to embed the Pkl runtime into your Kotlin application, and also provides code generation for from Pkl source code.\n" }, { "path": "docs/modules/kotlin-binding/pages/pkl-config-kotlin.adoc", "content": "= pkl-config-kotlin Library\ninclude::ROOT:partial$component-attributes.adoc[]\n:uri-pkl-config-kotlin-maven-module: {uri-maven-docsite}/artifact/org.pkl-lang/pkl-config-kotlin\n:uri-pkl-config-kotlin-main-sources: {uri-github-tree}/pkl-config-kotlin/src/main/kotlin/org/pkl/config/kotlin\n:uri-pkl-config-kotlin-test-sources: {uri-github-tree}/pkl-config-kotlin/src/test/kotlin/org/pkl/config/kotlin\n:uri-pkl-config-kotlin-ConverterFactories: {uri-pkl-config-kotlin-main-sources}/ConverterFactories.kt\n:uri-pkl-config-kotlin-ConfigExtensions: {uri-pkl-config-kotlin-main-sources}/ConfigExtensions.kt\n\nThe _pkl-config-kotlin_ library extends xref:java-binding:pkl-config-java.adoc[pkl-config-java] with Kotlin specific extension methods and object converters.\nWe recommend that Kotlin projects depend on this library instead of _pkl-config-java_.\n\n== Installation\n\nThe _pkl-config-kotlin_ library is available {uri-pkl-config-kotlin-maven-module}[from Maven Central].\nIt requires Java 17 or higher and Kotlin 1.5 or higher.\n\n=== Gradle\n\nTo use the library in a Gradle project, declare the following dependency:\n\n[tabs]\n====\nKotlin::\n+\n.build.gradle.kts\n[source,kotlin,subs=\"+attributes\"]\n----\ndependencies {\n implementation(\"org.pkl-lang:pkl-config-kotlin:{pkl-artifact-version}\")\n}\n\nrepositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven(url = \"{uri-sonatype}\")\nendif::[]\n}\n----\n\nGroovy::\n+\n.build.gradle\n[source,groovy,subs=\"+attributes\"]\n----\ndependencies {\n implementation \"org.pkl-lang:pkl-config-kotlin:{pkl-artifact-version}\"\n}\n\nrepositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven { url \"{uri-sonatype}\" }\nendif::[]\n}\n----\n====\n\n=== Maven\n\nTo use the library in a Maven project, declare the following dependency:\n\n.pom.xml\n[source,xml,subs=\"+attributes\"]\n----\n\n \n org.pkl-lang\n pkl-config-kotlin\n {pkl-artifact-version}\n \nifndef::is-release-version[]\n \n \n sonatype-s01\n Sonatype S01\n {uri-sonatype}\n \n \nendif::[]\n\n----\n\n== Usage\n\nBelow is the Kotlin version of the Java xref:java-binding:pkl-config-java.adoc#config-evaluator-java-example[ConfigEvaluator] example.\nDifferences to the Java version are called out.\n\n[source,kotlin,indent=0]\n----\ninclude::{examplesdir}/KotlinConfigExample.kt[tags=usage]\n----\n<1> Use the `forKotlin()` method to preconfigure the builder with Kotlin specific conversions.\nIn particular, `forKotlin()` eliminates the need to annotate constructor parameters of Kotlin classes and Kotlin data classes with `@Named`.\n<2> The evaluator should be closed once it is no longer needed.\nHere this is done with a Kotlin `use {}` expression.\nAny data returned by the evaluator before calling `close()` remains valid.\n<3> Navigate to the `\"pigeon\"` child.\nThe subscript notation is shorthand for `config.get(\"pigeon\")`.\n<4> Convert `\"age\"` to `Int` with the `Config.to()` extension method.\nThe target type is provided as a type argument.\nAlways use `Config.to()` instead of `Config.as()` in Kotlin.\n<5> `Config.to()` makes conversions to parameterized types straightforward:\n`to>()` instead of `as(JavaType.listOf(String::class.java))`.\n\nFor properties that are allowed to be `null`, convert to a nullable type:\n\n[source,kotlin,indent=0]\n----\ninclude::{examplesdir}/KotlinConfigExample.kt[tags=nullable]\n----\n<1> To indicate that `null` is an allowed value, convert to the nullable type `String?`.\nConverting to `String` would result in a `ConversionException`.\n\nFor a ready-to-go example with full source code,\nsee link:{uri-config-kotlin-example}[config-kotlin] in the _pkl-jvm-examples_ repository.\n\n== Further Information\n\nRefer to the Javadoc and sources published with the library, or browse the library's {uri-pkl-config-kotlin-main-sources}[main] and {uri-pkl-config-kotlin-test-sources}[test] sources.\n" }, { "path": "docs/modules/language-reference/pages/index.adoc", "content": "= Language Reference\ninclude::ROOT:partial$component-attributes.adoc[]\n:uri-common-mark: https://commonmark.org/\n:uri-newspeak: https://newspeaklanguage.org\n:uri-prototypical-inheritance: https://en.wikipedia.org/wiki/Prototype-based_programming\n:uri-double-precision: https://en.wikipedia.org/wiki/Double-precision_floating-point_format\n:uri-progressive-disclosure: https://en.wikipedia.org/wiki/Progressive_disclosure\n:uri-javadoc-Pattern: https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html\n:uri-github-PklLexer: {uri-github-tree}/pkl-core/src/main/java/org/pkl/core/parser/Lexer.java\n:uri-pkl-core-ModuleSchema: {uri-pkl-core-main-sources}/ModuleSchema.java\n:uri-pkl-core-SecurityManager: {uri-pkl-core-main-sources}/SecurityManager.java\n:uri-pkl-core-ResourceReader: {uri-pkl-core-main-sources}/resource/ResourceReader.java\n:uri-pkl-core-ModuleKey: {uri-pkl-core-main-sources}/module/ModuleKey.java\n:uri-pkl-core-PklException: {uri-pkl-core-main-sources}/PklException.java\n:uri-value-converters: {uri-pkl-stdlib-docs}/base/PcfRenderer#converters\n// TODO: double check this\n:uri-pkl-go-resource-reader-docs: https://github.com/apple/pkl-go/blob/main/pkl/reader.go\n:uri-pkl-swift-resource-reader-docs: https://github.com/apple/pkl-swift/blob/main/Sources/PklSwift/Reader.swift\n:uri-glob-7: https://man7.org/linux/man-pages/man7/glob.7.html\n:uri-unicode-identifier: https://unicode.org/reports/tr31/#R1-1\n:uri-semver: https://semver.org\n:uri-mvs-build-list: https://research.swtch.com/vgo-mvs#algorithm_1\n\nThe language reference provides a comprehensive description of every Pkl language feature.\n\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<>\n\nFor a hands-on introduction, see xref:language-tutorial:index.adoc[Tutorial].\nFor ready-to-go examples with full source code, see xref:ROOT:examples.adoc[].\nFor API documentation, see xref:ROOT:standard-library.adoc[Standard Library].\n\n[[comments]]\n== Comments\n\nPkl has three forms of comments:\n\nLine comment::\nA code comment that starts with a double-slash (`//`) and runs until the end of the line.\n+\n[source%parsed,{pkl}]\n----\n// Single-line comment\n----\n\nBlock comment::\nA nestable multiline comment, which is typically used to comment out code.\nStarts with `+/*+` and ends with `+*/+`.\n+\n[source%parsed,{pkl}]\n----\n/*\n Multiline\n comment\n*/\n----\n\nDoc comment::\nA user-facing comment attached to a program member.\nIt starts with a triple-slash (`///`) and runs until the end of the line.\nDoc comments on consecutive lines are merged.\n+\n[source%parsed,{pkl}]\n----\n/// A *bird* superstar.\n/// Unfortunately, extinct.\ndodo: Bird\n----\n\nDoc comments are processed by xref:pkl-doc:index.adoc[Pkldoc], Pkl's documentation generator.\nFor details on their syntax, see <>.\n\n[[numbers]]\n== Numbers\n\nPkl has two numeric types, link:{uri-stdlib-Int}[Int] and link:{uri-stdlib-Float}[Float].\nTheir common supertype is link:{uri-stdlib-Number}[Number].\n\n=== Integers\n\nA value of type link:{uri-stdlib-Int}[Int] is a 64-bit signed integer.\n\nInteger literals can be written in decimal, hexadecimal, binary, or octal notation:\n\n[source%tested,{pkl}]\n----\nnum1 = 123\nnum2 = 0x012AFF // <1>\nnum3 = 0b00010111 // <2>\nnum4 = 0o755 // <3>\n----\n<1> decimal: 76543\n<2> decimal: 23\n<3> decimal: 493\n\nIntegers can optionally include an underscore as a separator to improve readability.\nAn underscore does not affect the integer's value.\n\n[source%tested,{pkl}]\n----\nnum1 = 1_000_000 // <1>\nnum2 = 0x0134_64DE // <2>\nnum3 = 0b0001_0111 // <3>\nnum4 = 0o0134_6475 // <4>\n----\n<1> Equivalent to `1000000`\n<2> Equivalent to `0x013464DE`\n<3> Equivalent to `0b00010111`\n<4> Equivalent to `0o01346475`\n\nNegative integer literals start with a minus sign, as in `-123`.\n\nIntegers support the standard comparison operators:\n\n[source%tested,{pkl}]\n----\ncomparison1 = 5 == 2\ncomparison2 = 5 < 2\ncomparison3 = 5 > 2\ncomparison4 = 5 <= 2\ncomparison5 = 5 >= 2\n----\n\nIntegers support the following arithmetic operators:\n\n[source%tested,{pkl}]\n----\nnum1 = 5 + 2 // <1>\nnum2 = 5 - 2 // <2>\nnum3 = 5 * 2 // <3>\nnum4 = 5 / 2 // <4>\nnum5 = 5 ~/ 2 // <5>\nnum6 = 5 % 2 // <6>\nnum7 = 5 ** 2 // <7>\n----\n<1> addition (result: `7`)\n<2> subtraction (result: `3`)\n<3> multiplication (result: `10`)\n<4> division (result: `2.5`, always `Float`)\n<5> integer division (result: `2`, always `Int`)\n<6> remainder (result: `1`)\n<7> exponentiation (result: `25`)\n\nArithmetic overflows are caught and result in an error.\n\nTo restrict an integer's range, use one of the predefined <>\nor an link:{uri-stdlib-isBetween}[isBetween] <>:\n\n[source,{pkl}]\n----\nclientPort: UInt16\nserverPort: Int(isBetween(0, 1023))\n----\n\n=== Floats\n\nA value of type link:{uri-stdlib-Float}[Float] is a 64-bit link:{uri-double-precision}[double-precision] floating point number.\n\nFloat literals use decimal notation.\nThey consist of an integer part, decimal point, fractional part, and exponent part.\nThe integer and exponent parts are optional.\n\n[source%tested,{pkl}]\n----\nnum1 = .23\nnum2 = 1.23\nnum3 = 1.23e2 // <1>\nnum4 = 1.23e-2 // <2>\n----\n<1> result: 1.23 * 10^2^\n<2> result: 1.23 * 10^-2^\n\nNegative float literals start with a minus sign, as in `-1.23`.\n\nThe special float values _not a number_, _positive infinity_, and _negative infinity_ are written as:\n\n[source%tested,{pkl}]\n----\nnotANumber = NaN\npositiveInfinity = Infinity\nnegativeInfinity = -Infinity\n----\n\nThe link:{uri-stdlib-NaN}[NaN] and link:{uri-stdlib-Infinity}[Infinity] properties are defined in the standard library.\n\nFloats support the same comparison and arithmetic operators as integers.\nFloat literals with a fractional part of zero can be safely replaced with integer literals.\nFor example, it is safe to write `1.3 * 42` instead of `1.3 * 42.0`.\n\nFloats can also include the same underscore separator as integers. For example, `1_000.4_400` is a float whose value is equivalent to `1000.4400`.\n\nTIP: As integers are more convenient to use than floats with a fractional part of zero, we recommend requiring `x: Number` instead of `x: Float` in type annotations.\n\nTo restrict a float to a finite value, use the link:{uri-stdlib-isFinite}[isFinite] <>:\n\n[source,{pkl}]\n----\nx: Float(isFinite)\n----\n\nTo restrict a float's range, use the link:{uri-stdlib-isBetween}[isBetween] type constraint:\n\n[source,{pkl}]\n----\nx: Float(isBetween(0, 10e6))\n----\n\n[[booleans]]\n== Booleans\n\nA value of type link:{uri-stdlib-Boolean}[Boolean] is either `true` or `false`.\n\nApart from the standard logical operators, `Boolean` has\nlink:{uri-stdlib-xor}[xor] and link:{uri-stdlib-implies}[implies] methods.\n\n[source%tested,{pkl}]\n----\nres1 = true && false // <1>\nres2 = true || false // <2>\nres3 = !false // <3>\nres4 = true.xor(false) // <4>\nres5 = true.implies(false) // <5>\n----\n<1> logical conjunction (result: `false`)\n<2> logical disjunction (result: `true`)\n<3> logical negation (result: `true`)\n<4> exclusive disjunction (result: `true`)\n<5> logical implication (result: `false`)\n\n[[strings]]\n== Strings\n\nA value of type link:{uri-stdlib-String}[String] is a sequence of Unicode code points.\n\nString literals are enclosed in double quotes:\n\n[source%tested,{pkl-expr}]\n----\n\"Hello, World!\"\n----\n\nTIP: Except for a few minor differences footnote:[Pkl's string literals have fewer character escape sequences,\nhave stricter rules for line indentation in multiline strings, and do not have a line continuation character.],\nString literals have the same syntax and semantics as in Swift 5. Learn one of them, know both of them!\n\nInside a string literal, the following character escape sequences have special meaning:\n\n* `\\t` - tab\n* `\\n` - line feed\n* `\\r` - carriage return\n* `\\\"` - verbatim quote\n* `\\\\` - verbatim backslash\n\nUnicode escape sequences have the form `\\u{}`, where `` is a hexadecimal number between 0 and 10FFFF:\n\n[source%tested,{pkl-expr}]\n----\n\"\\u{26} \\u{E9} \\u{1F600}\" // <1>\n----\n<1> result: `\"& é 😀\"`\n\nTo concatenate strings, use the `+` (plus) operator, as in `\"abc\" + \"def\" + \"ghi\"`.\n\n=== String Interpolation\n\nTo embed the result of expression `` in a string, use `\\()`:\n\n[source%tested,{pkl}]\n----\nname = \"Dodo\"\ngreeting = \"Hi, \\(name)!\" // <1>\n----\n<1> result: `\"Hi, Dodo!\"`\n\nBefore a result is inserted, it is converted to a string:\n\n[source%tested,{pkl}]\n----\nx = 42\nstr = \"\\(x + 2) plus \\(x * 2) is \\(0x80)\" // <1>\n----\n<1> result: `\"44 plus 84 is 128\"`\n\n=== Multiline Strings\n\nTo write a string that spans multiple lines, use a multiline string literal:\n\n[source%tested,{pkl-expr}]\n----\n\"\"\"\nAlthough the Dodo is extinct,\nthe species will be remembered.\n\"\"\"\n----\n\nMultiline string literals are delimited by three double quotes (`\"\"\"`).\nString content and closing delimiter must each start on a new line.\n\nThe content of a multiline string starts on the first line after the opening quotes and ends on the last line before the closing quotes.\nLine breaks are included in the string and normalized to `\\n`.\n\nThe previous multiline string is equivalent to this single-line string.\nNotice that there is no leading or trailing whitespace.\n\n[source%tested,{pkl-expr}]\n----\n\"Although the Dodo is extinct,\\nthe species will be remembered.\"\n----\n\nString interpolation, character escape sequences, and Unicode escape sequences work the same as for single-line strings:\n\n[source%tested,{pkl}]\n----\nbird = \"Dodo\"\nmessage = \"\"\"\nAlthough the \\(bird) is extinct,\nthe species will be remembered.\n\"\"\"\n----\n\nEach content line must begin with the same whitespace characters as the line containing the closing delimiter,\nwhich is not included in the string. Any further leading whitespace characters are preserved.\nIn other words, line indentation is controlled by indenting lines relative to the closing delimiter.\n\nIn the following string, lines have no leading whitespace:\n\n[source%tested,{pkl}]\n----\nstr = \"\"\"\n Although the Dodo\n is extinct,\n the species\n will be remembered.\n \"\"\"\n----\n\nIn the following string, lines are indented between three and five spaces:\n\n[source%tested,{pkl}]\n----\nstr = \"\"\"\n Although the Dodo\n is extinct,\n the species\n will be remembered.\n \"\"\"\n----\n\n[[custom-string-delimiters]]\n=== Custom String Delimiters\n\nSome strings contain many verbatim backslash (`\\`) or quote (`\"`) characters.\nA good example is regular expressions, which make frequent use of backslash characters for escaping.\nIn such cases, using the escape sequences `\\\\` and `\\\"` quickly becomes tedious and hampers readability.\n\nInstead, leading/closing string delimiters can be customized to start/end with a pound sign (`\\#`).\nThis also affects the escape character, which changes from `\\` to `\\#`.\n\nAll backslash and quote characters in the following string are interpreted verbatim:\n\n[source%tested,{pkl-expr}]\n----\n#\" \\\\\\\\\\ \"\"\"\"\" \"#\n----\n\nEscape sequences and string interpolation still work, and now start with `\\#`:\n\n[source%tested,{pkl}]\n----\nbird = \"Dodo\"\nstr = #\" \\\\\\\\\\ \\#n \\#u{12AF} \\#(bird) \"\"\"\"\" \"#\n----\n\nMore generally, string delimiters and escape characters can be customized to contain _n_ pound signs each, for n >= 1.\n\nIn the following string, _n_ is 2. As a result, the string content is interpreted verbatim:\n\n[source%tested,{pkl-expr}]\n----\n##\" \\\\\\\\\\ \\#\\#\\# \"\"\"\"\" \"##\n----\n\n=== String API\n\nThe `String` class offers a link:{uri-stdlib-String}[rich API].\nHere are just a few examples:\n\n[source%tested,{pkl}]\n----\nstrLength = \"dodo\".length // <1>\nreversedStr = \"dodo\".reverse() // <2>\nhasAx = \"dodo\".contains(\"alive\") // <3>\ntrimmed = \" dodo \".trim() // <4>\n----\n<1> result: `4`\n<2> result: `\"odod\"`\n<3> result: `false`\n<4> result: `\"dodo\"`\n\n[[durations]]\n== Durations\n\nA value of type link:{uri-stdlib-Duration}[Duration] has a _value_ component of type `Number` and a _unit_ component of type `String`.\nThe unit component is constrained to the units defined in link:{uri-stdlib-DurationUnit}[DurationUnit].\n\nDurations are constructed with the following `Number` properties:\n\n[source%tested,{pkl}]\n----\nduration1 = 5.ns // nanoseconds (smallest unit)\nduration2 = 5.us // microseconds\nduration3 = 5.ms // milliseconds\nduration4 = 5.s // seconds\nduration5 = 5.min // minutes\nduration6 = 5.h // hours\nduration7 = 3.d // days (largest unit)\n----\n\nA duration can be negative, as in `-5.min`.\nIt can have a floating point value, as in `5.13.min`.\nThe link:{uri-stdlib-Duration-value}[value] and link:{uri-stdlib-Duration-unit}[unit] properties provide access to the duration's components.\n\nDurations support the standard comparison operators:\n\n[source%tested,{pkl}]\n----\ncomparison1 = 5.min == 3.s\ncomparison2 = 5.min < 3.s\ncomparison3 = 5.min > 3.s\ncomparison4 = 5.min <= 3.s\ncomparison5 = 5.min >= 3.s\n----\n\nDurations support the same arithmetic operators as numbers:\n\n[source%tested,{pkl}]\n----\nres1 = 5.min + 3.s // <1>\nres2 = 5.min - 3.s // <2>\nres3 = 5.min * 3 // <3>\nres4 = 5.min / 3 // <4>\nres5 = 5.min / 3.min // <5>\nres6 = 5.min ~/ 3 // <6>\nres7 = 5.min ~/ 3.min // <7>\nres8 = 5.min % 3 // <8>\nres9 = 5.min ** 3 // <9>\n----\n<1> result: `5.05.min`\n<2> result: `4.95.min`\n<3> result: `15.min`\n<4> result: `1.6666666666666667.min`\n<5> result: `1.6666666666666667`\n<6> result: `1.min`\n<7> result: `1`\n<8> result: `2.min`\n<9> result: `125.min`\n\nThe value component can be an expression:\n\n[source%tested,{pkl}]\n----\nx = 5\nxMinutes = x.min // <1>\ny = 3\nxySeconds = (x + y).s // <2>\n----\n<1> result: `5.min`\n<2> result: `8.s`\n\n[[data-sizes]]\n== Data Sizes\n\nA value of type link:{uri-stdlib-DataSize}[DataSize] has a _value_ component of type `Number` and a _unit_ component of type `String`.\nThe unit component is constrained to the units defined in link:{uri-stdlib-DataSizeUnit}[DataSizeUnit].\n\nData sizes with decimal units (factor 1000) are constructed with the following `Number` properties:\n\n[source%tested,{pkl}]\n----\ndatasize1 = 5.b // bytes (smallest unit)\ndatasize2 = 5.kb // kilobytes\ndatasize3 = 5.mb // megabytes\ndatasize4 = 5.gb // gigabytes\ndatasize5 = 5.tb // terabytes\ndatasize6 = 5.pb // petabytes (largest unit)\n----\n\nData sizes with binary units (factor 1024) are constructed with the following `Number` properties:\n\n[source%tested,{pkl}]\n----\ndatasize1 = 5.b // bytes (smallest unit)\ndatasize2 = 5.kib // kibibytes\ndatasize3 = 5.mib // mebibytes\ndatasize4 = 5.gib // gibibytes\ndatasize5 = 5.tib // tebibytes\ndatasize6 = 5.pib // pebibytes (largest unit)\n----\n\nA data size can be negative, as in `-5.mb`.\nIt can have a floating point value, as in `5.13.mb`.\nThe link:{uri-stdlib-DataSize-value}[value] and link:{uri-stdlib-DataSize-unit}[unit] properties provide access to the data size's components.\n\nData sizes support the standard comparison operators:\n\n[source%tested,{pkl}]\n----\ncomparison1 = 5.mb == 3.kib\ncomparison2 = 5.mb < 3.kib\ncomparison3 = 5.mb > 3.kib\ncomparison4 = 5.mb <= 3.kib\ncomparison5 = 5.mb >= 3.kib\n----\n\nData sizes support the same arithmetic operators as numbers:\n\n[source%tested,{pkl}]\n----\nres1 = 5.mb + 3.kib // <1>\nres2 = 5.mb - 3.kib // <2>\nres3 = 5.mb * 3 // <3>\nres4 = 5.mb / 3 // <4>\nres5 = 5.mb / 3.mb // <5>\nres6 = 5.mb ~/ 3 // <6>\nres7 = 5.mb ~/ 3.mb // <7>\nres8 = 5.mb % 3 // <8>\nres9 = 5.mb ** 3 // <9>\n----\n<1> result: `5.003072.mb`\n<2> result: `4.996928.mb`\n<3> result: `15.mb`\n<4> result: `1.6666666666666667.mb`\n<5> result: `1.6666666666666667`\n<6> result: `1.mb`\n<7> result: `1`\n<8> result: `2.mb`\n<9> result: `125.mb`\n\nThe value component can be an expression:\n\n[source%tested,{pkl}]\n----\nx = 5\nxMegabytes = x.mb // <1>\ny = 3\nxyKibibytes = (x + y).kib // <2>\n----\n<1> result: `5.mb`\n<2> result: `8.kib`\n\n[[objects]]\n== Objects\n\nAn object is an ordered collection of _values_ indexed by _name_.\n\nAn object's key-value pairs are called its _properties_.\nProperty values are lazily evaluated on the first read.\n\nBecause Pkl's objects differ in important ways from objects in general-purpose programming languages,\nand because they are the backbone of most data models, understanding objects is the key to understanding Pkl.\n\n[[defining-objects]]\n=== Defining Objects\n\nLet's define an object with properties `name` and `extinct`:\n\n[source%tested,{pkl}]\n----\ndodo { // <1>\n name = \"Dodo\" // <2>\n extinct = true // <3>\n} // <4>\n----\n<1> Defines a module property named `dodo`.\n The open curly brace (`{`) indicates that the value of this property is an object.\n<2> Defines an object property named `name` with string value `\"Dodo\"`.\n<3> Defines an object property named `extinct` with boolean value `true`.\n<4> The closing curly brace indicates the end of the object definition.\n\nTo access an object property by name, use dot (`.`) notation:\n\n[source%tested,{pkl}]\n----\ndodoName = dodo.name\ndodoIsExtinct = dodo.extinct\n----\n\nObjects can be nested:\n\n[source%tested,{pkl}]\n----\ndodo {\n name = \"Dodo\"\n taxonomy { // <1>\n `class` = \"Aves\" // <2>\n }\n}\n----\n<1> Defines an object property named `taxonomy`.\n The open curly brace indicates that its value is another object.\n<2> The word `class` is a keyword of Pkl, and needs to be wrapped in backticks (```) to be used as a property.\n\nAs you probably guessed, the nested property `class` can be accessed with `dodo.taxonomy.class`.\n\nLike all values, objects are _immutable_, which is just a fancy (and short!) way to say that their properties never change.\nSo what happens when Dodo moves to a different street? Do we have to construct a new object from scratch?\n\n[[amending-objects]]\n=== Amending Objects\n\nFortunately, we don't have to.\nAn object can be _amended_ to form a new object that only differs in selected properties.\nHere is how this looks:\n\n[source%parsed,{pkl}]\n----\ntortoise = (dodo) { // <1>\n name = \"Galápagos tortoise\"\n taxonomy { // <2>\n `class` = \"Reptilia\" // <3>\n }\n}\n----\n<1> Defines a module property named `tortoise`.\n Its value is an object that _amends_ `dodo`.\n Note that the amended object must be enclosed in parentheses.\n<2> Object property `tortoise.taxonomy` _amends_ `dodo.taxonomy`.\n<3> Object property `tortoise.taxonomy.class` _overrides_ `dodo.taxonomy.class`.\n\nAs you can see, it is easy to construct a new object that overrides selected properties of an existing object,\neven if, as in our example, the overridden property is nested inside another object.\n\nNOTE: If this way of constructing new objects from existing objects reminds you of prototypical inheritance, you are spot-on:\nPkl objects use prototypical inheritance as known from languages such as JavaScript.\nBut unlike in JavaScript, their prototype chain cannot be directly accessed or even modified.\nAnother difference is that in Pkl, object properties are late-bound. Read on to see what this means.\n\n[[amends-declaration]]\n[NOTE]\n.Amends declaration vs. amends expression\n====\n\nThe <> and <> sections cover two notations that are both a form of amending; called an _amends declaration_ and an _amends expression_, respectively.\n\n[source%tested,{pkl}]\n----\npigeon { // <1>\n name = \"Turtle dove\"\n extinct = false\n}\n\nparrot = (pigeon) { // <2>\n name = \"Parrot\"\n}\n----\n<1> Amends declaration.\n<2> Amends expression.\n\nAn amends declaration amends a property of the same name if the property exists within a parent module.\nOtherwise, an amends declaration implicitly amends {uri-stdlib-Dynamic}[Dynamic].\n\nAnother way to think about an amends declaration is that it is shorthand for assignment.\nIn practical terms, `pigeon {}` is the same as `pigeon = (super.pigeon) {}`.\n\nAmending object bodies can be chained for both an amends declaration and an amends expression.\n\n[source%tested,{pkl}]\n----\npigeon {\n name = \"Common wood pigeon\"\n} {\n extinct = false\n} // <1>\n\ndodo = (pigeon) {\n name = \"Dodo\"\n} {\n extinct = true\n} // <2>\n----\n<1> Chained amends declaration.\n<2> Chained amends expression (`(pigeon) { ... } { ... }` is the amends expression).\n====\n\n[[late-binding]]\n=== Late Binding\n\nLet's move on to Pkl's secret sauce:\nthe ability to define an object property's value in terms of another property's value, and the resulting _late binding_ effect.\nHere is an example:\n\n[source%tested,{pkl}]\n----\npenguin {\n eggIncubation = 40.d \n adultWeightInGrams = eggIncubation.value * 100 // <1>\n}\nadultWeightInGrams = penguin.adultWeightInGrams\n----\n<1> result: `4000`\n\nWe have defined a hypothetical `penguin` object whose `adultWeightInGrams` property is defined in terms of the `eggIncubation` duration.\nCan you guess what happens when `penguin` is amended and its `eggIncubation` overridden?\n\n[source%tested,{pkl}]\n----\nmadeUpBird = (penguin) {\n eggIncubation = 11.d\n}\nadultWeightInGrams = madeUpBird.adultWeightInGrams // <1>\n----\n<1> result: `1100`\n\nAs you can see, ``madeUpBird``'s `adultWeightInGrams` changed along with its `eggIncubation`.\nThis is what we mean when we say that object properties are _late-bound_.\n\n[NOTE]\n.Spreadsheet Programming\n====\nA good analogy is that object properties behave like spreadsheet cells.\nWhen they are linked, changes to \"downstream\" properties automatically propagate to \"upstream\" properties.\nThe main difference is that editing a spreadsheet cell changes the state of the spreadsheet,\nwhereas \"editing\" a property results in a new object, leaving the original object untouched.\nIt is as if you made a copy of the entire spreadsheet whenever you edited a cell!\n====\n\nLate binding of properties is an incredibly useful feature for a configuration language.\nIt is used extensively in Pkl code (especially in templates) and is the key to understanding how Pkl works.\n\n=== Transforming Objects\n\nSay we have the following object:\n\n[source%tested,{pkl}]\n----\ndodo {\n name = \"Dodo\"\n extinct = true\n}\n----\n\nHow can property `name` be removed?\n\nThe recipe for transforming an object is:\n\n. Convert the object to a map.\n. Transform the map using ``Map``'s link:{uri-stdlib-Map}[rich API].\n. If necessary, convert the map back to an object.\n\nEquipped with this knowledge, let's try to accomplish our objective:\n\n[source%tested,{pkl-expr}]\n----\ndodo\n .toMap()\n .remove(\"name\")\n .toDynamic()\n----\n\nThe resulting dynamic object is equivalent to `dodo`, except that it no longer has a `name` property.\n\n[IMPORTANT]\n.Lazy vs. Eager Data Types\n====\nConverting an object to a map is a transition from a _lazy_ to an _eager_ data type.\nAll of the object's properties are evaluated and all references between them are resolved.\n\nIf the map is later converted back to an object, subsequent changes to the object's properties no longer propagate to (previously) dependent properties.\nTo make these boundaries clear, transitioning between _lazy_ and _eager_ data types always requires an explicit method call, such as `toMap()` or `toDynamic()`.\n====\n\n[[typed-objects]]\n=== Typed Objects\n\n:fn-typed-objects: footnote:[By \"structure\" we mean a list of property names and (optionally) property types.]\n\nPkl has two kinds of objects:\n\n* A link:{uri-stdlib-Dynamic}[Dynamic] object has no predefined structure.{fn-typed-objects}\n When a dynamic object is amended, not only can existing properties be overridden or amended, but new properties can also be added.\n So far, we have only used dynamic objects in this chapter.\n* A link:{uri-stdlib-Typed}[Typed] object has a fixed structure described by a class definition.\n When a typed object is amended, its properties can be overridden or amended, but new properties cannot be added.\n In other words, the new object has the same class as the original object.\n\n[TIP]\n.When to Use Typed vs. Dynamic Objects\n====\n* Use typed objects to build schema-backed data models that are validatedfootnote:[By \"Use typed objects\" we mean to define classes and build data models out of instances of these classes.].\n This is what most templates do.\n* Use dynamic objects to build schema-less data models that are not validated.\n Dynamic objects are useful for ad-hoc tasks, tasks that do not justify the effort of writing and maintaining a schema, and for representing data whose structure is unknown.\n====\n\nNote that every <> is a typed object. Its properties implicitly define a class,\nand new properties cannot be added when amending the module.\n\nA typed object is backed by a _class_.\nLet's look at an example:\n\n[source%tested,{pkl}]\n----\nclass Bird { // <1>\n name: String\n lifespan: Int\n migratory: Boolean\n}\n\npigeon = new Bird { // <2>\n name = \"Pigeon\"\n lifespan = 8\n migratory = false\n}\n----\n<1> Defines a class named `Bird` with properties `name`, `lifespan` and `migratory`.\n<2> Defines a module property named `pigeon`.\n Its value is a typed object constructed by instantiating class `Bird`.\n A type only needs to be stated when the property does not have or inherit a <>.\n Otherwise, amend syntax (`pigeon { ... }`) or shorthand instantiation syntax (`pigeon = new { ... }`) should be used.\n\nCongratulations, you have constructed your first typed objectfootnote:[Not counting that every module is a typed object.]!\nHow does it differ from a dynamic object?\n\nThe answer is that a typed object has a fixed structure prescribed by its class, which cannot be changed when amending the object:\n\n[source%tested%error,{pkl}]\n----\nclass Bird { // <1>\n name: String\n lifespan: Int\n}\n\nfaultyPigeon = new Bird {\n name = \"Pigeon\"\n lifespan = 8\n hobby = \"singing\"\n}\n----\n\nEvaluating this gives:\n\n[source,shell,subs=\"quotes\"]\n----\nCannot find property *hobby* in object of type *repl#Bird*.\n\nAvailable properties:\nlifespan\nname\n----\n\nClass structure is also enforced when instantiating a class.\nLet's try to override property `name` with a value of the wrong type:\n\n[source%tested%error,{pkl}]\n----\nfaultyPigeon2 = new Bird {\n name = 3.min\n lifespan = 8\n}\n----\n\nEvaluating this, also fails:\n\n[source,shell,subs=\"quotes\"]\n----\nExpected value of type *String*, but got type *Duration*.\nValue: 3.min\n----\n\nTyped objects are the fundamental building block for constructing validated data models in Pkl.\nTo dive deeper into this topic, continue with <>.\n\n[NOTE]\n.Converting untyped objects to typed objects\n====\nWhen you have a `Dynamic` that has all the properties (with the right types and meeting all constraints), you can convert it to a `Typed` by using link:{uri-stdlib-Dynamic-toTyped}[`toTyped()`]:\n\n[source,{pkl}]\n----\nclass Bird {\n name: String\n lifespan: Int\n}\n\npigeon = new Dynamic { // <1>\n name = \"Pigeon\"\n lifespan = 8\n}.toTyped(Bird) // <2>\n----\n<1> Instead of a `new Bird`, `pigeon` can be defined with a `new Dynamic`.\n<2> That `Dynamic` is then converted to a `Bird`.\n====\n\n[[properties]]\n=== Property Modifiers\n\n==== Hidden Properties\n\nA property with the modifier `hidden` is omitted from the rendered output and object conversions.\nHidden properties are also ignored when evaluating equality or hashing (e.g. for `Mapping` or `Map` keys).\n\n[source,{pkl}]\n----\nclass Bird {\n name: String\n lifespan: Int\n hidden nameAndLifespanInIndex = \"\\(name), \\(lifespan)\" // <1>\n nameSignWidth: UInt = nameAndLifespanInIndex.length // <2>\n}\n\npigeon = new Bird { // <3>\n name = \"Pigeon\"\n lifespan = 8\n}\n\npigeonInIndex = pigeon.nameAndLifespanInIndex // <4>\n\npigeonDynamic = pigeon.toDynamic() // <5>\n\nfavoritePigeon = (pigeon) {\n nameAndLifespanInIndex = \"Bettie, \\(lifespan)\"\n}\n\nsamePigeon = pigeon == favoritePigeon // <6>\n----\n<1> Properties defined as `hidden` are accessible on any `Bird` instance, but not output by default.\n<2> Non-hidden properties can refer to hidden properties as usual.\n<3> `pigeon` is an object with _four_ properties, but is rendered with _three_ properties.\n<4> Accessing a `hidden` property from outside the class and object is like any other property.\n<5> Object conversions omit hidden properties, so the resulting `Dynamic` has three properties.\n<6> Objects that differ only in `hidden` property values are considered equal\n\nInvoking Pkl on this file produces the following result.\n\n[source,{pkl}]\n----\npigeon {\n name = \"Pigeon\"\n lifespan = 8\n nameSignWidth = 9\n}\npigeonInIndex = \"Pigeon, 8\"\npigeonDynamic {\n name = \"Pigeon\"\n lifespan = 8\n nameSignWidth = 9\n}\nfavoritePigeon {\n name = \"Pigeon\"\n lifespan = 8\n nameSignWidth = 9\n}\nsamePigeon = true\n----\n\n==== Local properties\nA property with the modifier `local` can only be referenced in the lexical scope of its definition.\n\n[source,{pkl}]\n----\nclass Bird {\n name: String\n lifespan: Int\n local separator = \",\" // <1>\n hidden nameAndLifespanInIndex = \"\\(name)\\(separator) \\(lifespan)\" // <2>\n}\n\npigeon = new Bird {\n name = \"Pigeon\"\n lifespan = 8\n}\n\npigeonInIndex = pigeon.nameAndLifespanInIndex // <3>\npigeonSeparator = pigeon.separator // Error <4>\n----\n<1> This property can only be accessed from inside this _class definition_.\n<2> Non-local properties can refer to the local property as usual.\n<3> The _value_ of `separator` occurs in `nameAndLifespanInIndex`.\n<4> Pkl does not accept this, as there is no property `separator` on a `Bird` instance.\n\nBecause a `local` property is added to the lexical scope, but not (observably) to the object, you can add `local` properties to ``Listing``s and ``Mapping``s.\n\n[NOTE]\n.Import clauses define local properties\n====\n\nAn _import clause_ defines a local property in the containing module.\nThis means `import \"someModule.pkl\"` is effectively `const local someModule = import(\"someModule.pkl\")`.\nAlso, `import \"someModule.pkl\" as otherName` is effectively `const local otherName = import(\"someModule.pkl\")`.\n====\n\n[[fixed-properties]]\n==== Fixed properties\n\nA property with the `fixed` modifier cannot be assigned to or amended when defining an object of its class.\n\n.Bird.pkl\n[source%tested,{pkl}]\n----\nfixed laysEggs: Boolean = true\n\nfixed birds: Listing = new {\n \"Pigeon\"\n \"Hawk\"\n \"Penguin\"\n}\n----\n\nWhen amending, assigning to a `fixed` property is an error.\nSimilarly, it is an error to use an <> on a fixed property:\n\n.invalid.pkl\n[source%tested,{pkl}]\n----\namends \"Bird.pkl\"\n\nlaysEggs = false // <1>\n\nbirds { // <2>\n \"Giraffe\"\n}\n----\n<1> Error: cannot assign to fixed property `laysEggs`\n<2> Error: cannot amend fixed property `birds`\n\nWhen extending a class and overriding an existing property definition, the fixedness of the overridden property must be preserved.\nIf the property in the parent class is declared `fixed`, the child property must also be declared `fixed`.\nIf the property in the parent class is not declared `fixed`, the child property may not add the `fixed` modifier.\n\n[source%parsed,{pkl}]\n----\nabstract class Bird {\n fixed canFly: Boolean\n name: String\n}\n\nclass Penguin extends Bird {\n canFly = false // <1>\n fixed name = \"Penguin\" // <2>\n}\n----\n<1> Error: missing modifier `fixed`.\n<2> Error: modifier `fixed` cannot be applied to property `name`.\n\nThe `fixed` modifier is useful for defining properties that are meant to be derived from other properties.\nIn the following snippet, the property `wingspanWeightRatio` is not meant to be assigned to, because it is derived\nfrom other properties.\n\n[source%parsed,{pkl}]\n----\nclass Bird {\n wingspan: Int\n weight: Int\n fixed wingspanWeightRatio: Int = wingspan / weight\n}\n----\n\nAnother use-case for `fixed` is to define properties that are meant to be fixed to a class definition.\nIn the example below, the `species` of a bird is tied to the class, and therefore is declared `fixed`.\n\nNote that it is possible to define a `fixed` property without a value, for one of two reasons:\n\n1. The type has a default value that makes an explicit default redundant.\n2. The property is meant to be overridden by a child class.\n\n[source%tested,{pkl}]\n----\nabstract class Bird {\n fixed species: String // <1>\n}\n\nclass Osprey extends Bird {\n fixed species: \"Pandion haliaetus\" // <2>\n}\n----\n<1> No explicit default because the property is overridden by a child class.\n<2> Overrides the type from `String` to the <> `\"Pandion haliaetus\"`. +\nAssigning an explicit default would be redundant, therefore it is omitted.\n\n==== Const properties\n\nA property with the `const` modifier behaves like the <> modifier,\nwith the additional rule that it cannot reference non-const properties or methods.\n\n.Bird.pkl\n[source%tested,{pkl}]\n----\nconst laysEggs: Boolean = true\n\nconst examples: Listing = new {\n \"Pigeon\"\n \"Hawk\"\n \"Penguin\"\n}\n----\n\nReferencing any non-const property or method is an error.\n\n.invalid.pkl\n[source%parsed,{pkl}]\n----\npigeonName: String = \"Pigeon\"\n\nconst function birdLifespan(i: Int): Int = (i / 4).toInt()\n\nclass Bird {\n name: String\n lifespan: Int\n}\n\nconst bird: Bird = new {\n name = pigeonName // <1>\n lifespan = birdLifespan(24) // <2>\n}\n----\n<1> Error: cannot reference non-const property `pigeonName` from a const property.\n<2> Allowed: `birdLifespan` is const.\n\nIt is okay to reference another value _within_ the same const property.\n\n.valid.pkl\n[source%tested,{pkl}]\n----\nclass Bird {\n lifespan: Int\n description: String\n speciesName: \"Bird\"\n}\n\nconst bird: Bird = new {\n lifespan = 8\n description = \"species: \\(speciesName), lifespan: \\(lifespan)\" // <1>\n}\n----\n<1> `lifespan` is declared within property `bird`. `speciesName` resolves to `this.speciesName`, where `this` is a value within property `bird`.\n\nNOTE: Because `const` members can only reference themselves and other `const` members, they are not <>.\n\nThe `const` modifier implies that it is also <>.\nTherefore, the same rules that apply to `fixed` also apply to `const`:\n\n* A `const` property cannot be assigned to or amended when defining an object of its class.\n* The const-ness of a property or method must be preserved when it is overridden by a child class.\n\n[[class-and-annotation-const]]\n*Class, Annotation, and Typealias Scoping*\n\nIn these following scenarios, any reference to a property or method of its enclosing module requires that the referenced member is `const`:\n\n* Class body\n* Annotation body\n* Typealiased constrained type\n\n.invalid2.pkl\n[source%parsed,{pkl}]\n----\npigeonName: String = \"Pigeon\"\n\nclass Bird {\n name: String = pigeonName // <1>\n}\n\n@Deprecated { message = \"Replace with \\(pigeonName)\" } // <2>\noldPigeonName: String\n\ntypealias IsPigeonName = String(pigeonName) // <3>\n----\n<1> Error: cannot reference non-const property `pigeonName` from a class.\n<2> Error: cannot reference non-const property `pigeonName` from an annotation.\n<3> Error: cannot reference non-const property `pigeonname` from a typealias.\n\nThis rule exists because classes, annotations, and typealiases are not <>;\nit is not possible to change the definition of these members by amending the module\nwhere it is defined.\n\nGenerally, there are two strategies for referencing such properties:\n\n*Add the `const` modifier to the referenced property*\n\nOne solution is to add the `const` modifier to the property being referenced.\n\n.Birds.pkl\n[source,diff]\n----\n-pigeonName: String = \"Pigeon\"\n+const pigeonName: String = \"Pigeon\"\n\n class Bird {\n name: String = pigeonName\n }\n----\n\nThis solution makes sense if `pigeonName` does not get assigned/amended when amending module `Birds.pkl` (modules are regular objects that can be amended).\n\n*Self-import the module*\n\n.Birds.pkl\n[source,diff]\n----\n+import \"Birds.pkl\" // <1>\n+\n pigeonName: String = \"Pigeon\"\n\n class Bird {\n- name: String = pigeonName\n+ name: String = Birds.pigeonName\n }\n----\n<1> module `Birds` imports itself\n\nThis solution works because an import clause implicitly defines a `const local` property and amending this module does not affect a self-import.\n\nThis makes sense if property `pigeonName` *does* get assigned/amended when amending module `Birds.pkl`.\n\n[[listings]]\n== Listings\n\nA value of type link:{uri-stdlib-Listing}[Listing] is an ordered, indexed collection of _elements_.\n\nA listing's elements have zero-based indexes and are lazily evaluated on the first read.\n\nListings combine qualities of lists and objects:\n\n* Like lists, listings can contain arbitrary elements.\n* Like objects, listings excel at defining and amending nested literal data structures.\n* Like objects, listings can only be directly manipulated through amendment,\n but converting them to a list (and, if necessary, back to a listing) opens the door to arbitrary transformations.\n* Like object properties, listing elements are evaluated lazily, can be defined in terms of each other, and are late-bound.\n\n[TIP]\n.When to use Listing vs. <>\n====\n* When a collection of elements needs to be specified literally, use a listing.\n* When a collection of elements needs to be transformed in a way that cannot be achieved by <> a listing, use a list.\n* If in doubt, use a listing.\n\nTemplates and schemas should almost always use listings instead of lists.\nNote that listings can be converted to lists when the need arises.\n====\n\n=== Defining Listings\n\nListings have a literal syntax that is similar to that of objects.\nHere is a listing with two elements:\n\n[source%tested,{pkl}]\n----\nbirds = new Listing { // <1>\n new { // <2>\n name = \"Pigeon\"\n diet = \"Seed\"\n }\n new { // <3>\n name = \"Parrot\"\n diet = \"Berries\"\n }\n}\n----\n<1> Defines a module property named `birds` with a value of type `Listing`.\n A type only needs to be stated when the property does not have or inherit a <>.\n Otherwise, amend syntax (`birds { ... }`) or shorthand instantiation syntax (`birds = new { ... }`) should be used.\n<2> Defines a listing element of type `Dynamic`.\n<3> Defines another listing element of type `Dynamic`.\n The order of definitions is relevant.\n\nTo access an element by index, use the `[]` (subscript) operator:\n\n[source%tested,{pkl}]\n----\nfirstBirdName = birds[0].name // <1>\nsecondBirdDiet = birds[1].diet // <2>\n----\n<1> result: `\"Pigeon\"`\n<2> result: `\"Berries\"`\n\nListings can contain arbitrary types of elements:\n\n[source%tested,{pkl}]\n----\nlisting = new Listing {\n \"Pigeon\" // <1>\n 3.min // <2>\n new Listing { // <3>\n \"Barn owl\"\n }\n}\n----\n<1> Defines a listing element of type `String`.\n<2> Defines a listing element of type `Duration`.\n<3> Defines a listing element of type `Listing`.\n\nListings can have `local` properties:\n\n[source%tested,{pkl}]\n----\nlisting = new Listing {\n local pigeon = \"Pigeon\" // <1>\n pigeon // <2>\n \"A \" + pigeon + \" is a bird\" // <3>\n}\n----\n<1> Defines a local property with the value `\"Pigeon\"`.\n Local properties can have a type annotation, as in `pigeon: String = \"Pigeon\"`.\n<2> Defines a listing element that references the local property.\n<3> Defines another listing element that references the local property.\n\n[[amending-listings]]\n=== Amending Listings\n\nLet's say we have the following listing:\n\n[source%tested,{pkl}]\n----\nbirds = new Listing {\n new {\n name = \"Pigeon\"\n diet = \"Seeds\"\n }\n new {\n name = \"Parrot\"\n diet = \"Berries\"\n }\n}\n----\n\nTo add, override, or amend elements of this listing, amend the listing itself:\n\n[source%tested,{pkl}]\n----\nbirds2 = (birds) { // <1>\n new { // <2>\n name = \"Barn owl\"\n diet = \"Mice\"\n }\n [0] { // <3>\n diet = \"Worms\"\n }\n [1] = new { // <4>\n name = \"Albatross\"\n diet = \"Fish\"\n }\n}\n----\n<1> Defines a module property named `birds2`. Its value is a listing that amends `birds`.\n<2> Defines a listing element of type `Dynamic`.\n<3> Amends the listing element at index 0 (whose name is `\"Pigeon\"`) and overrides property `diet`.\n<4> Overrides the listing element at index 1 (whose name is `\"Parrot\"`) with an entirely new dynamic object.\n\n=== Late Binding\n\nA listing element can be defined in terms of another element.\nTo reference the element at index ``, use `this[]`:\n\n[source%tested,{pkl}]\n----\nbirds = new Listing {\n new { // <1>\n name = \"Pigeon\"\n diet = \"Seeds\"\n }\n (this[0]) { // <2>\n name = \"Parrot\"\n }\n}\n----\n<1> Defines a listing element of type `Dynamic`.\n<2> Defines a listing element that amends the element at index 0 and overrides `name`.\n\nListing elements are late-bound:\n\n[source%tested,{pkl}]\n----\nnewBirds = (birds) { // <1>\n [0] {\n diet = \"Worms\"\n }\n}\n\nsecondBirdDiet = newBirds[1].diet // <2>\n----\n<1> Amends listing `birds` and overrides property `diet` of element 0 (whose name is \"Pigeon\"`) to have the value `\"Worms\"`.\n<2> Because element 1 is defined in terms of element 0, its `diet` property also changes to `\"Worms\"`.\n\n=== Transforming Listings\n\nSay we have the following listing:\n\n[source%tested,{pkl}]\n----\nbirds = new Listing {\n new {\n name = \"Pigeon\"\n diet = \"Seeds\"\n }\n new {\n name = \"Parrot\"\n diet = \"Berries\"\n }\n}\n----\n\nHow can the order of elements be reversed programmatically?\n\nThe recipe for transforming a listing is:\n\n. Convert the listing to a list.\n. Transform the list using ``List``'s link:{uri-stdlib-List}[rich API].\n. If necessary, convert the list back to a listing.\n\nTIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-BaseValueRenderer}[value renderer].\nBecause most value renderers treat lists the same as listings, it is often not necessary to convert back to a listing.\n\nEquipped with this knowledge, let's try to accomplish our objective:\n\n[source%tested,{pkl}]\n----\nreversedbirds = birds\n .toList()\n .reverse()\n .toListing()\n----\n\n`result` now contains the same elements as `birds`, but in reverse order.\n\n[IMPORTANT]\n.Lazy vs. Eager Data Types\n====\nConverting a listing to a list is a transition from a _lazy_ to an _eager_ data type.\nAll of the listing's elements are evaluated and all references between them are resolved.\n\nIf the list is later converted back to a listing, subsequent changes to the listing's elements no longer propagate to (previously) dependent elements.\nTo make these boundaries clear, transitioning between _lazy_ and _eager_ data types always requires an explicit method call, such as `toList()` or `toListing()`.\n====\n\n=== Default Element\n\nListings can have a _default element_:\n\n[source%tested,{pkl}]\n----\nbirds = new Listing {\n default { // <1>\n lifespan = 8\n }\n new { // <2>\n name = \"Pigeon\" // <3>\n }\n new { // <4>\n name = \"Parrot\"\n lifespan = 20 // <5>\n }\n}\n----\n<1> Amends the `default` element and sets property `lifespan`.\n<2> Defines a new listing element that implicitly amends the default element.\n<3> Defines a new property called `name`. Property `lifespan` is inherited from the default element.\n<4> Defines a new listing element that implicitly amends the default element.\n<5> Overrides the default for property `lifespan`.\n\n`default` is a hidden (that is, not rendered) link:{uri-stdlib-Listing-default}[property] defined in class `Listing`.\nIf `birds` had a <>, a suitable default element would be inferred from its type parameter.\nIf, as in our example, no type annotation is provided or inherited, the default element is the empty `Dynamic` object.\n\nLike regular listing elements, the default element is late-bound.\nAs a result, defaults can be changed retroactively:\n\n[source%tested,{pkl}]\n----\nbirds2 = (birds) {\n default {\n lifespan = 8\n diet = \"Seeds\"\n }\n}\n----\n\nBecause both of ``birds``'s elements amend the default element, changing the default element also changes them.\nAn equivalent literal definition of `birds2` would look as follows:\n\n[source%tested,{pkl}]\n----\nbirds2 = new Listing {\n new {\n name = \"Pigeon\"\n lifespan = 8\n diet = \"Seeds\"\n }\n new {\n name = \"Parrot\"\n lifespan = 20\n diet = \"Berries\"\n }\n}\n----\n\nNote that Parrot kept its diet because its prior self defined it explicitly, overriding any default.\n\nIf you are interested in the technical underpinnings of default elements (and not afraid of dragons!), continue with <>.\n\n[[listing-type-annotations]]\n=== Type Annotations\n\nTo declare the type of a property that is intended to hold a listing, use:\n\n[source,{pkl}]\n----\nx: Listing\n----\n\nThis declaration has the following effects:\n\n* `x` is initialized with an empty listing.\n* If `ElementType` has a <>, that value becomes the listing's default element.\n* The first time `x` is read,\n ** its value is checked to have type `Listing`.\n ** the listing's elements are checked to have the type `ElementType`.\n\nHere is an example:\n\n[source%tested,{pkl}]\n----\nclass Bird {\n name: String\n lifespan: Int\n}\n\nbirds: Listing\n----\n\nBecause the default value for type `Bird` is `new Bird {}`, that value becomes the listing's default element.\n\nLet's go ahead and populate `birds`:\n\n[source%tested,{pkl}]\n----\nbirds {\n new {\n name = \"Pigeon\"\n lifespan = 8\n }\n new {\n name = \"Parrot\"\n lifespan = 20\n }\n}\n----\n\nThanks to ``birds``'s default element, which was inferred from its type,\nit is not necessary to state the type of each list element\n(`new Bird { ... }`, `new Bird { ... }`, etc.).\n\n==== Distinct Elements\n\nTo constrain a listing to distinct elements, use ``Listing``'s link:{uri-stdlib-Listing-isDistinct}[isDistinct] property:\n\n[source%tested,{pkl}]\n----\nclass Bird {\n name: String\n lifespan: Int\n}\n\nbirds: Listing(isDistinct)\n----\n\nThis is as close as Pkl's late-bound data types (objects, listings, and mappings) get to a <>.\n\nTo demand distinct names instead of distinct `Bird` objects, use link:{uri-stdlib-Listing-isDistinctBy}[isDistinctBy()]:\n\n[source%tested,{pkl}]\n----\nbirds: Listing(isDistinctBy((it) -> it.name))\n----\n\n[[mappings]]\n== Mappings\n\nA value of type link:{uri-stdlib-Mapping}[Mapping] is an ordered collection of _values_ indexed by _key_.\n\nNOTE: Most of what has been said about <> also applies to mappings.\nNevertheless, this section is written to stand on its own.\n\nA mapping's key-value pairs are called its _entries_.\nKeys are eagerly evaluated; values are lazily evaluated on the first read.\n\nMappings combine qualities of maps and objects:\n\n* Like maps, mappings can contain arbitrary key-value pairs.\n* Like objects, mappings excel at defining and amending nested literal data structures.\n* Like objects, mappings can only be directly manipulated through amendment,\n but converting them to a map (and, if necessary, back to a mapping) opens the door to arbitrary transformations.\n* Like object properties, a mapping's values (but not its keys) are evaluated lazily, can be defined in terms of each other, and are late-bound.\n\n[TIP]\n.When to use Mapping vs. <>\n====\n* When key-value style data needs to be specified literally, use a mapping.\n* When key-value style data needs to be transformed in a way that cannot be achieved by <> a mapping, use a map.\n* If in doubt, use a mapping.\n\nTemplates and schemas should almost always use mappings instead of maps.\nNote that mappings can be converted to maps when the need arises.\n====\n\n=== Defining Mappings\n\nMappings have the same literal syntax as objects, except that keys enclosed in `[]` take the place of property names.\nHere is a mapping with two entries:\n\n[source%tested,{pkl}]\n----\nbirds = new Mapping { // <1>\n [\"Pigeon\"] { // <2>\n lifespan = 8\n diet = \"Seeds\"\n }\n [\"Parrot\"] { // <3>\n lifespan = 20\n diet = \"Berries\"\n }\n}\n----\n<1> Defines a module property named `birds` with a value of type `Mapping`.\n A type only needs to be stated when the property does not have or inherit a <>.\n Otherwise, amend syntax (`birds { ... }`) or shorthand instantiation syntax (`birds = new { ... }`) should be used.\n<2> Defines a mapping entry with the key `\"Pigeon\"` and a value of type `Dynamic`.\n<3> Defines a mapping entry with the key `\"Parrot\"` and a value of type `Dynamic`.\n\nTo access a value by key, use the `[]` (subscript) operator:\n\n[source%tested,{pkl}]\n----\npigeon = birds[\"Pigeon\"]\nparrot = birds[\"Parrot\"]\n----\n\nMappings can contain arbitrary types of values:\n\n[source%tested,{pkl}]\n----\nmapping = new Mapping {\n [\"number\"] = 42\n [\"list\"] = List(\"Pigeon\", \"Parrot\")\n [\"nested mapping\"] {\n [\"Pigeon\"] {\n lifespan = 20\n diet = \"Seeds\"\n }\n }\n}\n----\n\nAlthough string keys are most common, mappings can contain arbitrary types of keys:\n\n[source%tested,{pkl}]\n----\nmapping = new Mapping {\n [3.min] = 42\n [new Dynamic { name = \"Pigeon\" }] = \"abc\"\n}\n----\n\nKeys can be computed:\n\n[source%tested,{pkl}]\n----\nmapping = new Mapping {\n [\"Pigeon\".reverse()] = 42\n}\n----\n\nMappings can have `local` properties:\n\n[source%tested,{pkl}]\n----\nmapping = new Mapping {\n local parrot = \"Parrot\" // <1>\n [\"Pigeon\"] { // <2>\n friend = parrot\n }\n}\n----\n<1> Defines a local property name `parrot` with the value `\"Parrot\"`.\n Local properties can have a type annotation, as in `parrot: String = \"Parrot\"`.\n<2> Defines a mapping entry whose value references `parrot`.\n The local property is visible to values but not keys.\n\n[[amending-mappings]]\n=== Amending Mappings\n\nLet's say we have the following mapping:\n\n[source%tested,{pkl}]\n----\nbirds = new Mapping {\n [\"Pigeon\"] {\n lifespan = 8\n diet = \"Seeds\"\n }\n [\"Parrot\"] {\n lifespan = 20\n diet = \"Berries\"\n }\n}\n----\n\nTo add, override, or amend entries of this mapping, amend the mapping:\n\n[source%tested,{pkl}]\n----\nbirds2 = (birds) { // <1>\n [\"Barn owl\"] { // <2>\n lifespan = 15\n diet = \"Mice\"\n }\n [\"Pigeon\"] { // <3>\n diet = \"Seeds\"\n }\n [\"Parrot\"] = new { // <4>\n lifespan = 20\n diet = \"Berries\"\n }\n}\n----\n<1> Defines a module property named `birds2`. Its value is a mapping that amends `birds`.\n<2> Defines a mapping entry with the key `\"Barn owl\"` and a value of type `Dynamic`.\n<3> Amends mapping entry `\"Pigeon\"` and overrides property `diet`.\n<4> Overrides mapping entry `\"Parrot\"` with an entirely new value of type `Dynamic`.\n\n=== Late Binding\n\nA mapping entry's value can be defined in terms of another entry's value.\nTo reference the value with key ``, use `this[]`:\n\n[source%tested,{pkl}]\n----\nbirds = new Mapping {\n [\"Pigeon\"] { // <1>\n lifespan = 8\n diet = \"Seeds\"\n }\n [\"Parrot\"] = (this[\"Pigeon\"]) { // <2>\n lifespan = 20\n }\n}\n----\n<1> Defines a mapping entry with the key `\"Pigeon\"` and a value of type `Dynamic`.\n<2> Defines a mapping entry with the key `\"Parrot\"` and a value that amends `\"Pigeon\"`.\n\nMapping values are late-bound:\n\n[source%tested,{pkl}]\n----\nbirds2 = (birds) { // <1>\n [\"Pigeon\"] {\n diet = \"Seeds\"\n }\n}\n\nparrotDiet = birds2[\"Parrot\"].diet // <2>\n----\n<1> Amends mapping `birds` and overrides ``\"Pigeon\"``'s `diet` property to have value `\"Seeds\"`.\n<2> Because `\"Parrot\"` is defined in terms of `\"Pigeon\"`, its `diet` property also changes to `\"Seeds\"`.\n\n=== Transforming Mappings\n\nSay we have the following mapping:\n\n[source%tested,{pkl}]\n----\nbirds = new Mapping {\n [\"Pigeon\"] {\n lifespan = 8\n diet = \"Seeds\"\n }\n [\"Parrot\"] = (this[\"Pigeon\"]) {\n lifespan = 20\n }\n}\n----\n\nHow can ``birds``'s keys be reversed programmatically?\n\nThe recipe for transforming a mapping is:\n\n. Convert the mapping to a map.\n. Transform the map using ``Map``'s link:{uri-stdlib-Map}[rich API].\n. If necessary, convert the map back to a mapping.\n\nTIP: Often, transformations happen in a link:{uri-stdlib-PcfRenderer-converters}[converter] of a link:{uri-stdlib-BaseValueRenderer}[value renderer].\nAs most value renderers treat maps the same as mappings, it is often not necessary to convert back to a mapping.\n\nEquipped with this knowledge, let's try to accomplish our objective:\n\n[source%tested,{pkl}]\n----\nresult = birds\n .toMap()\n .mapKeys((key, value) -> key.reverse())\n .toMapping()\n----\n\n`result` contains the same values as `birds`, but its keys have changed to `\"noegiP\"` and `\"torraP\"`.\n\n[IMPORTANT]\n.Lazy vs. Eager Data Types\n====\nConverting a mapping to a map is a transition from a _lazy_ to an _eager_ data type.\nAll of the mapping's values are evaluated and all references between them are resolved.\n(Mapping keys are eagerly evaluated.)\n\nIf the map is later converted back to a mapping, changes to the mapping's values no longer propagate to (previously) dependent values.\nTo make these boundaries clear, transitioning between _lazy_ and _eager_ data types always requires an explicit method call, such as `toMap()` or `toMapping()`.\n====\n\n=== Default Value\n\nMappings can have a _default value_:\n\n[source%tested,{pkl}]\n----\nbirds = new Mapping {\n default { // <1>\n lifespan = 8\n }\n [\"Pigeon\"] { // <2>\n diet = \"Seeds\" // <3>\n }\n [\"Parrot\"] { // <4>\n lifespan = 20 // <5>\n }\n}\n----\n<1> Amends the `default` value and sets property `lifespan`.\n<2> Defines a mapping entry with the key `\"Pigeon\"` that implicitly amends the default value.\n<3> Defines a new property called `diet`. Property `lifespan` is inherited from the default value.\n<4> Defines a mapping entry with the key `\"Parrot\"` that implicitly amends the default value.\n<5> Overrides the default for property `lifespan`.\n\n`default` is a hidden (that is, not rendered) link:{uri-stdlib-Mapping-default}[property] defined in class `Mapping`.\nIf `birds` had a <>, a suitable default value would be inferred from its second type parameter.\nIf, as in our example, no type annotation is provided or inherited, the default value is the empty `Dynamic` object.\n\nLike regular mapping values, the default value is late-bound.\nAs a result, defaults can be changed retroactively:\n\n[source%tested,{pkl}]\n----\nbirds2 = (birds) {\n default {\n lifespan = 8\n diet = \"Seeds\"\n }\n}\n----\n\nBecause both of ``birds``'s mapping values amend the default value, changing the default value also changes them.\nAn equivalent literal definition of `birds2` would look as follows:\n\n[source%tested,{pkl}]\n----\nbirds2 = new Mapping {\n [\"Pigeon\"] {\n lifespan = 8\n diet = \"Seeds\"\n }\n [\"Parrot\"] {\n lifespan = 20\n diet = \"Berries\"\n }\n}\n----\n\nNote that Parrot kept its lifespan because its prior self defined it explicitly, overriding any default.\n\nIf you are interested in the technical underpinnings of default values, continue with <>.\n\n[[mapping-type-annotations]]\n=== Type Annotations\n\nTo declare the type of a property that is intended to hold a mapping, use:\n\n[source,{pkl}]\n----\nx: Mapping\n----\n\nThis declaration has the following effects:\n\n* `x` is initialized with an empty mapping.\n* If `ValueType` has a <>, that value becomes the mapping's default value.\n* The first time `x` is read,\n ** its value is checked to have type `Mapping`.\n ** the mapping's keys are checked to have type `KeyType`.\n ** the mapping's values are checked to have type `ValueType`.\n\nHere is an example:\n\n[source%tested,{pkl}]\n----\nclass Bird {\n lifespan: Int\n}\n\nbirds: Mapping\n----\n\nBecause the default value for type `Bird` is `new Bird {}`, that value becomes the mapping's default value.\n\nLet's go ahead and populate `birds`:\n\n[source%tested,{pkl}]\n----\nbirds {\n [\"Pigeon\"] {\n lifespan = 8\n }\n [\"Parrot\"] {\n lifespan = 20\n }\n}\n----\n\nThanks to ``birds``'s default value, which was inferred from its type,\nit is not necessary to state the type of each mapping value\n(`[\"Pigeon\"] = new Bird { ... }`, `[\"Parrot\"] = new Bird { ... }`, etc.).\n\n[[classes]]\n== Classes\n\nClasses are arranged in a single inheritance hierarchy.\nAt the top of the hierarchy sits class link:{uri-stdlib-Any}[Any]; at the bottom, type <>.\n\nClasses contain properties and methods, which can be `local` to their declaring scope.\nProperties can also be `hidden` from rendering.\n\n[source%tested,{pkl}]\n----\nclass Bird {\n name: String\n hidden taxonomy: Taxonomy\n}\n\nclass Taxonomy {\n `species`: String\n}\n\npigeon: Bird = new {\n name = \"Common wood pigeon\"\n taxonomy {\n species = \"Columba palumbus\"\n }\n}\n\npigeonClass = pigeon.getClass()\n----\n\nDeclaration of new class instances will fail when property names are misspelled: \n\n[source%tested%error,{pkl}]\n----\n// Detects the spelling mistake\nparrot = new Bird {\n namw = \"Parrot\"\n}\n----\n\n=== Class Inheritance\n\nPkl supports single inheritance with a Java(Script)-like syntax.\n\n[source%tested,{pkl}]\n----\nabstract class Bird {\n name: String\n}\n\nclass ParentBird extends Bird {\n kids: List\n}\n\npigeon: ParentBird = new {\n name = \"Old Pigeon\"\n kids = List(\"Pigeon Jr.\", \"Teen Pigeon\")\n}\n----\n\n[[methods]]\n== Methods\n\nPkl methods can be defined on classes and modules using the `function` keyword.\nMethods may access properties of their containing type.\nSubmodules and subclasses can override them.\n\nLike Java and most other object-oriented languages, Pkl uses _single dispatch_ -- methods are dynamically dispatched based on the receiver's runtime type.\n\n[source%tested,{pkl}]\n----\nclass Bird {\n name: String\n function greet(bird: Bird): String = \"Hello, \\(bird.name)!\" // <1>\n}\n\nfunction greetPigeon(bird: Bird): String = bird.greet(pigeon) // <2>\n\npigeon: Bird = new {\n name = \"Pigeon\"\n}\nparrot: Bird = new {\n name = \"Parrot\"\n}\n\ngreeting1 = pigeon.greet(parrot) // <3>\ngreeting2 = greetPigeon(parrot) // <4>\n----\n<1> Instance method of class `Bird`.\n<2> Module method.\n<3> Call instance method on `pigeon`.\n<4> Call module method (on `this`).\n\nLike other object-oriented languages, methods defined on extended classes and modules may be overridden.\nThe parent type's method may be called via the <>.\n\nNOTE: Methods do not support named parameters or default parameter values.\nThe xref:blog:ROOT:class-as-a-function.adoc[Class-as-a-function] pattern may be a suitable replacement.\n\nTIP: In most cases, methods without parameters should not be defined.\nInstead, use <> on the module or class.\n\n[[modules]]\n== Modules\n\n=== Introduction\n\nModules are the unit of loading, executing, and sharing Pkl code.\nEvery file containing Pkl code is a module.\nBy convention, module files have a `.pkl` extension.\n\nModules have a <> and are loaded from a <>.\n\nAt runtime, modules are represented as objects of type link:{uri-stdlib-baseModule}/Module[Module].\nThe precise runtime type of a module is a subclass of `Module` containing the module's property and method definitions.\n\nLike class members, module members may have type annotations, which are validated at runtime:\n\n[source%tested,{pkl}]\n----\ntimeout: Duration(isPositive) = 5.ms\n\nfunction greet(name: String): String = \"Hello, \\(name)!\"\n----\n\nBecause modules are regular objects, they can be assigned to properties and passed to and returned from methods.\n\nModules can be <> by other modules.\nIn analogy to objects, modules can serve as templates for other modules through <>.\nIn analogy to classes, modules can be <> to add additional module members.\n\n=== Module Names\n\nModules may declare their name by way of a _module clause_, which consists of the keyword `module` followed by a qualified name:\n\n[source%tested,{pkl}]\n----\n/// My bird module.\nmodule com.animals.Birds\n----\n\nA module clause must come first in a module.\nIts doc comment, if present, holds the module's overall documentation.\n\nIn the absence of a module clause, a module's name is inferred from the module URI from which the module was first loaded.\nFor example, the inferred name for a module first loaded from `+https://example.com/pkl/bird.pkl+` is `bird`.\n\nModule names do not affect evaluation but are used in diagnostic messages and Pkldoc.\nIn particular, they are the first component (everything before the hash sign) of fully qualified member names such as `pkl.base#Int`.\n\nNOTE: Modules shared with other parties should declare a qualified module name, which is more unique and stable than an inferred name.\n\n=== Module URIs\n\nModules are loaded from _module URIs_.\n\nBy default, the following URI types are available for import:\n\n==== File URI:\nExample: `+file:///path/to/my_module.pkl+` \n\nRepresents a module located on a file system.\n\n==== HTTP(S) URI:\nExample: `+https://example.com/my_module.pkl+` \n\nRepresents a module imported via an HTTP(S) GET request.\n\nNOTE: Modules loaded from HTTP(S) URIs are only cached until the `pkl` command exits or the `Evaluator` object is closed.\n\n[[module-path-uri]]\n==== Module path URI:\nExample: `+modulepath:/path/to/my_module.pkl+`\n\nModule path URIs are resolved relative to the _module path_, a search path for modules similar to Java's class path (see the `--module-path` CLI option).\nFor example, given the module path `/dir1:/zip1.zip:/jar1.jar`, module `+modulepath:/path/to/my_module.pkl+` will be searched for in the following locations:\n\n. `/dir1/path/to/my_module.pkl`\n. `/path/to/my_module.pkl` within `/zip1.zip`\n. `/path/to/my_module.pkl` within `/jar1.jar`\n\nWhen evaluating Pkl code from Java, `+modulepath:/path/to/my_module.pkl+` corresponds to class path location `path/to/my_module.pkl`.\nIn a typical Java project, this corresponds to file path `src/main/resources/path/to/my_module.pkl` or `src/test/resources/path/to/my_module.pkl`.\n\n[[package-asset-uri]]\n==== Package asset URI:\nExample: `+package://example.com/mypackage@1.0.0#/my_module.pkl+`\n\nRepresent a module within a _package_.\nA package is a shareable archive of modules and resources that are published to the internet.\n\nTo import `package://example.com/mypackage@1.0.0#/my_module.pkl`, Pkl follows these steps:\n\n1. Make an HTTPS GET request to `\\https://example.com/mypackage@1.0.0` to retrieve the package's metadata.\n2. From the package metadata, download the referenced zip archive, and validate its checksum.\n3. Resolve path `/my_module.pkl` within the package's zip archive.\n\nA package asset URI has the following form:\n\n----\n'package://' '@' '#' \n----\n\nOptionally, the SHA-256 checksum of the package can also be specified:\n\n[source]\n----\n'package://' '@' '::sha256:' '#' \n----\n\nPackages can be managed as dependencies within a _project_.\nFor more details, consult the <> section of the language reference.\n\nPackages can also be downloaded from a mirror.\nFor more details, consult the <> section of the language reference.\n\n==== Standard Library URI\n\nExample: `+pkl:math+`\n\nStandard library modules are named `pkl.` and have module URIs of the form `pkl:`.\nFor example, module `pkl.math` has module URI `pkl:math`.\nSee the link:{uri-pkl-stdlib-docs-index}[API Docs] for the complete list of standard library modules.\n\n==== Relative URIs\n\nRelative module URIs are interpreted relative to the URI of the enclosing module.\nFor example, a module with URI `modulepath:/animals/birds/pigeon.pkl`\ncan import `modulepath:/animals/birds/parrot.pkl`\nwith `import \"parrot.pkl\"` or `import \"/animals/birds/parrot.pkl\"`.\n\n[NOTE]\n.Paths on Windows\n====\nRelative paths use the `/` character as the directory separator on all platforms, including Windows.\n\nPaths that contain drive letters (e.g. `C:`) must be declared as an absolute file URI, for example: `import \"file:///C:/path/to/my/module.pkl\"`. Otherwise, they are interpreted as a URI scheme.\n====\n\nNOTE: When importing a relative directory or file that starts with `@`, the import string must be prefixed with `./`.\nOtherwise, this syntax will be interpreted as xref:dependency-notation[dependency notation].\n\n[#dependency-notation]\n==== Dependency notation URIs\n\nExample: `+@birds/bird.pkl+`\n\nDependency notation URIs represent a path within a <>.\nFor example, import `@birds/bird.pkl` represents path `/bird.pkl` in a dependency named \"birds\".\n\nA dependency is either a remote package or a local project dependency.\n\n==== Extension points\n\nPkl embedders can register additional module loaders that recognize other types of module URIs.\n\n==== Evaluation\n\nModule URIs can be evaluated directly:\n\n[source,shell]\n----\n$ pkl eval path/to/mymodule.pkl\n$ pkl eval file:///path/to/my_module.pkl\n$ pkl eval https://apple.com/path/to/mymodule.pkl\n$ pkl eval --module-path=/pkl-modules modulepath:/path/to/my_module.pkl\n$ pkl eval pkl:math\n----\n\n[[triple-dot-module-uris]]\n==== Triple-dot Module URIs\n\nTo simplify referencing ancestor modules in a hierarchical module structure,\nrelative file and module path URIs may start with `++...++/`, a generalization of `../`.\nModule URI `++...++/foo/bar/baz.pkl` resolves to the first existing module among\n`../foo/bar/baz.pkl`, `../../foo/bar/baz.pkl`, `../../../foo/bar/baz.pkl`, and so on.\nFurthermore, module URI `++...++` is equivalent to `++...++/`.\n\nUsing triple-dot module URIs never resolve to the current module.\nFor example, a module at path `foo/bar.pkl` that references module URI `++...++/foo/bar.pkl`\ndoes not resolve to itself.\n\n[[module-amend]]\n=== Amending a Module\n\nRecall how an object is amended:\n\n[source%tested,{pkl}]\n----\npigeon {\n name = \"Pigeon\"\n diet = \"Seeds\"\n}\n\nparrot = (pigeon) { // <1>\n name = \"Parrot\" // <2>\n}\n----\n<1> Object `parrot` amends object `pigeon`, inheriting all of its members.\n<2> `parrot` overrides `name`.\n\nAmending a module works in the same way, except that the syntax differs slightly:\n\n.pigeon.pkl\n[source%tested,{pkl}]\n----\nname = \"Pigeon\"\ndiet = \"Seeds\"\n----\n\n.parrot.pkl\n[source%parsed,{pkl}]\n----\namends \"pigeon.pkl\" // <1>\n\nname = \"Parrot\" // <2>\n----\n<1> Module `parrot` amends module `pigeon`, inheriting all of its members.\n<2> `parrot` overrides `name`.\n\nA module is amended by way of an _amends clause_, which consists of the keyword `amends` followed by the <> of the module to amend.\n\nAn amends clause comes after the module clause (if present) and before any import clauses:\n\n.parrot.pkl\n[source%parsed,{pkl}]\n----\nmodule parrot\n\namends \"pigeon.pkl\"\n\nimport \"other.pkl\"\n\nname = \"Parrot\"\n----\n\nAt most one amends clause is permitted.\nA module cannot have both an amends clause and an extends clause.\n\nAn amending module has the same type (that is, module class) as the module it amends.\nAs a consequence, it cannot define new properties, methods, or classes, unless they are declared as `local`.\nIn our example, this means that module `parrot` can only define (and thus override) the property `name`.\nSpelling mistakes such as `namw` are caught immediately, rather than accidentally defining a new property.\n\nAmending is used to fill in _template modules_:\n\n. The template module defines which properties exist, their types, and what module output is desired (for example JSON indented with two spaces).\n. The amending module fills in property values as required, relying on the structure, defaults and validation provided by the template module.\n. The amending module is evaluated to produce the final result.\n\nTemplate modules are often provided by third parties and served over HTTPS.\n\n[[module-extend]]\n=== Extending a Module\n\nRecall how a class is extended:\n\n.PigeonAndParrot.pkl\n[source%tested,{pkl}]\n----\nopen class Pigeon { // <1>\n name = \"Pigeon\"\n diet = \"Seeds\"\n}\n\nclass Parrot extends Pigeon { // <2>\n name = \"Parrot\" // <3>\n diet = \"Berries\" // <4>\n extinct = false // <5>\n\n function say() = \"Pkl is great!\" // <6>\n}\n----\n<1> Class `Pigeon` is declared as `open` for extension.\n<2> Class `Parrot` extends `Pigeon`, inheriting all of its members.\n<3> `Parrot` overrides `name`.\n<4> `Parrot` overrides `diet`.\n<5> `Parrot` defines a new property named `extinct`.\n<6> `Parrot` defines a new function named `say`.\n\nExtending a module works in the same way, except that the syntax differs slightly:\n\n.pigeon.pkl\n[source%tested,{pkl}]\n----\nopen module pigeon // <1>\n\nname = \"Pigeon\"\ndiet = \"Seeds\"\n----\n<1> Module `pigeon` is declared as `open` for extension.\n\n.parrot.pkl\n[source%parsed,{pkl}]\n----\nextends \"pigeon.pkl\" // <1>\n\nname = \"Parrot\" // <2>\ndiet = \"Berries\" // <3>\nextinct = false // <4>\n\nfunction say() = \"Pkl is great!\" // <5>\n----\n<1> Module `parrot` extends module `pigeon`, inheriting all of its members.\n<2> `parrot` overrides `name`.\n<3> `parrot` overrides `diet`.\n<4> `parrot` defines a new property named `extinct`.\n<5> `parrot` defines a new function named `say`.\n\nA module is extended by way of an _extends clause_, which consists of the keyword `extends` followed by the <> of the module to extend.\nThe extends clause comes after the module clause (if present) and before any import clauses.\nOnly modules declared as `open` can be extended.\n\n.parrot.pkl\n[source%parsed,{pkl}]\n----\nmodule parrot\n\nextends \"pigeon.pkl\"\n\nimport \"other.pkl\"\n\nname = \"Parrot\"\ndiet = \"Berries\"\nextinct = false\n\nfunction say() = \"Pkl is great!\"\n----\n\nAt most one extends clause is permitted.\nA module cannot have both an amends clause and an extends clause.\n\nExtending a module implicitly defines a new module class that extends the original module's class.\n\n[[import-module]]\n=== Importing a Module\n\nA module import makes the imported module accessible to the importing module.\nA module is imported by way of either an <>, or an <>.\n\n[[import-clause]]\n==== Import Clauses\n\nAn import clause consists of the keyword `import` followed by the <> of the module to import.\nAn import clause comes after module, amends and extends clauses (if present), and before the module body:\n\n.parrot.pkl\n[source%parsed,{pkl}]\n----\nmodule parrot\n\namends \"pigeon.pkl\"\n\nimport \"module1.pkl\"\nimport \"module2.pkl\"\n\nname = \"Parrot\"\n----\n\nMultiple import clauses are permitted.\n\nA module import implicitly defines a new `const local` property through which the imported module can be accessed.\n(Remember that modules are regular objects.)\nThe name of this property, called _import name_, is constructed from the module URI as follows:\n\n. Strip the URI scheme, including the colon (`:`).\n. Strip everything up to and including the last forward slash (`/`).\n. Strip any trailing `.pkl` file extension.\n\nHere are some examples:\n\n.Local file import\n[source%parsed,{pkl}]\n----\nimport \"modules/pigeon.pkl\" // relative to current module\n\nname = pigeon.name\n----\n\n.HTTPS import\n[source%parsed,{pkl}]\n----\nimport \"https://mycompany.com/modules/pigeon.pkl\"\n\nname = pigeon.name\n----\n\n.Standard library import\n[source%parsed,{pkl}]\n----\nimport \"pkl:math\"\n\npi = math.Pi\n----\n\n.Package import\n[source%parsed,{pkl}]\n----\nimport \"package://example.com/birds@1.0.0#/sparrow.pkl\"\n\nname = sparrow.name\n----\n\nBecause its members are automatically visible in every module, the `pkl:base` module is typically not imported.\n\nOccasionally, the default import name for a module may not be convenient or appropriate:\n\n* If not a valid identifier, the import name needs to be enclosed in backticks on each use, for example, ``my-module`.someMember`.\n* The import name may clash with other names in the importing module.\n\nIn such a case, a different import name can be chosen:\n\n.parrot.pkl\n[source%parsed,{pkl}]\n----\nimport \"pigeon.pkl\" as piggy\n\nname = \"Parrot\"\ndiet = piggy.diet\n----\n\n[TIP]\n.What makes a good module file name?\n====\nWhen creating a new module, especially one intended for import into other modules, try to choose a module file name that makes a good import name:\n\n* short\n+\nLess than six characters, not counting the `.pkl` file extension, is a good rule of thumb.\n* valid identifier\n+\nStick to alphanumeric characters. Use an underscore (`_`) instead of a hyphen (`-`) as a name separator.\n* descriptive\n+\nAn import name should make sense on its own and when used in qualified member names.\n====\n\n[[import-expression]]\n==== Import Expressions (`import()`)\n\nAn import expression consists of the keyword `import`, followed by a <> wrapped in parentheses:\n\n[source,{pkl}]\n----\nmodule birds\n\npigeon = import(\"pigeon.pkl\")\nparrot = import(\"parrot.pkl\")\n----\n\nUnlike import clauses, import expressions only import a value, and do not import a type.\nA type is a name that can be used in type positions, for example, as a type annotation.\n\n[[globbed-imports]]\n=== Globbed Imports\n\nMultiple modules may be imported at once with `import*`.\nWhen importing multiple modules, a glob pattern is used to match against existing resources.\nA globbed import evaluates to a `Mapping`, where keys are the expanded form of the glob and values are import expressions on each individual module.\n\nGlobbed imports can be expressed as either a clause or as an expression.\nWhen expressed as a clause, they follow the same naming rules as a normal <>: they introduce a local property equal to the last path segment without the `.pkl` extension.\nA globbed import clause cannot be used as a type.\n\n[source,{pkl}]\n----\nimport* \"birds/*.pkl\" as allBirds // <1>\nimport* \"reptiles/*.pkl\" <2>\n\nbirds = import*(\"birds/*.pkl\") // <3>\n----\n<1> Globbed import clause\n<2> Globbed import clause without an explicit name (will import the name `*`)\n<3> Globbed import expression\n\nAssuming that a file system contains these files:\n\n[source,txt]\n----\n.\n├── birds/\n│ ├── pigeon.pkl\n│ ├── parrot.pkl\n│ └── falcon.pkl\n└── index.pkl\n----\n\nThe following two snippets are logically identical:\n\n.index.pkl\n[source,{pkl}]\n----\nbirds = import*(\"birds/*.pkl\")\n----\n\n.index.pkl\n[source,{pkl}]\n----\nbirds = new Mapping {\n [\"birds/pigeon.pkl\"] = import(\"birds/pigeon.pkl\")\n [\"birds/parrot.pkl\"] = import(\"birds/parrot.pkl\")\n [\"birds/falcon.pkl\"] = import(\"birds/falcon.pkl\")\n}\n----\n\nBy default, only the `file` and `package` schemes are globbable.\nGlobbing another scheme will cause Pkl to throw.\n\nPkl can be extended to provide custom globbable schemes through the link:{uri-pkl-core-ModuleKey}[ModuleKey]\nSPI.\n\nWhen globbing within <>, only the asset path (the fragment section) is globbable.\nOtherwise, characters are interpreted verbatim, and not treated as glob wildcards.\n\nFor details on how glob patterns work, refer to <> in the Advanced Topics section.\n\nNOTE: When globbing files, symbolic links are not followed. Additionally, the `.` and `..` entries are skipped. +\nThis behavior is similar to the behavior of Bash with `shopt -s dotglob` enabled.\n\n=== Security Checks\n\nWhen attempting to directly evaluate a module, as in `pkl eval myModule.pkl`,\nthe following security checks are performed:\n\n* The module URI is checked against the module allowlist (`--allowed-modules`).\n\nThe module allowlist is a comma-separated list of regular expressions.\nFor access to be granted, at least one regular expression must match a prefix of the module URI.\nFor example, the allowlist `file:,https:` grants access to any module whose URI starts with `file:` or `https:`.\n\nWhen a module attempts to load another module (via `amends`, `extends`, or `imports`),\nthe following security checks are performed:\n\n* The target module URI is checked against the module allowlist (`--allowed-modules`).\n* The source and target modules' _trust levels_ are determined and compared.\n\nFor access to be granted, the source module's trust level must be greater than or equal to the target module's trust level.\nBy default, there are five trust levels, listed from highest to lowest:\n\n. `repl:` modules (code evaluated in the REPL)\n. `file:` modules\n. `modulepath:` modules\n. All other modules (for example `https:`)\n. `pkl:` modules (standard library)\n\nFor example, this means that `file:` modules can import `https:` modules, but not the other way around.\n\nIf a module URI is resolved in multiple steps, all URIs are subject to the above security checks.\nAn example of this is an HTTPS URL that results in a redirect.\n\nPkl embedders can further customize security checks.\n\n[[module-output]]\n=== Module Output\n\nBy default, the output of evaluating a module is the entire module rendered as Pcf.\nThere are two ways to change this behavior:\n\n1. _Outside_ the language, by using the `--format` CLI option or the `outputFormat` Gradle task property.\n2. _Inside_ the language, by configuring a module's `output` property.\n\n==== CLI\n\nGiven the following module:\n\n[source%tested,{pkl}]\n.config.pkl\n----\na = 10\nb {\n c = 20\n}\n----\n\n`pkl eval config.pkl`, which is shorthand for `pkl eval --format pcf config.pkl`, renders the module as Pcf:\n\n[source,{pkl}]\n----\na = 10\nb {\n c = 20\n}\n----\n\n`pkl eval --format yaml config.pkl` renders the module as YAML:\n\n[source,yaml]\n----\na: 10\nb:\n c: 20\n----\n\nLikewise, `pkl eval --format json config.pkl` renders the module as JSON.\n\n[[in-language]]\n==== In-language\n\nNow let's do the same -- and more -- inside the language.\n\nModules have an link:{uri-stdlib-baseModule}/Module#output[output] property that controls what the module's output is and how that output is rendered.\n\nTo control *what* the output is, set the link:{uri-stdlib-baseModule}/ModuleOutput#value[output.value] property:\n\n[source%parsed,{pkl}]\n----\na = 10\nb {\n c = 20\n}\noutput {\n value = b // defaults to `outer`, which is the entire module\n}\n----\n\nThis produces:\n\n[source,{pkl}]\n----\nc = 20\n----\n\nTo control _how_ the output is rendered, set the link:{uri-stdlib-baseModule}/ModuleOutput#renderer[output.renderer] property:\n\n[source%parsed,{pkl}]\n----\na = 10\nb {\n c = 20\n}\n\noutput {\n renderer = new YamlRenderer {}\n}\n----\n\nThe standard library provides these renderers:\n\n* link:{uri-stdlib-baseModule}/JsonRenderer[JsonRenderer]\n* link:{uri-stdlib-jsonnetModule}/Renderer[jsonnet.Renderer]\n* link:{uri-stdlib-baseModule}/PcfRenderer[PcfRenderer]\n* link:{uri-stdlib-baseModule}/PListRenderer[PListRenderer]\n* link:{uri-stdlib-baseModule}/PropertiesRenderer[PropertiesRenderer]\n* link:{uri-stdlib-protobufModule}/Renderer[protobuf.Renderer]\n* link:{uri-stdlib-xmlModule}/Renderer[xml.Renderer]\n* link:{uri-stdlib-baseModule}/YamlRenderer[YamlRenderer]\n\nTo render a format that is not yet supported, you can implement your own renderer by extending the class link:{uri-stdlib-baseModule}/ValueRenderer[ValueRenderer].\n\nThe standard library renderers can be configured with _value converters_, which influence how particular values are rendered.\n\nFor example, since YAML does not have a standard way to represent data sizes, a plain `YamlRenderer` cannot render `DataSize` values.\nHowever, we can teach it to:\n\n[source%parsed,{pkl}]\n----\nquota {\n memory = 100.mb\n disk = 20.gb\n}\n\noutput {\n renderer = new YamlRenderer {\n converters {\n [DataSize] = (size) -> \"\\(size.value) \\(size.unit)\"\n }\n }\n}\n----\n\nThis produces:\n\n[source,yaml]\n----\nquota:\n memory: 100 MB\n disk: 20 GB\n----\n\nIn addition to _class_-based converters, renderers also support _path_-based converters:\n\n[source%parsed,{pkl}]\n----\noutput {\n renderer = new YamlRenderer {\n converters {\n [\"quota.memory\"] = (size) -> \"\\(size.value) \\(size.unit)\"\n [\"quota.disk\"] = (size) -> \"\\(size.value) \\(size.unit)\"\n }\n }\n}\n----\n\nFor more on path-based converters, see {uri-stdlib-PcfRenderer-converters}[PcfRenderer.converters].\n\nSpecial <> may also be used to influence how class properties are rendered.\nThe `ConvertProperty` annotation (and subclasses of it) are automatically applied during.\nFor more on annotation-based converters, see link:{uri-stdlib-ConvertProperty}[ConvertProperty].\n\nSometimes it is useful to directly compute the final module output, bypassing `output.value` and `output.converters`.\nTo do so, set the link:{uri-stdlib-baseModule}/ModuleOutput#text[output.text] property to a String value:\n\n[source%parsed,{pkl}]\n----\noutput {\n // defaults to `renderer.render(value)`\n text = \"this is the final output\".toUpperCase()\n}\n----\n\nThis produces:\n\n[source]\n----\nTHIS IS THE FINAL OUTPUT\n----\n\n[[multiple-file-output]]\n==== Multiple File Output\n\nIt is sometimes desirable for a single module to produce multiple output files.\nThis is possible by configuring a module's link:{uri-stdlib-outputFiles}[`output.files`] property \n// suppress inspection \"AsciiDocLinkResolve\"\nand specifying the xref:pkl-cli:index.adoc#multiple-file-output-path[`--multiple-file-output-path`]\n(or `-m` for short) CLI option.\n\nHere is an example that produces a JSON and a YAML file:\n\n.birds.pkl\n[source%parsed,{pkl}]\n----\npigeon {\n name = \"Pigeon\"\n diet = \"Seeds\"\n}\nparrot {\n name = \"Parrot\"\n diet = \"Seeds\"\n}\noutput {\n files {\n [\"birds/pigeon.json\"] {\n value = pigeon\n renderer = new JsonRenderer {}\n }\n [\"birds/parrot.yaml\"] {\n value = parrot\n renderer = new YamlRenderer {}\n }\n }\n}\n----\n\nRunning `pkl eval -m output/ birds.pkl` produces the following output files:\n\n.output/birds/pigeon.json\n[source,json]\n----\n{\n \"name\": \"Pigeon\",\n \"diet\": \"Seeds\"\n}\n----\n\n.output/birds/parrot.yaml\n[source,yaml]\n----\nname: Parrot\ndiet: Berries\n----\n\nWithin `output.files`, \na key determines a file's path relative to `--multiple-file-output-path`, \nand a value determines the file's contents.\nIf a file's path resolves to a location outside `--multiple-file-output-path`, \nevaluation fails with an error.\nNon-existing parent directories are created.\n\n[[aggregating-module-outputs]]\n===== Aggregating Module Outputs\n\nA value within `output.files` can be another module's `output`.\nWith this, a module can aggregate the outputs of multiple other modules.\nHere is an example:\n\n.pigeon.pkl\n[source%parsed,{pkl}]\n----\nname = \"Pigeon\"\ndiet = \"Seeds\"\noutput {\n renderer = new JsonRenderer {}\n}\n----\n\n.parrot.pkl\n[source%parsed,{pkl}]\n----\nname = \"Parrot\"\ndiet = \"Seeds\"\noutput {\n renderer = new YamlRenderer {}\n}\n----\n\n.birds.pkl\n[source%parsed,{pkl}]\n----\nimport \"pigeon.pkl\"\nimport \"parrot.pkl\"\n\noutput {\n files {\n [\"birds/pigeon.json\"] = pigeon.output\n [\"birds/parrot.yaml\"] = parrot.output\n }\n}\n----\n\n[TIP]\n====\nWhen aggregating module outputs,\nthe appropriate file extensions can be obtained programmatically:\n\n.birds.pkl\n[source%parsed,{pkl}]\n----\nimport \"pigeon.pkl\"\nimport \"parrot.pkl\"\n\noutput {\n files {\n [\"birds/pigeon.\\(pigeon.output.renderer.extension)\"] = pigeon.output\n [\"birds/parrot.\\(parrot.output.renderer.extension)\"] = parrot.output\n }\n}\n----\n====\n\n[[null-values]]\n== Null Values\n\nThe keyword `null` indicates the absence of a value.\n`null` is an instance of link:{uri-stdlib-Null}[Null], a direct subclass of `Any`.\n\n=== Non-Null Operator\n\nThe `!!` (non-null) operator asserts that its operand is non-null.\nHere are some examples:\n\n[source%tested%error,{pkl}]\n----\nname = \"Pigeon\"\nnameNonNull = name!! // <1>\n\nname2 = null\nname2NonNull = name2!! // <2>\n----\n<1> result: `\"Pigeon\"`\n<2> result: _Error: Expected a non-null value, but got `null`._\n\n=== Null Coalescing\n\nThe `??` (null coalescing) operator fills in a default for a `null` value.\n\n[source,{pkl-expr}]\n----\nvalue ?? default\n----\n\nThe above expression evaluates to `value` if `value` is non-null, and to `default` otherwise.\nHere are some examples:\n\n[source%tested,{pkl}]\n----\nname = \"Pigeon\"\nnameOrParrot = name ?? \"Parrot\" // <1>\n\nname2 = null\nname2OrParrot = name2 ?? \"Parrot\" // <2>\n----\n<1> result: `\"Pigeon\"`\n<2> result: `\"Parrot\"`\n\n[NOTE]\n.Default non-null behavior\n====\nMany languages allow `null` for (almost) every type, but Pkl does not.\nAny type can be extended to include `null` by appending `?` to the type.\n\nFor example, `parrot: Bird` will always be non-null, but `pigeon: Bird?` could be `null` - and _is_ by default,\nif `pigeon` is never amended. This means if you try to coalesce a (non-nullable) typed variable,\nthe result is always that variable’s value.\n\nAs per our example `parrot ?? pigeon == parrot` always holds,\nbut `pigeon ?? parrot` could either be `pigeon` or `parrot`,\ndepending on whether `pigeon` was ever amended with a non-null value.\n====\n\n[[null-propagation]]\n=== Null Propagation\n\nThe `?.` (null propagation) operator provides null-safe access to a member whose receiver may be `null`.\n\n[source,{pkl-expr}]\n----\nvalue?.member\n----\n\nThe above expression evaluates to `value.member` if `value` is non-null, and to `null` otherwise.\nHere are some examples:\n\n[source%tested,{pkl}]\n----\nname = \"Pigeon\"\nnameLength = name?.length // <1>\nnameUpper = name?.toUpperCase() // <2>\n\nname2 = null\nname2Length = name2?.length // <3>\nname2Upper = name2?.toUpperCase() // <4>\n----\n<1> result: `6`\n<2> result: `\"PIGEON\"`\n<3> result: `null`\n<4> result: `null`\n\nThe `?.` operator is often combined with `??`:\n\n[source%tested,{pkl}]\n----\nname = null\nnameLength = name?.length ?? 0 // <1>\n----\n<1> result: `0`\n\n=== ifNonNull Method\n\nThe link:{uri-stdlib-ifNonNull}[ifNonNull()] method is a generalization of the <> operator.\n\n[source%parsed,{pkl-expr}]\n----\nname.ifNonNull((it) -> doSomethingWith(it))\n----\n\nThe above expression evaluates to `doSomethingWith(name)` if `name` is non-null, and to `null` otherwise.\nHere are some examples:\n\n[source%tested,{pkl}]\n----\nname = \"Pigeon\"\nnameWithTitle = name.ifNonNull((it) -> \"Dr.\" + it) // <1>\n\nname2 = null\nname2WithTitle = name2.ifNonNull((it) -> \"Dr.\" + it) // <2>\n----\n<1> result: `\"Dr. Pigeon\"`\n<2> result: `null`\n\n=== NonNull Type Alias\n\nTo express that a property can have any type except `Null`, use the `NonNull` <>:\n\n[source,{pkl}]\n----\nx: NonNull\n----\n\n[[if-expressions]]\n== If Expressions\n\nAn `if` expression serves the same role as the ternary operator (`? :`) in other languages.\nEvery `if` expression must have an `else` branch.\n\n[source%tested,{pkl}]\n----\nnum = if (2 + 2 == 5) 1984 else 42 // <1>\n----\n<1> result: `42`\n\n[[resources]]\n== Resources\n\nPkl programs can read external resources, such as environment variables or text files.\n\nTo read a resource, use a `read` expression:\n\n[source%parsed,{pkl}]\n----\npath = read(\"env:PATH\")\n----\n\nBy default, the following resource URI schemes are supported:\n\nenv: :: Reads an environment variable.\nResult type is `String`.\nprop: :: Reads an external property set via the `-p name=value` CLI option.\nResult type is `String`.\nfile: :: Reads a file from the file system.\nResult type is link:{uri-stdlib-Resource}[Resource].\nhttp(s): :: Reads an HTTP(S) resource.\nResult type is link:{uri-stdlib-Resource}[Resource].\nmodulepath: :: Reads a resource from the module path (`--module-path`) or JVM class path.\nResult type is link:{uri-stdlib-Resource}[Resource].\nSee <> for further information.\npackage: :: Reads a resource from a _package_. Result type is link:{uri-stdlib-Resource}[Resource]. See <> for further information.\n\nRelative resource URIs are resolved against the enclosing module's URI.\n\nResources are cached in memory on the first read.\nTherefore, subsequent reads are guaranteed to return the same result.\n\n[[nullable-reads]]\n=== Nullable Reads\n\nIf a resource does not exist or cannot be read, `read()` fails with an error.\nTo recover from the absence of a resource, use `read?()` instead,\nwhich returns `null` for absent resources:\n\n[source%parsed,{pkl}]\n----\nport = read?(\"env:PORT\")?.toInt() ?? 1234\n----\n\n[[globbed-reads]]\n=== Globbed Reads\n\nMultiple resources may be read at the same time with `read*()`.\nWhen reading multiple resources, a glob pattern is used to match against existing resources.\nA globbed read returns a `Mapping`, where the keys are the expanded form of the glob, and values are `read` expressions on each individual resource.\n\nAssuming that a file system contains these files:\n\n[source,txt]\n----\n.\n├── birds/\n│ ├── pigeon.pkl\n│ ├── parrot.pkl\n│ └── falcon.pkl\n└── index.pkl\n----\n\nThe following two snippets are logically identical:\n\n.index.pkl\n[source%parsed,{pkl}]\n----\nbirdFiles = read*(\"birds/*.pkl\")\n----\n\n.index.pkl\n[source%parsed,{pkl}]\n----\nbirdFiles = new Mapping {\n [\"birds/pigeon.pkl\"] = read(\"birds/pigeon.pkl\")\n [\"birds/parrot.pkl\"] = read(\"birds/parrot.pkl\")\n [\"birds/falcon.pkl\"] = read(\"birds/falcon.pkl\")\n}\n----\n\nBy default, the following schemes support globbing:\n\n* `modulepath`\n* `file`\n* `env`\n* `prop`\n\nGlobbing other resources results in an error.\n\nFor details on how glob patterns work, reference <> in the Advanced Topics section.\n\nNOTE: When globbing files, symbolic links are not followed. Additionally, the `.` and `..` entries are skipped. +\nThis behavior is similar to the behavior of Bash with `shopt -s dotglob` enabled.\n\n[NOTE]\n====\nThe `env` and `prop` schemes are considered opaque, as they do not have traditional hierarchical elements like a host, path, or query string.\n\nWhile globbing is traditionally viewed as a way to match elements in a file system, a glob pattern is simply a way to match strings.\nThus, environment variables and external properties can be globbed, where their names get matched according to the rules described by the glob pattern.\n\nTo match all values within these schemes, use the `+++**+++` wildcard.\nThis has the effect of matching names that contain a forward slash too (`/`).\nFor example, the expression `read*(\"+++env:**+++\")` will evaluate to a Mapping of all environment variables.\n====\n\n=== Extending resource readers\n\nWhen Pkl is embedded within another runtime, it can be extended to read other kinds of resources.\n\nWhen embedded into a JVM application, new resources may be read by implementing the link:{uri-pkl-core-ResourceReader}[ResourceReader] SPI.\nWhen Pkl is embedded within Swift, new resources may be read by implementing the link:{uri-pkl-swift-resource-reader-docs}[ResourceReader] interface.\nWhen Pkl is embedded within Go, new resources may be read by implementing the link:{uri-pkl-go-resource-reader-docs}[ResourceReader] interface.\n\n=== Resource Allowlist\n\nWhen attempting to read a resource, the resource URI is checked against the resource allowlist (`--allowed-resources`).\nIn embedded mode, the allowlist is configured via an evaluator's link:{uri-pkl-core-SecurityManager}[SecurityManager].\n\nThe resource allowlist is a comma-separated list of regular expressions.\nFor access to be granted, at least one regular expression must match a prefix of the resource URI.\nFor example, the allowlist `file:,https:` grants access to any resource whose URI starts with `file:` or `https:`.\n\n[[errors]]\n== Errors\n\nBy design, errors are fatal in Pkl -- there is no way to recover from them.\nTo raise an error, use a `throw` expression:\n\n[source%tested%error,{pkl}]\n----\nmyValue = throw(\"You won't be able to recover from this one!\") // <1>\n----\n<1> `myValue` never receives a value because the program exits.\n\nThe error message is printed to the console and the program exits.\nIn embedded mode, a link:{uri-pkl-core-PklException}[PklException] is thrown.\n\n[[debugging]]\n== Debugging\n\nWhen debugging Pkl code, it can be useful to print the value of an expression.\nTo do so, use a `trace` expression:\n\n[source%tested,{pkl}]\n----\nnum1 = 42\nnum2 = 16\nres = trace(num1 * num2)\n----\n\nTracing an expression does not affect its result, but prints both its source code and result on standard error:\n\n[source,shell]\n----\npkl: TRACE: num1 * num2 = 672 (at file:///some/module.pkl, line 42)\n----\n\n[[advanced-topics]]\n== Advanced Topics\n\nThis section discusses language features that are generally more relevant to template and library authors than template consumers.\n\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<> +\n<>\n\n[[meaning-of-new]]\n=== Meaning of `new`\n\nObjects in Pkl always <> _some_ value.\nThe `new` keyword is a special case of amending where a contextual value is amended.\nIn Pkl, there are two forms of `new` objects:\n\n* `new` with explicit type information, for example, `new Foo {}`.\n* `new` without type information, for example, `new {}`.\n\n==== Type defaults\n\nTo understand instantiation cases without explicit parent or type information, it's important to first understand implicit default values.\nWhen a property is declared in a module or class but is not provided an explicit default value, the property's default value becomes the type's default value.\nSimilarly, when `Listing` and `Mapping` types are declared with explicit type arguments for their element or value, their `default` property amends that declared type.\nWhen `Listing` and `Mapping` types are declared without type arguments, their `default` property amends an empty `Dynamic` object.\nSome types, including `Pair` and primitives like `String`, `Number`, and `Boolean` have no default value; attempting to render such a property results in the error \"Tried to read property `` but its value is undefined\".\n\n[source,{pkl}]\n----\nclass Bird {\n name: String = \"polly\"\n}\n\nbird: Bird // <1>\nbirdListing: Listing // <2>\nbirdMapping: Mapping // <3> \n----\n<1> Without an explicit default value, this property has default value `new Bird { name = \"polly\" }`\n<2> With an explicit element type argument, this property's default value is equivalent to `new Listing { default = (_) -> new Bird { name = \"polly\" } }`\n<3> With an explicit value type argument, this property's default value is equivalent to `new Mapping { default = (_) -> new Bird { name = \"polly\" } }`\n\n==== Explicitly Typed `new`\n\nInstantiating an object with `new ` results in a value that amends the specified type's default value.\nNotably, creating a `Listing` element or assigning a `Mapping` entry value with an explicitly typed `new` ignores the object's `default` value.\n\n[source,{pkl}]\n----\nclass Bird {\n /// The name of the bird\n name: String\n\n /// Whether this is a bird of prey or not.\n isPredatory: Boolean?\n}\n\nnewProperty = new Bird { // <1>\n name = \"Warbler\"\n}\n\nsomeListing = new Listing {\n default {\n isPredatory = true\n }\n new Bird { // <2>\n name = \"Sand Piper\"\n }\n}\n\nsomeMapping = new Mapping {\n default {\n isPredatory = true\n }\n [\"Penguin\"] = new Bird { // <3>\n name = \"Penguin\"\n }\n}\n----\n<1> Assigning a `new` explicitly-typed value to a property.\n<2> Adding an `new` explicitly-typed `Listing` element.\nThe value will not have property `isPredatory = true` as the `default` property of the `Listing` is not used.\n<3> Assigning a `new` explicitly-typed value to a `Mapping` entry.\nThe value will not have property `isPredatory = true` as the `default` property of the `Mapping` is not used.\n\n==== Implicitly Typed `new`\n\nWhen using the implicitly typed `new` invocation, there is no explicit parent value to amend.\nIn these cases, Pkl infers the amend operation's parent value based on context:\n\n* When assigning to a declared property, the property's default value is amended (<>).\nIf there is no type associated with the property, an empty `Dynamic` object is amended.\n* When assigning to an entry (e.g. a `Mapping` member) or element (e.g. a `Listing` member), the enclosing object's `default` property is applied to the corresponding index or key, respectively, to produce the value to be amended.\n* In other cases, evaluation fails with the error message \"Cannot tell which parent to amend\".\n\nThe type annotation of a <> parameter is not used for inference.\nIn this case, the argument's type should be specified explicitly.\n\n[source,{pkl}]\n----\nclass Bird {\n name: String\n\n function listHatchlings(items: Listing): Listing = new {\n for (item in items) {\n \"\\(name):\\(item)\"\n }\n }\n}\n\ntypedProperty: Bird = new { // <1>\n name = \"Swift\"\n}\n\nuntypedProperty = new { // <2>\n hello = \"world\"\n}\n\ntypedListing: Listing = new {\n new { // <3>\n name = \"Kite\"\n }\n}\n\nuntypedListing: Listing = new {\n new { // <4>\n hello = \"there\"\n }\n}\n\ntypedMapping: Mapping = new {\n default { entryKey ->\n name = entryKey\n }\n [\"Saltmarsh Sparrow\"] = new { // <5>\n name = \"Sharp-tailed Sparrow\"\n }\n}\n\namendedMapping = (typedMapping) {\n [\"Saltmarsh Sparrow\"] = new {} // <6>\n}\n\nclass Aviary {\n birds: Listing = new {\n new { name = \"Osprey\" }\n }\n}\n\naviary: Aviary = new {\n birds = new { // <7>\n new { name = \"Kiwi\" }\n }\n}\n\nswiftHatchlings = typedProperty.listHatchlings(new { \"Poppy\"; \"Chirpy\" }) // <8>\n----\n<1> Assignment to a property with an explicitly declared type, amending `new Bird {}`.\n<2> Assignment to an undeclared property in module context, amending `new Dynamic {}`.\n<3> `Listing` element creation, amending implicit `default`, `new Bird {}`.\n<4> `Listing` element creation, amending implicit `default`, `new Dynamic {}`.\n<5> `Mapping` value assignment, amending the result of applying `default` to `\"Saltmarsh Sparrow\"`, `new Bird { name = \"Saltmarsh Sparrow\" }`.\n<6> `Mapping` value assignment _replacing_ the parent's entry, amending the result of applying `default` to `\"Saltmarsh Sparrow\"`, `new Bird { name = \"Saltmarsh Sparrow\" }`.\n<7> Amending the property default value `new Listing { new Bird { name = \"Osprey\" } }`; the result contains both birds.\n<8> Error: Cannot tell which parent to amend.\n\n[[let-expressions]]\n=== Let Expressions\n\nA `let` expression is Pkl's version of an (immutable) local variable.\nIts syntax is:\n\n[source]\n----\nlet ( = ) \n----\n\nA `let` expression is evaluated as follows:\n\n. `` is bound to ``, itself an expression.\n. `` is evaluated, which can refer to `` by its `` (this is the point).\n. The result of becomes the result of the overall expression.\n\nHere is an example:\n\n[source%tested,{pkl}]\n----\nbirdDiets =\n let (diets = List(\"Seeds\", \"Berries\", \"Mice\"))\n List(diets[2], diets[0]) // <1>\n----\n<1> result: `birdDiets = List(\"Mice\", \"Seeds\")`\n\n`let` expressions serve two purposes:\n\n- They introduce a human-friendly name for a potentially complex expression.\n- They evaluate a potentially expensive expression that is used in multiple places only once.\n\n`let` expressions can have type annotations:\n\n[source%tested,{pkl}]\n----\nbirdDiets = \n let (diets: List = List(\"Seeds\", \"Berries\", \"Mice\"))\n diets[2] + diets[0] // <1>\n----\n<1> result: `birdDiets = List(\"Mice\", \"Seeds\")`\n\n`let` expressions can be stacked:\n\n[source%tested,{pkl}]\n----\nbirdDiets = \n let (birds = List(\"Pigeon\", \"Barn owl\", \"Parrot\"))\n let (diet = List(\"Seeds\", \"Mice\", \"Berries\"))\n birds.zip(diet) // <1>\n----\n<1> result: `birdDiets = List(Pair(\"Pigeon\", \"Seeds\"), Pair(\"Barn owl\", \"Mice\"), Pair(\"Parrot\", \"Berries\"))`\n\n[[type-tests]]\n=== Type Tests\n\nTo test if a value conforms to a type, use the _is_ operator.\n\nAll the following tests hold:\n\n[source%tested,{pkl}]\n----\ntest1 = 42 is Int\ntest2 = 42 is Number\ntest3 = 42 is Any\ntest4 = !(42 is String)\n\nopen class Base\nclass Derived extends Base\n\nbase = new Base {}\n\ntest5 = base is Base\ntest6 = base is Any\ntest7 = !(base is Derived)\n\nderived = new Derived {}\n\ntest8 = derived is Derived\ntest9 = derived is Base\ntest10 = derived is Any\n----\n\nA value can be tested against any type, not just a class:\n\n[source,{pkl}]\n----\ntest1 = email is String(contains(\"@\")) // <1>\ntest2 = map is Map // <2>\ntest3 = name is \"Pigeon\"|\"Barn owl\"|\"Parrot\" // <3>\n----\n<1> `email` is tested for being a string that contains a `@` sign\n<2> `map` is tested for being a map from `Int` to `Base` values\n<3> `name` is tested for being one of `\"Pigeon\"`, `\"Barn owl\"`, or `\"Parrot\"`\n\n[[type-casts]]\n=== Type Casts\n\nThe _as_ (type cast) operator performs a runtime type check on its operand.\nIf the type check succeeds, the operand is returned as-is; otherwise, an error is thrown.\n\n[source%tested,{pkl}]\n----\nbirds {\n new { name = \"Pigeon\" }\n new { name = \"Barn owl\" }\n}\nnames = birds.toList().map((it) -> it.name) as List\n----\n\nAlthough type casts are never mandatory in Pkl, they occasionally help humans and tools better understand an expression's type.\n\n[[lists]]\n=== Lists\n\nA value of type link:{uri-stdlib-List}[List] is an ordered, indexed collection of _elements_.\n\nA list's elements have zero-based indexes and are eagerly evaluated.\n\n[TIP]\n.When to use List vs. <>\n====\n* When a collection of elements needs to be specified literally, use a listing.\n* When a collection of elements needs to be transformed in a way that cannot be achieved by <> a listing, use a list.\n* If in doubt, use a listing.\n\nTemplates and schemas should almost always use listings instead of lists.\nNote that listings can be converted to lists when the need arises.\n====\n\nLists are constructed with the `List()` methodfootnote:soft-keyword[Strictly speaking, `List`, `Set`, and `Map` are currently soft keywords. The goal is to eventually turn them into regular standard library methods.]:\n\n[source%tested,{pkl}]\n----\nlist1 = List() // <1>\nlist2 = List(1, 2, 3) // <2>\nlist3 = List(1, \"x\", 5.min, List(1, 2, 3)) // <3>\n----\n<1> result: empty list\n<2> result: list of length 3\n<3> result: heterogeneous list whose last element is another list\n\nTo concatenate lists, use the `+` operator:\n\n[source%tested,{pkl-expr}]\n----\nList(1, 2) + List(3, 4) + List(5)\n----\n\nTo access a list element by index, use the `[]` (subscript) operator:\n\n[source%tested,{pkl}]\n----\nlist = List(1, 2, 3, 4)\nlistElement = list[2] // <1>\n----\n<1> result: `3`\n\nClass `List` offers a link:{uri-stdlib-List}[rich API].\nHere are just a few examples:\n\n[source%tested,{pkl}]\n----\nlist = List(1, 2, 3, 4)\nres1 = list.contains(3) // <1>\nres2 = list.first // <2>\nres3 = list.rest // <3>\nres4 = list.reverse() // <4>\nres5 = list.drop(1).take(2) // <5>\nres6 = list.map((n) -> n * 3) // <6>\n----\n<1> result: `true`\n<2> result: `1`\n<3> result: `List(2, 3, 4)`\n<4> result: `List(4, 3, 2, 1)`\n<5> result: `List(2, 3)`\n<6> result: `List(3, 6, 9, 12)`\n\n[[sets]]\n=== Sets\n\nA value of type link:{uri-stdlib-Set}[Set] is a collection of unique _elements_.\n\nSets are constructed with the `Set()` methodfootnote:soft-keyword[]:\n\n[source%tested,{pkl}]\n----\nres1 = Set() // <1>\nres2 = Set(1, 2, 3) // <2>\nres3 = Set(1, 2, 3, 1) // <3>\nres4 = Set(1, \"x\", 5.min, List(1, 2, 3)) // <4>\n----\n<1> result: empty set\n<2> result: set of length 3\n<3> result: same set of length 3\n<4> result: heterogeneous set that contains a list as its last element\n\nSets retain the order of elements when constructed, which impacts how they are iterated over.\nHowever, this order is not considered when determining equality of two sets.\n\n[source%tested,{pkl}]\n----\nres1 = Set(4, 3, 2)\nres2 = res1.first // <1>\nres3 = res1.toListing() // <2>\nres4 = Set(2, 3, 4) == res1 // <3>\n----\n<1> result: `4`\n<2> result: `new Listing { 4; 3; 2 }`\n<3> result: `true`\n\nTo compute the union of sets, use the `+` operator:\n\n[source%tested,{pkl-expr}]\n----\nSet(1, 2) + Set(2, 3) + Set(5, 3) // <1>\n----\n<1> result: `Set(1, 2, 3, 5)`\n\nClass `Set` offers a link:{uri-stdlib-Set}[rich API].\nHere are just a few examples:\n\n[source%tested,{pkl}]\n----\nset = Set(1, 2, 3, 4)\nres1 = set.contains(3) // <1>\nres2 = set.drop(1).take(2) // <2>\nres3 = set.map((n) -> n * 3) // <3>\nres4 = set.intersect(Set(3, 9, 2)) // <4>\n----\n<1> result: `true`\n<2> result: `Set(2, 3)`\n<3> result: `Set(3, 6, 9, 12)`\n<4> result: `Set(3, 2)`\n\n[[maps]]\n=== Maps\n\nA value of type link:{uri-stdlib-Map}[Map] is a collection of _values_ indexed by _key_.\n\nA map's key-value pairs are called its _entries_.\nKeys and values are eagerly evaluated.\n\n[TIP]\n.When to use Map vs. <>\n====\n* When key-value style data needs to be specified literally, use a mapping.\n* When key-value style data needs to be transformed in ways that cannot be achieved by <> a mapping, use a map.\n* If in doubt, use a mapping.\n\nTemplates and schemas should almost always use mappings instead of maps.\n(Note that mappings can be converted to maps when the need arises.)\n====\n\nMaps are constructed by passing alternating keys and values to the `Map()` methodfootnote:soft-keyword[]:\n\n[source%tested,{pkl}]\n----\nmap1 = Map() // <1>\nmap2 = Map(1, \"one\", 2, \"two\", 3, \"three\") // <2>\nmap3 = Map(1, \"x\", 2, 5.min, 3, Map(1, 2)) // <3>\n----\n<1> result: empty map\n<2> result: set of length 3\n<3> result: heterogeneous map whose last value is another map\n\nAny Pkl value can be used as a map key:\n\n[source%tested,{pkl-expr}]\n----\nMap(new Dynamic { name = \"Pigeon\" }, 10.gb)\n----\n\nMaps retain the order of entries when constructed, which impacts how they are iterated over.\nHowever, this order is not considered when determining equality of two maps.\n\n[source%tested,{pkl}]\n----\nres1 = Map(2, \"hello\", 1, \"world\")\nres2 = res1.entries.first // <1>\nres3 = res1.toMapping() // <2>\nres4 = res1 == Map(1, \"world\", 2, \"hello\") // <3>\n----\n<1> result: `Pair(2, \"hello\")`\n<2> result: `new Mapping { [2] = \"hello\"; [1] = \"world\" }`\n<3> result: `true`\n\nTo merge maps, use the `+` operator:\n\n[source%tested,{pkl}]\n----\ncombinedMaps = Map(1, \"one\") + Map(2, \"two\", 1, \"three\") + Map(4, \"four\") // <1>\n----\n<1> result: `Map(1, \"three\", 2, \"two\", 4, \"four\")`\n\nTo access a value by key, use the `[]` (subscript) operator:\n\n[source%tested,{pkl}]\n----\nmap = Map(\"Pigeon\", 5.gb, \"Parrot\", 10.gb)\nparrotValue = map[\"Parrot\"] // <1>\n----\n<1> result: `10.gb`\n\nClass `Map` offers a link:{uri-stdlib-Map}[rich API].\nHere are just a few examples:\n\n[source%tested,{pkl}]\n----\nmap = Map(\"Pigeon\", 5.gb, \"Parrot\", 10.gb)\nres1 = map.containsKey(\"Parrot\") // <1>\nres2 = map.containsValue(8.gb) // <2>\nres3 = map.isEmpty // <3>\nres4 = map.length // <4>\nres5 = map.getOrNull(\"Falcon\") // <5>\n----\n<1> result: `true`\n<2> result: `false`\n<3> result: `false`\n<4> result: `2`\n<5> result: `null`\n\n[[bytes]]\n=== Bytes\n\nA value of type `Bytes` is a sequence of `UInt8` elements.\n\n`Bytes` can be constructed by passing byte values into the constructor.\n\n[source,pkl]\n----\nbytes1 = Bytes(0xff, 0x00, 0x3f) // <1>\nbytes2 = Bytes() // <2>\n----\n<1> Result: a `Bytes` with 3 elements\n<2> Result: an empty `Bytes`\n\n`Bytes` can also be constructed from a base64-encoded string, via `base64DecodedBytes`:\n\n[source,pkl]\n----\nbytes3 = \"cGFycm90\".base64DecodedBytes // <1>\n----\n<1> Result: `Bytes(112, 97, 114, 114, 111, 116)`\n\n==== `Bytes` vs `List`\n\n`Bytes` is similar to `List` in that they are both sequences of `UInt8` elements.\nHowever, they are semantically distinct.\n`Bytes` represent binary data, and is typically rendered differently.\nFor example, they are rendered as `` tags when using `PListRenderer`.\n\n`Bytes` also have different performance characteristics; a value of type `Bytes` tends to be managed as a contiguous memory block.\nThus, they are more compact and consume less memory.\nHowever, they are not optimized for transformations.\nFor example, given two values of size `M` and `N`, concatenating two `Bytes` values allocates O(M + N) space, whereas concatenating two `List` values allocates O(1) space.\n\n[[regular-expressions]]\n=== Regular Expressions\n\nA value of type link:{uri-stdlib-Regex}[Regex] is a regular expression with the same syntax and semantics as a link:{uri-javadoc-Pattern}[Java regular expression].\n\nRegular expressions are constructed with the link:{uri-stdlib-Regex-method}[Regex()] method:\n\n[source%tested,{pkl}]\n----\nemailRegex = Regex(#\"([\\w\\.]+)@([\\w\\.]+)\"#)\n----\n\n// note: first \\ on next line is asciidoc escape\nNotice the use of custom string delimiters `\\#\"` and `\"#`, which change the string's escape character from `\\` to `\\#`.\nAs a consequence, the regular expression's backslash escape character no longer requires escaping.\n\nTo test if a string fully matches a regular expression, use link:{uri-stdlib-matches}[String.matches()]:\n\n[source%tested,{pkl-expr}]\n----\n\"pigeon@example.com\".matches(emailRegex)\n----\n\nMany `String` methods accept either a `String` or `Regex` argument.\nHere is an example:\n\n[source%tested,{pkl}]\n----\nres1 = \"Pigeon\".contains(\"pigeon@example.com\")\nres2 = \"Pigeon\".contains(emailRegex)\n----\n\nTo find all matches of a regex in a string, use link:{uri-stdlib-Regex-match}[Regex.findMatchesIn()].\nThe result is a list of link:{uri-stdlib-RegexMatch}[RegexMatch] objects containing details about each match:\n\n[source%tested,{pkl}]\n----\nmatches = emailRegex.findMatchesIn(\"pigeon@example.com / falcon@example.com / parrot@example.com\")\nlist1 = matches.drop(1).map((it) -> it.start) // <1>\nlist2 = matches.drop(1).map((it) -> it.value) // <2>\nlist3 = matches.drop(1).map((it) -> it.groups[1].value) // <3>\n----\n<1> result: `List(0, 19, 40)` (the entire match, `matches[0]`, was dropped)\n<2> result: `List(\"pigeon@example.com\", \"falcon@example.com\", \"parrot@example.com\")`\n<3> result: `List(\"pigeon, falcon, parrot\")`\n\n[[type-aliases]]\n=== Type Aliases\n\nA _type alias_ introduces a new name for a (potentially complicated) type:\n\n[source%tested,{pkl}]\n----\ntypealias EmailAddress = String(matches(Regex(#\".+@.+\"#)))\n----\n\nOnce a type alias has been defined, it can be used in type annotations:\n\n[source%tested,{pkl}]\n----\nemail: EmailAddress = \"pigeon@example.com\"\n\nemailList: List = List(\"pigeon@example.com\", \"parrot@example.com\")\n----\n\nNew type aliases can be defined in terms of existing ones:\n\n[source%tested,{pkl}]\n----\ntypealias EmailList = List\n\nemailList: EmailList = List(\"pigeon@example.com\", \"parrot@example.com\")\n----\n\nType aliases can have type parameters:\n\n[source%tested,{pkl}]\n----\ntypealias StringMap = Map\n\nmap: StringMap = Map(\"Pigeon\", 42, \"Falcon\", 21)\n----\n\nCode generators have different strategies for dealing with type aliases:\n\n* the xref:java-binding:codegen.adoc[Java] code generator inlines them\n* the xref:kotlin-binding:codegen.adoc[Kotlin] code generator turns them into Kotlin type aliases.\n\nType aliases for unions of <> are turned into enum classes by both code generators.\n\n[[predefined-type-aliases]]\n==== Predefined Type Aliases\n\nThe _pkl.base_ module defines the following type aliases:\n\n* link:{uri-stdlib-Int8}[Int8] (-128 to 127)\n* link:{uri-stdlib-Int16}[Int16] (-32,768 to 32,767)\n* link:{uri-stdlib-Int32}[Int32] (-2,147,483,648 to 2,147,483,647)\n\n//-\n* link:{uri-stdlib-UInt8}[UInt8] (0 to 255)\n* link:{uri-stdlib-UInt16}[UInt16] (0 to 65,535)\n* link:{uri-stdlib-UInt32}[UInt32] (0 to 4,294,967,295)\n* link:{uri-stdlib-UInt}[UInt] (0 to 9,223,372,036,854,775,807)\n\n//-\n* link:{uri-stdlib-Uri}[Uri] (any String value)\n\nWARNING: Note that `UInt` has the same maximum value as `Int`, half of what would normally be expected.\n\nThe main purpose of the provided integer aliases is to enforce the range of an integer:\n\n[source%tested%error,{pkl}]\n----\nport: UInt16 = -1\n----\n\nThis gives:\n\n[source,shell,subs=\"quotes\"]\n----\nType constraint *isBetween(0, 65535)* violated.\nValue: -1\n----\n\nTo restrict a number to a custom range, use the link:{uri-stdlib-isBetween}[isBetween] method:\n\n[source%tested,{pkl}]\n----\nport: Int(isBetween(0, 1023)) = 443\n----\n\nNOTE: Remember that numbers are always instances of `Int` or `Float`.\nType aliases such as `UInt16` only check that numbers are within a certain range.\n\nThe xref:java-binding:codegen.adoc[Java] and xref:kotlin-binding:codegen.adoc[Kotlin] code generators\nmap predefined type aliases to the most suitable Java and Kotlin types.\nFor example, `UInt8` is mapped to `java.lang.Byte` and `kotlin.Byte`, and `Uri` is mapped to `java.net.URI`.\n\n[[type-annotations]]\n=== Type Annotations\n\nProperty and method definitions may optionally contain type annotations.\nType annotations serve the following purposes:\n\n* Documentation\n+ Type annotations help to document data models. They are included in any generated documentation.\n\n* Validation\n+ Type annotations are validated at runtime.\n\n* Defaults\n+ Type-annotated properties have <>.\n\n* Code Generation\n+ Type annotations enable statically typed access to configuration data through code generation.\n\n* Tooling\n+ Type annotations enable advanced tooling features such as code completion in editors.\n\n==== Class Types\n\nAny class can be used as a type:\n\n[source%parsed,{pkl}]\n----\nclass Bird {\n name: String // <1>\n}\nbird: Bird // <2>\n----\n<1> Declares an instance property of type `String`.\n<2> Declares a module property of type `Bird`.\n\n==== Module Types\n\nAny module import can be used as type:\n\n[source%parsed,{pkl}]\n.bird.pkl\n----\nname: String\nlifespan: Int\n----\n\n[source%parsed,{pkl}]\n.birds.pkl\n----\nimport \"bird.pkl\"\n\npigeon: bird // <1>\nparrot: bird // <1>\n----\n<1> Guaranteed to amend _bird.pkl_.\n\nAs a special case, the `module` keyword denotes the _enclosing_ module's type:\n\n[source%parsed,{pkl}]\n.bird.pkl\n----\nname: String\nlifespan: Int\nfriends: Listing\n----\n\n[source%parsed,{pkl}]\n.pigeon.pkl\n----\namends \"bird.pkl\"\n\nname = \"Pigeon\"\nlifespan = 8\nfriends {\n import(\"falcon.pkl\") // <1>\n}\n----\n<1> _falcon.pkl_ (not shown here) is guaranteed to amend _bird.pkl_.\n\n==== Type Aliases\n\nAny <> can be used as a type:\n\n[source%parsed,{pkl}]\n----\ntypealias EmailAddress = String(contains(\"@\"))\n\nemail: EmailAddress // <1>\n\nemailList: List // <2>\n----\n<1> equivalent to `email: String(contains(\"@\"))` for type checking purposes\n<2> equivalent to `emailList: List` for type checking purposes\n\n[[nullable-types]]\n==== Nullable Types\n\nClass types such as `Bird` (see above) do not admit `null` values.\nTo turn them into _nullable types_, append a question mark (`?`):\n\n[source%parsed,{pkl}]\n----\nbird: Bird = null // <1>\nbird2: Bird? = null // <2>\n----\n<1> throws `Type mismatch: Expected a value of type Bird, but got null`\n<2> succeeds\n\nThe only class types that admit `null` values despite not ending in `?` are `Any` and `Null`.\n(`Null` is not very useful as a type because it _only_ admits `null` values.)\n`Any?` and `Null?` are equivalent to `Any` and `Null`, respectively.\nIn some languages, nullable types are also known as _optional types_.\n\n[[generic-types]]\n==== Generic Types\n\nThe following class types are _generic types_:\n\n* `Pair`\n* `Collection`\n* `Listing`\n* `List`\n* `Mapping`\n* `Set`\n* `Map`\n* `Function0`\n* `Function1`\n* `Function2`\n* `Function3`\n* `Function4`\n* `Function5`\n* `Class`\n\nA generic type has constituent types written in angle brackets (`<>`):\n\n[source%parsed,{pkl}]\n----\npair: Pair // <1>\ncoll: Collection // <2>\nlist: List // <3>\nset: Set // <4>\nmap: Map // <5>\nmapping: Mapping // <6>\n----\n\n<1> a pair `String` and `Bird` as types for the first and second element, respectively\n<2> a collection of `Bird` elements\n<3> a list of `Bird` elements\n<4> a set of `Bird` elements\n<5> a map with `String` keys and `Bird` values\n<6> a mapping of `String` keys and `Bird` values\n\nOmitting the constituent types is equivalent to declaring them as `unknown`:\n\n[source%parsed,{pkl}]\n----\npair: Pair // equivalent to `Pair`\ncoll: Collection // equivalent to `Collection`\nlist: List // equivalent to `List`\nset: Set // equivalent to `Set`\nmap: Map // equivalent to `Map`\nmapping: Mapping // equivalent to `Mapping`\n----\n\nThe `unknown` type is both a top and a bottom type.\nWhen a static type analyzer encounters an expression of `unknown` type,\nit backs off and trusts the user that they know what they are doing.\n\n[[union-types]]\n==== Union Types\n\nA value of type `A | B`, read \"A or B\", is either a value of type `A` or a value of type `B`.\n\n[source%tested,{pkl}]\n----\nclass Bird { name: String }\n\nbird1: String|Bird = \"Pigeon\"\nbird2: String|Bird = new Bird { name = \"Pigeon\" }\n----\n\nMore complex union types can be formed:\n\n[source%parsed,{pkl}]\n----\nfoo: List|Bird\n----\n\nUnion types have no implicit default values, but an explicit type can be chosen using a `*` marker:\n[source%parsed,{pkl}]\n----\nfoo: \"a\"|\"b\" // undefined. Will throw an error if not amended\nbar: \"a\"|*\"b\" // default value will be taken from type \"b\"\nbaz: \"a\"|\"b\" = \"a\" // explicit value is given\nqux: String|*Int // default taken from Int, but Int has no default. Will throw if not amended\n----\n\nUnion types often come in handy when writing schemas for legacy JSON or YAML files.\n\n[[string-literal-types]]\n==== String Literal Types\n\nA string literal type admits a single string value:\n\n[source%parsed,{pkl}]\n----\ndiet: \"Seeds\"\n----\n\nWhile occasionally useful on their own,\nstring literal types are often combined with <> to form enumerated types:\n\n[source%parsed,{pkl}]\n----\ndiet: \"Seeds\"|\"Berries\"|\"Insects\"\n----\n\nTo reuse an enumerated type, introduce a type alias:\n\n[source%parsed,{pkl}]\n----\ntypealias Diet = \"Seeds\"|\"Berries\"|\"Insects\"\ndiet: Diet\n----\n\nThe Java and Kotlin code generators turn type aliases for enumerated types into enum classes.\n\n[[nothing-type]]\n==== Nothing Type\n\nThe `nothing` type is the bottom type of Pkl's type system, the counterpart of top type `Any`.\n\nThe bottom type is assignment-compatible with every other type, and no other type is assignment-compatible with it.\n\nBeing assignment-compatible with every other type may sound too good to be true, but there is a catch -- the `nothing` type has no values!\n\nDespite being a lonely type, `nothing` has practical applications.\nFor example, it is used in the standard library's `TODO()` method:\n\n[source%tested,{pkl}]\n----\nfunction TODO(): nothing = throw(\"TODO\")\n----\n\nA `nothing` return type indicates that a method never returns normally but always throws an error.\n\n[[unknown-type]]\n==== Unknown Type\n\nThe `unknown` type footnote:[Also known as _dynamic type_. We do not use that term to avoid confusion with `Dynamic`, Pkl's dynamic object type.] is ``nothing``'s even stranger cousin: it is both a top and bottom type!\nThis makes `unknown` assignment-compatible with every other type, and every other type assignment-compatible with `unknown`.\n\nWhen a static type analyzer encounters a value of `unknown` type,\nit backs off and trusts the code's author to know what they are doing -- for example, whether a method called on the value exists.\n\n==== Progressive Disclosure\n\nIn the spirit of link:{uri-progressive-disclosure}[progressive disclosure], type annotations are optional in Pkl.\nOmitting a type annotation is equivalent to specifying the type `unknown`:\n\n[source%parsed,{pkl}]\n----\nlifespan = 42 // <1>\nmap: Map // <2>\nfunction say(name) = name // <3>\n----\n<1> shorthand for `lifespan: unknown = 42`\n (As a dynamically typed language, Pkl does not try to statically infer types.)\n<2> shorthand for `map: Map = Map()`\n<3> shorthand for `function say(name: unknown): unknown = name`\n\n[[default-values]]\n==== Default Values\n\nType-annotated properties have implicit \"empty\" default values depending on their type:\n\n[source%tested,{pkl}]\n----\nclass Bird\n\ncoll: Collection // = List() <1>\nlist: List // = List() <2>\nset: Set // = Set() <3>\nmap: Map // = Map() <4>\nlisting: Listing // = new Listing { default = (index) -> new Bird {} } <5>\nmapping: Mapping // = new Mapping { default = (key) -> new Bird {} } <6>\nobj: Bird // = new Bird {} <7>\nnullable: Bird? // = Null(new Bird {}) <8>\nunion: *Bird|String // = new Bird {} <9>\nstringLiteral: \"Pigeon\" // = \"Pigeon\" <10>\nnullish: Null // = null <11>\n----\n\n<1> Properties of type `Collection` default to the empty list.\n<2> Properties of type `List` default to the empty list.\n<3> Properties of type `Set` default to the empty set.\n<4> Properties of type `Map` default to the empty map.\n<5> Properties of type `Listing` default to an empty listing whose default element is the default for `X`.\n<6> Properties of type `Mapping` default to an empty mapping whose default value is the default for `Y`.\n<7> Properties of non-external class type `X` default to `new X {}`.\n<8> Properties of type `X?` default to `Null(x)` where `x` is the default for `X`.\n<9> Properties with a union type have no default value. By prefixing one of the types in a union with a `*`, the default of that type is chosen as the default for the union.\n<10> Properties with a string literal type default to the type's only value.\n<11> Properties of type `Null` default to `null`.\n\nSee <> for further information.\n\nProperties of the following types do not have implicit default values:\n\n* `abstract` classes, including `Any` and `NotNull`\n* Union types, unless an explicit default is given by prefixing one of the types with `*`.\n* `external` (built-in) classes, including:\n** `String`\n** `Boolean`\n** `Int`\n** `Float`\n** `Duration`\n** `DataSize`\n** `Pair`\n** `Regex`\n\nAccessing a property that neither has an (implicit or explicit) default value nor has been overridden throws an error:\n\n[source%tested%error,{pkl}]\n----\nname: String\n----\n\n[[type-constraints]]\n==== Type Constraints\n\nA type may be followed by a comma-separated list of _type constraints_ enclosed in round brackets (`()`).\nA type constraint is a boolean expression that must hold for the annotated element.\nType constraints enable advanced runtime validation that goes beyond the capabilities of static type checking.\n\n[source%tested,{pkl}]\n----\nclass Bird {\n name: String(length >= 3) // <1>\n parent: String(this != name) // <2>\n}\n\npigeon: Bird = new {\n name = \"Pigeon\"\n parent = \"Pigeon Sr.\" // <3>\n}\n----\n<1> Restricts `name` to have at least three characters.\n<2> The name of the bird (`this`) should not be the same as the name of the `parent`.\n<3> Note how `parent` is different from `name`. If they were the same, we would be thrown a constraint error.\n\nIn the following example, we define a `Bird` with a name of only two characters.\n\n[source%tested%error,{pkl}]\n----\npigeon: Bird = new {\n // fails the constraint because [name] is less than 3 characters\n name = \"Pi\"\n}\n----\n\nBoolean expressions are convenient for ad-hoc type constraints.\nAlternatively, type constraints can be given as lambda expressions accepting a single argument, namely the value to be validated.\nThis allows for the abstraction and reuse of type constraints.\n\n[source%tested,{pkl}]\n----\nclass Project {\n local emailAddress = (str) -> str.matches(Regex(#\".+@.+\"#))\n email: String(emailAddress)\n}\n\nproject: Project = new {\n email = \"projectPigeon@example.com\"\n}\n----\n\n[source%tested%error,{pkl}]\n----\nproject: Project = new {\n // fails the constraint because `\"projectPigeon-example.com\"` doesn't match the regular expression.\n email = \"projectPigeon-example.com\"\n}\n----\n\n===== Composite Type Constraints\n\nA composite type can have type constraints for the overall type, its constituent types, or both.\n\n[source%tested,{pkl}]\n----\nclass Project {\n local emailAddress = (str) -> str.matches(Regex(#\".+@.+\"#))\n // constrain the nullable type's element type\n type: String(contains(\"source\"))?\n // constrain the map type and its key/value types\n contacts: Map(length <= 5)\n}\n\nproject: Project = new {\n type = \"open-source\"\n contacts = Map(\"Pigeon\", \"pigeon@example.com\")\n}\n----\n\n[[anonymous-functions]]\n=== Anonymous Functions\n\nAn _anonymous function_ is a function without a name.\n\nMost modern general-purpose programming languages support anonymous functions,\nunder names such as _lamba expressions_, _arrow functions_, _function literals_, _closures_, or _procs_.\n\nAnonymous functions have their own literal syntax:\n\n[source]\n----\n() -> expr // <1>\n(param) -> expr // <2>\n(param1, param2, ..., paramN) -> expr // <3>\n----\n<1> Zero-parameter lambda expression\n<2> Single-parameter lambda expression\n<3> Multi-parameter lambda expression\n\nHere is an example:\n\n[source%tested,{pkl-expr}]\n----\n(n) -> n * 3\n----\n\nThis anonymous function accepts a parameter named `n`, multiplies it by 3, and returns the result.\n\nAnonymous functions are values of type link:{uri-stdlib-Function}[Function], more specifically\nlink:{uri-stdlib-Function0}[Function0], link:{uri-stdlib-Function1}[Function1],\nlink:{uri-stdlib-Function2}[Function2], link:{uri-stdlib-Function3}[Function3],\nlink:{uri-stdlib-Function4}[Function4], or link:{uri-stdlib-Function5}[Function5].\nThey cannot have more than five parameters.\n\nTo invoke an anonymous function, call its link:{uri-stdlib-Function1-apply}[apply] method:\n\n[source%tested,{pkl-expr}]\n----\n((n) -> n * 3).apply(4) // 12\n----\n\nMany standard library methods accept anonymous functions:\n\n[source%tested,{pkl-expr}]\n----\nList(1, 2, 3).map((n) -> n * 3) // List(3, 6, 9)\n----\n\nAnonymous functions can be assigned to properties, thereby giving them a name:\n\n[source%tested,{pkl}]\n----\nadd = (a, b) -> a + b\nadded = add.apply(2, 3)\n----\n\n[TIP]\n====\nIf an anonymous function is not intended to be passed as value, it is customary to declare a method instead:\n\n[source%tested,{pkl}]\n----\nfunction add(a, b) = a + b\nadded = add(2, 3)\n----\n====\n\nAn anonymous function's parameters can have type annotations:\n\n[source%tested,{pkl-expr}]\n----\n(a: Number, b: Number) -> a + b\n----\n\nApplying this function to arguments not of type `Number` results in an error.\n\nAnonymous functions are _closures_: They can access members defined in a lexically enclosing scope, even after leaving that scope:\n\n[source%tested,{pkl}]\n----\na = 42\naddToA = (b: Number) -> a + b\nlist = List(1, 2, 3).map(addToA) // List(43, 44, 45)\n----\n\nSingle-parameter anonymous functions can also be applied with the `|>` (pipe) operator,\nwhich expects a function argument to the left and an anonymous function to the right.\nThe pipe operator works especially well for chaining multiple functions:\n\n[source%tested,{pkl}]\n----\nmul3 = (n) -> n * 3\nadd2 = (n) -> n + 2\n\nnum = 4 \n |> mul3\n |> add2\n |> mul3 // <1>\n----\n<1> result: `42`\n\nLike methods, anonymous functions can be recursive:\n\n[source%tested,{pkl}]\n----\nfactor = (n: Number(isPositive)) -> if (n < 2) n else n * factor.apply(n - 1)\nnum = factor.apply(5) // <1>\n----\n<1> result: `120`\n\n[[mixins]]\n==== Mixins\n\nA mixin is an anonymous function used to apply the same modification to different objects.\n\nEven though mixins are regular functions, they are best created with object syntax:\n\n[source%tested,{pkl}]\n----\nwithDiet = new Mixin {\n diet = \"Seeds\"\n}\n----\n\nMixins can optionally specify which type of object they apply to:\n\n[source%tested,{pkl}]\n----\nclass Bird { diet: String }\n\nwithDietTyped = new Mixin {\n diet = \"Seeds\"\n}\n----\n\nFor properties with type annotation, the shorthand `new { ... }` syntax can be used:\n\n[source%tested,{pkl}]\n----\nwithDietTyped: Mixin = new {\n diet = \"Seeds\"\n}\n----\n\nTo apply a mixin, use the `|>` (pipe) operator:\n\n[source%tested,{pkl}]\n----\npigeon {\n name = \"Pigeon\"\n}\npigeonWithDiet = pigeon |> withDiet\n\nbarnOwl {\n name = \"Barn owl\"\n}\nbarnOwlWithDiet = barnOwl |> withDiet\n----\n\n`withDiet` can be generalized by turning it into a factory method for mixins:\n[source%tested,{pkl}]\n----\nfunction withDiet(_diet: String) = new Mixin {\n diet = _diet\n}\nseedPigeon = pigeon |> withDiet(\"Seeds\")\nMiceBarnOwl = barnOwl |> withDiet(\"Mice\")\n----\n\nMixins can themselves be modified with <>.\n\n[[function-amending]]\n==== Function Amending\n\nAn anonymous function that returns an object can be amended with the same syntax as that object.\nThe result is a new function that accepts the same number of parameters as the original function,\napplies the original function to them, and amends the returned object.\n\nFunction amending is a special form of function composition.\nThanks to function amending, link:{uri-stdlib-Listing-default}[Listing.default]\nand link:{uri-stdlib-Mapping-default}[Mapping.default] can be treated as if they were objects,\nonly gradually revealing their true (single-parameter function) nature:\n\n[source%tested,{pkl}]\n----\nbirds = new Mapping {\n default { // <1>\n diet = \"Seeds\"\n }\n [\"Pigeon\"] { // <2>\n lifespan = 8\n }\n}\n----\n<1> Amends the `default` function, which returns a default mapping value given a mapping key, and sets property `diet`.\n<2> Implicitly applies the amended `default` function and amends the returned object with property `lifespan`.\n\nThe result is a mapping whose entry `\"Pigeon\"` has both `diet` and `lifespan` set.\n\nWhen amending an anonymous function, it is possible to access its parameters\nby declaring a comma-separated, arrow (`->`) terminated parameter list after the opening curly brace (`{`).\n\nOnce again, this is especially useful to configure a listing's or mapping's `default` function:\n\n[source%tested,{pkl}]\n----\nbirds = new Mapping {\n default { key -> // <1>\n name = key\n }\n [\"Pigeon\"] {} // <2>\n [\"Barn owl\"] {} // <3>\n}\n----\n<1> Amends the `default` function and sets the `name` property to the mapping entry's key.\n To access the `default` function's key parameter, it is declared with `key ->`.\n (Any other parameter name could be chosen, but `key` is customary for default functions.)\n<2> Defines a mapping entry with key `\"Pigeon\"`\n<3> Defines a mapping entry with key `\"Barn owl\"`\n\nThe result is a mapping with two entries `\"Pigeon\"` and `\"Barn owl\"` whose `name` properties are set to their keys.\n\nFunction amending can also be used to refine <>.\n\n[[amend-null]]\n=== Amending Null Values\n\nIt's time to lift a secret: The predefined `null` value is just one of the potentially many values of type `Null`.\n\nFirst, here are the technical facts:\n\n* Null values are constructed with `pkl.base#Null()`.\n* `Null(x)` constructs a null value that is equivalent to `x` when amended.\nIn other words, `Null(x) { ... }` is equivalent to `x { ... }`.\n* All null values are equal according to `==`.\n\nWe say that `Null(x)` is a \"null value with default x\".\nBut what is it useful for?\n\n====\nNull values with default are used to define properties that are null (\"switched off\") by default but have a default value once amended (\"switched on\").\n====\n\nHere is an example:\n\n.template.pkl\n[source%tested,{pkl}]\n----\n// we don't have a pet yet, but already know that it is going to be a bird\npet = Null(new Dynamic {\n animal = \"bird\"\n})\n----\n\n[source%parsed,{pkl}]\n----\namends \"template.pkl\"\n\n// We got a pet, let's fill in its name\npet {\n name = \"Parry the Parrot\"\n}\n----\n\nA null value can be switched on without adding or overriding a property:\n\n[source%parsed,{pkl}]\n----\namends \"template.pkl\"\n\n// We do not need to name anything if we have no pet yet\npet {}\n----\n\nThe predefined `null` value is defined as `Null(new Dynamic {})`.\nIn other words, amending `null` is equivalent to amending `Dynamic {}` (the empty dynamic object):\n\n[source%tested,{pkl}]\n----\npet = null\n----\n\n[source%tested,{pkl}]\n----\npet {\n name = \"Parry the Parrot\"\n}\n----\n\nIn most cases, the `Null()` method is not used directly.\nInstead, it is used under the hood to create implicit defaults for properties with nullable type:\n\n.template.pkl\n[source%tested,{pkl}]\n----\nclass Pet {\n name: String\n animal: String = \"bird\"\n}\n\n// defaults to `Null(Pet {})`\npet: Pet?\n----\n\n[source%tested,{pkl}]\n----\namends \"template.pkl\"\n\npet {\n name = \"Perry the Parrot\"\n}\n----\n\nThe general rule is: A property with nullable type `X?` defaults to `Null(x)` if type `X` has default value `x`, and to `null` if `X` has no default value.\n\n[[when-generators]]\n=== When Generators\n\n`when` generators conditionally generate object members.\nThey come in two variants:\n\n. `when () { }`\n. `when () { } else { }`\n\nThe following code conditionally generates properties `hobby` and `idol`:\n[source%tested,{pkl}]\n----\nisSinger = true\n\nparrot {\n lifespan = 20\n when (isSinger) {\n hobby = \"singing\"\n idol = \"Frank Sinatra\"\n }\n}\n----\n\n`when` generators can have an `else` part:\n\n[source%tested,{pkl}]\n----\nisSinger = false\n\nparrot {\n lifespan = 20\n when (isSinger) {\n hobby = \"singing\"\n idol = \"Aretha Franklin\"\n } else {\n hobby = \"whistling\"\n idol = \"Wolfgang Amadeus Mozart\"\n }\n}\n----\n\nBesides properties, `when` generators can generate elements and entries:\n\n[source%tested,{pkl}]\n----\nabilities {\n \"chirping\"\n when (isSinger) {\n \"singing\" // <1>\n }\n \"whistling\"\n}\n\nabilitiesByBird {\n [\"Barn owl\"] = \"hooing\"\n when (isSinger) {\n [\"Parrot\"] = \"singing\" // <2>\n }\n [\"Parrot\"] = \"whistling\"\n}\n----\n<1> conditional element\n<2> conditional entry\n\n[[for-generators]]\n=== For Generators\n\n`for` generators generate object members in a loop.\nThey come in two variants:\n\n. `for ( in ) { }`\n. `for (, in ) { }`\n\nThe following code generates a `birds` object containing three elements.\nEach element is an object with properties `name` and `lifespan`.\n\n[source%tested,{pkl}]\n----\nnames = List(\"Pigeon\", \"Barn owl\", \"Parrot\")\n\nbirds {\n for (_name in names) {\n new {\n name = _name\n lifespan = 42\n }\n }\n}\n----\n\nThe following code generates a `birdsByName` object containing three entries.\nEach entry is an object with properties `name` and `lifespan` keyed by name.\n\n[source%tested,{pkl}]\n----\nnamesAndLifespans = Map(\"Pigeon\", 8, \"Barn owl\", 15, \"Parrot\", 20)\n\nbirdsByName {\n for (_name, _lifespan in namesAndLifespans) {\n [_name] {\n name = _name\n lifespan = _lifespan\n }\n }\n}\n----\n\nThe following types are iterable:\n\n|===\n|Type |Key |Value\n\n|`IntSeq`\n|element index (`Int`)\n|element value (`Int`)\n\n|`List`\n|element index (`Int`)\n|element value (`Element`)\n\n|`Set`\n|element index (`Int`)\n|element value (`Element`)\n\n|`Map`\n|entry key (`Key`)\n|entry value (`Value`)\n\n|`Bytes`\n|element index (`Int`)\n|element value (`UInt8`)\n\n|`Listing`\n|element index (`Int`)\n|element value (`Element`)\n\n|`Mapping`\n|entry key (`Key`)\n|entry value (`Value`)\n\n|`Dynamic`\n|element index (`Int`) +\nentry key +\nproperty name (`String`)\n|element value +\nentry value +\nproperty value\n|===\n\nIndices are zero-based.\nNote that `for` generators can generate elements and entries but not properties.footnote:[More precisely, they cannot generate properties with a non-constant name.]\n\n[[spread-syntax]]\n=== Spread Syntax (`\\...`)\n\nSpread syntax generates object members from an iterable value.\n\nThere are two variants of spread syntax, a non-nullable variant and a nullable variant.\n\n1. `\\...`\n2. `\\...?`\n\nSpreading an xref:objects[`Object`] (one of `Dynamic`, `Listing` and `Mapping`) will unpack all of its members into the enclosing object footnote:[Values that are xref:typed-objects[`Typed`] are not iterable.].\nEntries become entries, elements become elements, and properties become properties.\n\n[source%tested,{pkl}]\n----\nentries1 {\n [\"Pigeon\"] = \"Piggy the Pigeon\"\n [\"Barn owl\"] = \"Barney the Barn owl\"\n}\n\nentries2 {\n ...entries1 // <1>\n}\n\nelements1 { 1; 2 }\n\nelements2 {\n ...elements1 // <2>\n}\n\nproperties1 {\n name = \"Pigeon\"\n diet = \"Seeds\"\n}\n\nproperties2 {\n ...properties1 // <3>\n}\n----\n<1> Spreads entries `[\"Pigeon\"] = \"Piggy the Pigeon\"` and `[\"Barn owl\"] = \"Barney the Barn owl\"`\n<2> Spreads elements `1` and `2`\n<3> Spreads properties `name = \"Pigeon\"` and `diet = \"Seeds\"`\n\nSpreading all other iterable types generates members determined by the iterable.\nThe following table describes how different iterables turn into object members:\n\n|===\n|Iterable type|Member type\n\n| `Map`\n| Entry\n\n| `List`\n| Element\n\n| `Set`\n| Element\n\n| `IntSeq`\n| Element\n\n| `Bytes`\n| Element\n|===\n\nThese types can only be spread into enclosing objects that support that member type.\nFor example, a `List` can be spread into a `Listing`, but cannot be spread into a `Mapping`.\n\nIn some ways, spread syntax can be thought of as a shorthand for a xref:for-generators[for generator]. One key difference is that spread syntax can generate properties, which is not possible with a for generator.\n\n[NOTE]\n====\nLook out for duplicate key conflicts when using spreads.\nSpreading entries or properties may cause conflicts due to matched existing key definitions.\n\nIn the following code snippet, `\"Pigeon\"` is declared twice in the `newPets` object, and thus is an error.\n\n[source%tested%error,{pkl}]\n----\noldPets {\n [\"Pigeon\"] = \"Piggy the Pigeon\"\n [\"Parrot\"] = \"Perry the Parrot\"\n}\n\nnewPets {\n ...oldPets\n [\"Pigeon\"] = \"Toby the Pigeon\" // <1>\n}\n----\n<1> Error: Duplicate definition of member `\"Pigeon\"`.\n====\n\n==== Nullable spread\n\nA non-nullable spread (`\\...`) will error if the value being spread is `null`.\n\nIn contrast, a nullable spread (`\\...?`) is syntactic sugar for wrapping a spread in a xref:when-generators[`when`].\n\nThe following two snippets are logically identical.\n\n[source%parsed,{pkl}]\n----\nresult {\n ...?myValue\n}\n----\n\n[source%parsed,{pkl}]\n----\nresult {\n when (myValue != null) {\n ...myValue\n }\n}\n----\n\n[[member-predicates]]\n=== Member Predicates (`[[...]]`)\n\nOccasionally it is useful to configure all object members matching a predicate.\nThis is especially true when configuring elements, which—unlike entries—cannot be accessed by key:\n\n[source%tested,{pkl}]\n----\nenvironmentVariables { // <1>\n new { name = \"PIGEON\"; value = \"pigeon-value\" }\n new { name = \"PARROT\"; value = \"parrot-value\" }\n new { name = \"BARN OWL\"; value = \"barn-owl-value\" }\n}\n\nupdated = (environmentVariables) {\n [[name == \"PARROT\"]] { // <2>\n value = \"new-value\" // <3>\n }\n}\n----\n<1> a listing of environment variables\n<2> amend element(s) whose name equals \"PARROT\" +\n(`name` is shorthand for `this.name`)\n<3> update value to \"new-value\"\n\nThe predicate, enclosed in double brackets (`\\[[...]]`), is matched against each member of the enclosing object.\nWithin the predicate, `this` refers to the member that the predicate is matched against.\nMatching members are amended (`{ ... }`) or overridden (`= `).\n\n[[this-keyword]]\n=== `this` keyword\n\nNormally, the `this` keyword references the enclosing object's receiver.\n\nExample:\n[source,pkl]\n----\nbird {\n eatsInsects = this is InsectavorousBird\n}\n----\n\nWhen used inside a <>, `this` refers to the value being tested.\n\nExample:\n[source,pkl]\n----\nport: UInt16(this > 1000)\n----\n\nWhen used inside a <>, `this` refers to the value being matched against.\n\nExample:\n[source,pkl]\n----\nanimals {\n [[this is Bird]] {\n canFly = true\n }\n}\n----\n\n[[receiver]]\n==== Receiver\n\nThe receiver is the bottom-most object in the <>.\nThat means that, within the context of an amending object, the receiver is the amending object.\n\nExample:\n[source,pkl]\n----\nhidden lawyerBird {\n title = \"\\(this.name), Esq.\"\n}\n\npolly = (lawyerBird) {\n name = \"Polly\" // <1>\n}\n----\n<1> Polly has title `\"Polly, Esq.\"`.\n\n[[outer-keyword]]\n=== `outer` keyword\n\nThe `outer` keyword references the <> of the immediately outer lexical object.\n\nIt can be useful to disambiguate a lookup that might otherwise resolve elsewhere.\n\nExample:\n[source%tested,pkl]\n----\nfoo {\n bar = \"bar\"\n qux {\n bar = outer.bar // <1>\n }\n}\n----\n<1> References `bar` one level higher.\n\nNote that `outer` cannot be chained.\nIn order to reference a value more than one level higher, a typical pattern is to declare a local property at that level.\n\nFor example:\n\n[source%parsed,pkl]\n----\nfoo {\n local self = this\n bar {\n baz {\n qux = self.qux\n }\n }\n}\n----\n\n[[super-keyword]]\n=== `super` keyword\n\nThe `super` keyword references the parent object in the <>.\n\nWhen used within a class, it refers to the superclass's prototype.\nWhen used within an object, it refers to the parent object in the amends chain.\n\nExample:\n[source%tested,pkl]\n----\nbird = new { name = \"Quail\" }\n\nbird2 = (bird) { name = \"Ms. \\(super.name)\" } // <1>\n\nabstract class Bird {\n foods: Listing\n\n function canEat(food: String): Boolean = foods.contains(food)\n}\n\nclass InsectavorousBird extends Bird {\n function canEat(food: String) =\n super.canEat(food) || food == \"insect\" // <2>\n}\n----\n<1> Result: `\"Ms. Quail\"`\n<2> Calls parent class method `canEat()`\n\nThe `super` keyword must be followed by property/method access, or subscript.\n`super` by itself a syntax error; whereas `super.foo` and `super[\"foo\"]` are valid expressions.\n\n[[module-keyword]]\n=== `module` keyword\n\nThe `module` keyword can be used as either a value, or as a type.\n\nWhen used as a value, it refers to the <> of the module itself.\n\n[source%tested,pkl]\n----\nname = \"Quail\"\n\nsome {\n deep {\n object {\n name = module.name // <1>\n }\n }\n}\n----\n<1> Resolves to `\"Quail\"`\n\nWhen used as a type, it is the module's class.\n\n[source%parsed,pkl]\n----\nmodule Bird\n\nfriend: module // <1>\n----\n<1> Is class `Bird`\n\nThe `module` type is a _self type_.\nIf the module is extended by another module, the `module` type refers to the extending module when\nin the context of that module.\n\n[[glob-patterns]]\n=== Glob Patterns\n\nResources and modules may be imported at the same time by globbing with the <> and <> features.\n\nPkl's glob patterns mostly follow the rules described by link:{uri-glob-7}[glob(7)], with the following differences:\n\n* `*` includes names that start with a dot (`.`).\n* `+++**+++` behaves like `*`, except it also matches directory boundary characters (`/`).\n* Named character classes are not supported.\n* Collating symbols are not supported.\n* Equivalence class expressions are not supported.\n* Support for <> (patterns within `{` and `}`) are added.\n\nHere is a full specification of how globs work:\n\n==== Wildcards\n\nThe following tokens denote wildcards:\n\n[cols=\"1,2\"]\n|===\n|Wildcard |Meaning\n\n|`*`\n|Match zero or more characters, until a directory boundary (`/`) is reached.\n\n|`**`\n|Match zero or more characters, crossing directory boundaries.\n\n|`?`\n|Match a single character.\n\n|`[...]`\n|Match a single character represented by this <>.\n|===\n\nNOTE: Unlike globs within shells, the `*` wildcard includes names that start with a dot (`.`).\n\n[[character-classes]]\n==== Character Classes\n\nCharacter classes are sequences delimited by the `[` and `]` characters, and represent a single\ncharacter as described by the sequence within the enclosed brackets.\nFor example, the pattern `[abc]` means \"a single character that is a, b, or c\".\n\nCharacter classes may be negated using `!`.\nFor example, the pattern `[!abc]` means \"a single character that is not a, b, nor c\".\n\nCharacter classes may use the `-` character to denote a range.\nThe pattern `[a-f]` is equivalent to `[abcdef]`.\nIf the `-` character exists at the beginning or the end of a character class, it does not carry any special meaning.\n\nWithin a character class, the characters `{`, `}`, `\\`, `*`, and `?` do not have any special meaning.\n\nA character class is not allowed to be empty.\nThus, if the first character within the character class is `]`, it is treated literally and not as the closing delimiter of the character class.\nFor example, the glob pattern `[]abc]` matches a single character that is either `]`, `a`, `b`, or `c`.\n\n[[glob-sub-patterns]]\n==== Sub-patterns\n\nSub-patterns are glob patterns delimited by the `{` and `}` characters, and separated by the `,` character.\nFor example, the pattern `{pigeon,parrot}` will match either `pigeon` or `parrot`.\n\nSub-patterns cannot be nested. The pattern `{foo,{bar,baz}}` is not a valid glob pattern, and an error will be thrown during evaluation.\n\n==== Escapes\n\nThe escape character (`\\`) can be used to remove the special meaning of a character. The following escapes are valid:\n\n* `\\[`\n* `\\*`\n* `\\?`\n* `\\\\`\n* `\\{`\n\nAll other escapes are considered a syntax error and an error is thrown.\n\nTIP: If incorporating escape characters into a glob pattern, use <> to express the glob pattern. For example, `+++import*(#\"\\{foo.pkl\"#)+++`. This way, the backslash is interpreted as a backslash and not a string escape.\n\n==== Examples\n[cols=\"1,2\"]\n|===\n|Pattern |Description\n\n|`*.pk[lg]`\n|Anything suffixed by `.pkl`, or `.pkg`.\n\n|`**.y{a,}ml`\n|Anything suffixed by either `yml` or `yaml`, crossing directory boundaries. \n\n|`birds/{\\*.yml,*.json}`\n|Anything within the `birds` subdirectory that ends in `.yml` or `.json`. This pattern is equivalent to `birds/*.{yml,json}`.\n\n|`a?*.txt`\n|Anything starting with `a` and at least one more letter, and suffixed with `.txt`.\n\n|`modulepath:/**.pkl`\n|All Pkl files in the module path.\n|===\n\n[[quoted-identifiers]]\n=== Quoted Identifiers\n\nAn identifier is the name part of an entity in Pkl.\nEntities that are named by identifiers include classes, properties, typealiases, and modules.\nFor example, `class Bird` has the identifier `Bird`.\n\nNormally, an identifier must conform to Unicode's {uri-unicode-identifier}[UAX31-R1-1 syntax], with the additions of `_` and `$` permitted as identifier start characters.\nAdditionally, an identifier cannot clash with a keyword.\n\nTo define an identifier that is otherwise illegal, enclose them in backticks.\nThis is called a _quoted identifier_.\n\n[source,{pkl}]\n----\n`A Bird's First Flight Time` = 5.s\n----\n\n[NOTE]\n====\nBackticks are not part of a quoted identifier's name, and surrounding an already legal identifier with backticks is redundant.\n\n[source,{pkl}]\n----\n`number` = 42 // <1>\nres1 = `number` // <2>\nres2 = number // <3>\n----\n<1> Equivalent to `number = 42`\n<2> References property `{backtick}number{backtick}`\n<3> Also references property `{backtick}number{backtick}`\n====\n\n[[doc-comments]]\n=== Doc Comments\n\nDoc comments are the user-facing documentation of a module and its members.\nThey consist of one or more lines starting with a triple slash (`///`).\nHere is a doc comment for a module:\n\n[source%tested,{pkl}]\n----\n/// An aviated animal going by the name of [bird](https://en.wikipedia.org/wiki/Bird).\n///\n/// These animals live on the planet Earth.\nmodule com.animals.Birds\n----\n\nDoc comments are written in Markdown.\nThe following Markdown features are supported:\n\n* all link:{uri-common-mark}[CommonMark] features\n* https://help.github.com/articles/organizing-information-with-tables[GitHub flavored Markdown tables]\n\n[NOTE]\n====\nPlaintext URLs are only rendered as links when enclosed in angle brackets:\n\n[source,{pkl}]\n----\n/// A link is *not* generated for https://example.com.\n/// A link *is* generated for .\n----\n====\n\nDoc comments are consumed by humans reading source code, the _Pkldoc_ documentation generator, code generators, and editor/IDE plugins.\nThey are programmatically accessible via the link:{uri-stdlib-reflectModule}/[pkl.reflect] Pkl API and link:{uri-pkl-core-ModuleSchema}[ModuleSchema] Java API.\n\n[TIP]\n.Doc Comment Style Guidelines\n====\n* Use proper spelling and grammar.\n* Start each sentence on a new line and capitalize the first letter.\n* End each sentence with a punctuation mark.\n* The first paragraph of a doc comment is its _summary_.\n Keep the summary short (a single sentence is common)\n and insert an empty line (`///`) before the next paragraph.\n====\n\nDoc comments can be attached to module, class, type alias, property, and method declarations.\nHere is a comprehensive example:\n\n.Birds.pkl\n[source%tested,{pkl}]\n----\n/// An aviated animal going by the name of [bird](https://en.wikipedia.org/wiki/Bird).\n///\n/// These animals live on the planet Earth.\nmodule com.animals.Birds\n\n/// A bird living on Earth.\n///\n/// Has [name] and [lifespan] properties and an [isOlderThan()] method.\nclass Bird {\n /// The name of this bird.\n name: String\n\n /// The lifespan of this bird.\n lifespan: UInt8\n\n /// Tells if this bird is older than [bird].\n function isOlderThan(bird: Bird): Boolean = lifespan > bird.lifespan\n}\n\n/// An adult [Bird].\ntypealias Adult = Bird(lifespan >= 2)\n\n/// A common [Bird] found in large cities.\npigeon: Bird = new {\n name = \"Pigeon\"\n lifespan = 8\n}\n\n/// Creates a [Bird] with the given [_name] and lifespan `0`.\nfunction Infant(_name: String): Bird = new { name = _name; lifespan = 0 }\n----\n\n[[member-links]]\n==== Member Links\n\nTo link to a member declaration, write the member's name enclosed in square brackets (`[]`):\n\n[source,{pkl}]\n----\n/// A common [Bird] found in large cities.\n----\n\nTo customize the link text, insert the desired text, enclosed in square brackets, before the member name:\n\n[source,{pkl}]\n----\n/// A [common Bird][Bird] found in large cities.\n----\n\nCustom link text can use markup:\n\n[source,{pkl}]\n----\n/// A [*common* Bird][Bird] found in large cities.\n----\n\nThe short link `[Bird]` is equivalent to `[{backtick}Bird{backtick}][Bird]`.\n\nMember links are resolved according to Pkl's normal name resolution rules.\nThe syntax for linking to the members of _Birds.pkl_ (see above) is as follows:\n\nModule::\n* `[module]` (from same module)\n* `[Birds]` (from a module that contains `import \"Birds.pkl\"`)\n\nClass::\n* `[Bird]` (from same module)\n* `[Birds.Bird]` (from a module that contains `import \"Birds.pkl\"`)\n\nType Alias::\n* `[Adult]` (from same module)\n* `[Birds.Adult]` (from a module that contains `import \"Birds.pkl\"`)\n\nClass Property::\n* `[name]` (from same class)\n* `[Bird.name]` (from same module)\n* `[Birds.Bird.name]` (from a module that contains `import \"Birds.pkl\"`)\n\nClass Method::\n* `[greet()]` (from same class)\n* `[Bird.greet()]` (from same module)\n* `[Birds.Bird.greet()]` (from a module that contains `import \"Birds.pkl\"`)\n\nClass Method Parameter::\n* `[bird]` (from same method)\n\nModule Property::\n* `[pigeon]` (from same module)\n* `[Birds.pigeon]` (from a module that contains `import \"Birds.pkl\"`)\n\nModule Method::\n* `[isPigeon()]` (from same module)\n* `[Birds.isPigeon()]` (from a module that contains `import \"Birds.pkl\"`)\n\nModule Method Parameter::\n* `[bird]` (from same method)\n\nMembers of `pkl.base` can be linked to by their simple name:\n\n[source,{pkl}]\n----\n/// Returns a [String].\n----\n\nModule-level members can be prefixed with `module.` to resolve name conflicts:\n\n[source,{pkl}]\n----\n/// See [module.pigeon].\n----\n\nTo exclude a member from documentation and code completion, <> it with `@Unlisted`:\n\n[source%parsed,{pkl}]\n----\n@Unlisted\npigeon: Bird\n----\n\nThe following member links are marked up as code but not rendered as links:footnote:[Only applies to links without custom link text.]\n\n* `[null]`, `[true]`, `[false]`, `[this]`, `[unknown]`, `[nothing]`\n* self-links\n* subsequent links to the same member from the same doc comment\n* links to a method's own parameters\n\nNevertheless, it is a good practice to use member links in the above cases.\n\n[[annotations]]\n=== Annotations\n\nAnnotations are a mechanism to provides extra metadata about Pkl <>, <>, <>, and <>.\nThey provide metadata about the type or member they annotate that can be via link:{uri-stdlib-reflectModule}[reflection] or Pkl's Java APIs.\nThe most common use cases for annotations are to add metadata to influence behavior of xref:pkl-doc:index.adoc[Pkldoc], code generation tools, or <>.\n\nAnnotations are regular Pkl objects whose class extends link:{uri-stdlib-Annotation}[`Annotation`].\nAnnotation instances are defined similarly to regular <>, but instead of using the `new` keyword the class name is prefixed with `@`.\nThe object body may be omitted if an annotation's class has no properties or the declared annotation does not override any of the class's default values\nMultiple annotations may be defined on a member.\nIf the annotated member has a <>, the annotation is defined between the comment and the member.\n\n[source%tested,{pkl}]\n----\n/// Module doc comment\n@SomeAnnotation // <1>\nmodule myModule\n\nclass SomeAnnotation extends Annotation { // <2>\n description: String = \"some annotation\"\n}\n\n/// Module doc comment\n@SomeAnnotation // <3>\nclass Bird {\n @SomeAnnotation { description = \"some property\" } // <4>\n name: String\n\n @SomeAnnotation { description = \"some method\" } // <5>\n @Unlisted // <6>\n function greet(greeting: String): String = \"\\(greeting), \\(name)!\"\n}\n----\n<1> An annotation applied to a module. The annotation(s) must precede the `module` clause and follow the doc comment. The object body is omitted.\n<2> The definition of an annotation class.\n<3> An annotation appied to a class. The object body is omitted.\n<4> An annotation applied to a property. The object body is included because the `description` property is overridden.\n<5> An annotation applied to a method. The object body is included because the `description` property is overridden.\n<6> A second annotation applied to the same method.\n\n[[name-resolution]]\n=== Name Resolution\n\nConsider this snippet of code buried deep inside a config file:\n\n[source%parsed,{pkl}]\n----\na = x + 1\n----\n\nThe call site's \"variable\" syntax reveals that `x` refers to a _LAMP_\n(let binding, anonymous function parameter, method parameter, or property) definition. But which one?\n\nTo answer this question, Pkl follows these steps:\n\n. Search the lexically enclosing scopes of `x`,\n starting with the scope in which `x` occurs and continuing outwards\n up to and including the enclosing module's top-level scope, for a LAMP definition named `x`.\n If a match is found, this is the answer.\n. Search the `pkl.base` module for a top-level definition of property `x`.\n If a match is found, this is the answer.\n. Search the <> of `this`, from bottom to top, for a definition of property `x`.\n If a match is found, this is the answer.\n. Throw a \"name `x` not found\" error.\n\nNOTE: Pkl's LAMP name resolution is inspired by link:{uri-newspeak}[Newspeak].\nThe goal is for name resolution to be stable with regard to changes in external modules.\nThis is why lexically enclosing scopes are searched before the prototype chain of `this`,\nand why the prototype chains of lexically enclosing scopes are not searched,\nwhich sometimes requires the use of `outer.` or `module.`.\nFor name resolution to fully stabilize, the list of top-level properties defined in `pkl.base` needs to be freezed.\nThis is tentatively planned for Pkl 1.0.\n\nConsider this snippet of code buried deep inside a config file:\n\n[source%parsed,{pkl}]\n----\na = x(\"foo\") + 1\n----\n\nThe call site's method call syntax reveals that `x` refers to a method definition. But which one?\n\nTo answer this question, Pkl follows these steps:\n\n. Search the call sites' lexically enclosing scopes,\n starting with the scope in which the call site occurs and continuing outwards\n up to and including the enclosing module's top-level scope, for a definition of method `x`.\n If a match is found, this is the answer.\n. Search the `pkl.base` module for a top-level definition of method `x`.\n If a match is found, this is the answer.\n. Search the class inheritance chain of `this`, starting with the class of `this`\n and continuing upwards until and including class `Any`, for a method named `x.`\n If a match is found, this is the answer.\n. Throw a \"method `x` not found\" error.\n\nNOTE: Pkl does not support arity or type-based method overloading.\nHence, the argument list of a method call is irrelevant for method resolution.\n\n[[prototype-chain]]\n==== Prototype Chain\n\nPkl's object model is based on link:{uri-prototypical-inheritance}[prototypical inheritance].\nThe prototype chain of objectfootnote:[An instance of `Listing`, `Mapping`, `Dynamic`, or (a subclass of) `Typed`.] `x` contains, from bottom to top:\n\n1. The chain of objects amended to create `x`, ending in `x` itself, in reverse order.footnote:[All objects in this chain are instances of the same class,\n except when a direct conversion between listing, mapping, dynamic, and typed object has occurred.\n For example, `Typed.toDynamic()` returns a dynamic object that amends a typed object.]\n2. The prototype of the class of the top object in (1).\n If no amending took place, this is the class of `x`.\n3. The prototypes of the superclasses of (2).\n\nThe prototype of class `X` is an instance of `X` that defines the defaults for properties defined in `X`.\nIts direct ancestor in the prototype chain is the prototype of the superclass of `X`.\n\nThe prototype of class `Any` sits at the top of every prototype chain.\nTo reduce the chance of naming collisions, `Any` does not define any property names.footnote:[Method resolution searches the class inheritance rather than prototype chain.]\n\nConsider the following code:\n\n[source%tested,{pkl}]\n----\none = new Dynamic { name = \"Pigeon\" }\ntwo = (one) { lifespan = 8 }\n----\n\nThe prototype chain of object `two` contains, now listed from top to bottom:\n\n. The prototype of class `Any`.\n. The prototype of class `Dynamic`.\n. `one`\n. `two`\n\nConsider the following code:\n\n[source%tested,{pkl}]\n----\nabstract class Named {\n name: String\n}\nclass Bird extends Named {\n lifespan: Int = 42\n}\none = new Bird { name = \"Pigeon\" }\ntwo = (one) { lifespan = 8 }\n----\n\nThe prototype chain of object `two` contains, listed from top to bottom:\n\n. The prototype of class `Any`.\n. The prototype of class `Typed`.\n. The prototype of class `Named`.\n. The prototype of class `Bird`.\n. `one`\n. `two`\n\n===== Non-object Values\n\nThe prototype chain of non-object value `x` contains, from bottom to top:\n\n1. The prototype of the class of `x`.\n2. The prototypes of the superclasses of (1).\n\nFor example, the prototype chain of value `42` contains, now listed from top to bottom:\n\n. The prototype of class `Any`.\n. The prototype of class `Number`.\n. The prototype of class `Int`.\n\nA prototype chain never contains a non-object value, such as `42`.\n\n[[reserved-keywords]]\n=== Reserved keywords\n\nThe following keywords are reserved in the language.\nThey cannot be used as a regular identifier, and currently do not have any meaning.\n\n* `protected`\n* `override`\n* `record`\n* `delete`\n* `case`\n* `switch`\n* `vararg`\n\nTo use these names in an identifier, <>.\n\nFor a complete list of keywords, consult field `Lexer.KEYWORDS` in {uri-github-PklLexer}[Lexer.java].\n\n[[blank-identifiers]]\n=== Blank Identifiers\n\nBlank identifiers can be used in many places to ignore parameters and variables. +\n`_` is not a valid identifier. To use it as a parameter or variable name,\nit needs to be enclosed in backticks: +`_`+.\n\n==== Functions and methods\n\n[source%tested,{pkl}]\n----\nbirds = List(\"Robin\", \"Swallow\", \"Eagle\", \"Falcon\")\nindexes = birds.mapIndexed((i, _) -> i)\n\nfunction constantly(_, second) = second \n----\n\n==== For generators\n\n[source%tested,{pkl}]\n----\nbirdColors = Map(\"Robin\", \"blue\", \"Eagle\", \"white\", \"Falcon\", \"red\")\n\nbirds = new Listing {\n for (name, _ in birdColors) {\n name\n }\n}\n----\n\n==== Let bindings\n\n[source%tested,{pkl}]\n----\nname = let (_ = trace(\"defining name\")) \"Eagle\"\n----\n\n==== Object bodies\n\n[source%tested,{pkl}]\n----\nbirds = new Dynamic {\n default { _ ->\n species = \"Bird\"\n }\n [\"Falcon\"] {}\n [\"Eagle\"] {}\n}\n----\n\n[[projects]]\n=== Projects\n\nA _project_ is a directory of Pkl modules and other resources.\nIt is defined by the presence of a `PklProject` file that amends the standard library module\n`pkl:Project`.\n\nDefining a project serves the following purposes:\n\n1. It allows defining common evaluator settings for Pkl modules within a logical project.\n2. It helps with managing <> dependencies for Pkl modules within a logical project.\n3. It enables packaging and sharing the contents of the project as a <>.\n4. It allows importing packages via dependency notation.\n\n[[project-dependencies]]\n==== Dependencies\n\nA project is useful for managing <> dependencies.\n\nWithin a PklProject file, dependencies can be defined:\n\n.PklProject\n[source%tested,{pkl}]\n----\namends \"pkl:Project\"\n\ndependencies {\n [\"birds\"] { // <1>\n uri = \"package://example.com/birds@1.0.0\"\n }\n}\n----\n<1> Declare dependency on `package://example.com/birds@1.0.0` with simple name \"birds\".\n\nThese dependencies can then be imported by their simple name.\nThis syntax is called _dependency notation_.\n\nExample:\n\n[source,{pkl}]\n----\nimport \"@birds/Bird.pkl\" // <1>\n\npigeon: Bird = new {\n name = \"Pigeon\"\n}\n----\n<1> Dependency notation; imports path `/Bird.pkl` within dependency `package://example.com/birds@1.0.0`\n\nNOTE: Internally, Pkl assigns URI scheme `projectpackage` to project dependencies imported using dependency notation.\n\nWhen the project gets published as a _package_, these names and URIs are preserved as the package's dependencies.\n\n[[resolving-dependencies]]\n==== Resolving Dependencies\n\nDependencies that are declared in a `PklProject` file must be _resolved_ via CLI command xref:pkl-cli:index.adoc#command-project-resolve[`pkl project resolve`].\nThis builds a single dependency list, resolving all transitive dependencies, and determines the appropriate version for each package.\nIt creates or updates a file called `PklProject.deps.json` in the project's root directory with the list of resolved dependencies.\n\nWhen resolving version conflicts, the CLI will pick the latest link:{uri-semver}[semver] minor version of each package.\nFor example, if the project declares a dependency on package A at `1.2.0`, and a package transitively declares a dependency on package A at `1.3.0`, version `1.3.0` is selected.\n\nIn short, the algorithm has the following steps:\n\n1. Gather a list of all dependencies, either directly declared or transitive.\n2. For each dependency, keep only the newest minor version.\n\nThe resolve command is idempotent; given a PklProject file, it always produces the same set of resolved dependencies.\n\nNOTE: This algorithm is adapted from Go's link:{uri-mvs-build-list}[minimum version selection].\n\n==== Creating a Package\n\nProjects enable the creation of a <>.\nTo create a package, the `package` section of a `PklProject` module must be defined.\n\n.PklProject\n[source,pkl]\n----\namends \"pkl:Project\"\n\npackage {\n name = \"mypackage\" // <1>\n baseUri = \"package://example.com/\\(name)\" // <2>\n version = \"1.0.0\" // <3>\n packageZipUrl = \"https://example.com/\\(name)/\\(name)@\\(version).zip\" // <4>\n}\n----\n<1> The display name of the package.For display purposes only.\n<2> The package URI, without the version part.\n<3> The version of the package.\n<4> The URL to download the package's ZIP file.\n\nThe package itself is created by the command xref:pkl-cli:index.adoc#command-project-package[`pkl project package`].\n\nThis command only prepares artifacts to be published.\nOnce the artifacts are prepared, they are expected to be uploaded to an HTTPS server such that the ZIP asset can be downloaded at path `packageZipUrl`, and the metadata can be downloaded at `+https://+`.\n\n[[local-dependencies]]\n==== Local dependencies\n\nA project can depend on a local project as a dependency.\nThis can be useful for:\n\n* Structuring a monorepo that publishes multiple packages.\n* Temporarily testing out library changes when used within another project.\n\nTo specify a local dependency, import its `PklProject` file.\nThe imported `PklProject` _must_ have a package section defined.\n\n.birds/PklProject\n[source,{pkl}]\n----\namends \"pkl:Project\"\n\ndependencies {\n [\"fruit\"] = import(\"../fruit/PklProject\") // <1>\n}\n\npackage {\n name = \"birds\"\n baseUri = \"package://example.com/birds\"\n version = \"1.8.3\"\n packageZipUrl = \"https://example.com/birds@\\(version).zip\"\n}\n----\n<1> Specify relative project `../fruit` as a dependency.\n\n.fruit/PklProject\n[source,{pkl}]\n----\namends \"pkl:Project\"\n\npackage {\n name = \"fruit\"\n baseUri = \"package://example.com/fruit\"\n version = \"1.5.0\"\n packageZipUrl = \"https://example.com/fruit@\\(version).zip\"\n}\n----\n\nFrom the perspective of project `birds`, `fruit` is just another package.\nIt can be imported using dependency notation, i.e. `import \"@fruit/Pear.pkl\"`.\nAt runtime, it will resolve to relative path `../fruit/Pear.pkl`.\n\nWhen packaging projects with local dependencies, both the project and its dependent project must be passed to the xref:pkl-cli:index.adoc#command-project-package[`pkl project package`] command.\n\n[[external-readers]]\n=== External Readers\n\nExternal readers are a mechanism to extend the <> and <> URI schemes that Pkl supports.\nReaders are implemented as ordinary executables and use Pkl's xref:bindings-specification:message-passing-api.adoc[message passing API] to communicate with the hosting Pkl evaluator.\nThe xref:swift:ROOT:index.adoc[Swift] and xref:go:ROOT:index.adoc[Go] language binding libraries provide an `ExternalReaderRuntime` type to facilitate implementing external readers.\n\nExternal readers are configured separately for modules and resources.\nThey are registered by mapping their URI scheme to the executable to run and additional arguments to pass.\nThis is done on the command line by passing `--external-resource-reader` and `--external-module-reader` flags, which may both be passed multiple times.\n\n[source,text]\n----\n$ pkl eval --external-resource-reader = --external-module-reader =' '\n----\n\nExternal readers may also be configured in a <> `PklProject` file.\n[source,{pkl}]\n----\nevaluatorSettings {\n externalResourceReaders {\n [\"\"] {\n executable = \"\"\n }\n }\n externalModuleReaders {\n [\"\"] {\n executable = \"\"\n arguments { \"\"; \"\" }\n }\n }\n}\n----\n\nRegistering an external reader for a scheme automatically adds that scheme to the default allowed modules/resources.\nAs with Pkl's built-in module and resource schemes, setting explicit allowed modules or resources overrides this behavior and appropriate patterns must be specified to allow use of external readers.\n\n==== Example\n\nConsider this module:\n\n[source,{pkl}]\n----\nusername = \"pigeon\"\n\nemail = read(\"ldap://ds.example.com:389/dc=example,dc=com?mail?sub?(uid=\\(username))\").text\n----\n\nPkl doesn't implement the `ldap:` resource URI scheme natively, but an external reader can provide it.\nAssuming a hypothetical `pkl-ldap` executable implementing the external reader protocol and the `ldap:` scheme is in the `$PATH`, this module can be evaluated as:\n\n[source,text]\n----\n$ pkl eval --external-resource-reader ldap=pkl-ldap\nusername = \"pigeon\"\nemail = \"pigeon@example.com\"\n----\n\nIn this example, the external reader may provide both `ldap:` and `ldaps:` schemes.\nTo support both schemes during evaluation, both would need to be registered explicitly:\n[source,text]\n----\n$ pkl eval --external-resource-reader ldap=pkl-ldap --external-resource-reader ldaps=pkl-ldap\n----\n\n[[mirroring_packages]]\n=== Mirroring packages\n\nA package is a shareable archive of modules and resources that are published to the internet.\n\nA package's URI tells two things:\n\n1. The name of the package.\n2. Where the package is downloaded from.\n\nFor example, given the package name `package://example.com/mypackage@1.0.0`, Pkl will make an HTTPS request to `\\https://example.com/mypackage@1.0.0` to fetch package metadata.\n\nIn situations where internet access is restricted, a mirror can be set up to allow use of packages that are published to the internet.\n\nTo direct Pkl to a mirror, the `--http-rewrite` CLI option (and its equivalent options when using Pkl's other evaluator APIs) must be used.\nFor example, `--http-rewrite \\https://pkg.pkl-lang.org/=\\https://my.internal.mirror/` will tell Pkl to download packages from host `my.internal.mirror`.\n\nNOTE: To effectively mirror packages from pkg.pkl-lang.org, there must be two rewrites; one for `\\https://pkg.pkl-lang.org/` (where package metadata is downloaded), and one for `\\https://github.com/` (where package zip files are downloaded).\n\nNOTE: Pkl does not provide any tooling to run a mirror server.\nTo fully set up mirroring, an HTTP(s) server will need be running, and which mirrors the same assets byte-for-byte.\n" }, { "path": "docs/modules/language-tutorial/pages/01_basic_config.adoc", "content": "= Basic Configuration\ninclude::ROOT:partial$component-attributes.adoc[]\n\nIn this first part of xref:index.adoc[the Pkl tutorial], you build familiarity with Pkl syntax and basic structure.\nYou also learn different ways to invoke Pkl to produce different formats.\n\n== Basic values\n\nConsider the following example Pkl file.\n\n[source,{pkl}]\n.intro.pkl\n----\nname = \"Pkl: Configure your Systems in New Ways\"\nattendants = 100\nisInteractive = true\namountLearned = 13.37\n----\n\nRunning Pkl on this file gives\n\n[source,shell]\n----\n$ pkl eval /Users/me/tutorial/intro.pkl\nname = \"Pkl: Configure your Systems in New Ways\"\nattendants = 100\nisInteractive = true\namountLearned = 13.37\n----\n\nIt may seem nothing happened.\nHowever, Pkl tells you that it _accepts the input_.\nIn other words, you now know that `intro.pkl` does not contain any errors.\n\nYou can ask Pkl to print this configuration in a different format, using the `-f` option.\nFor example, JSON:\n\n[source,shell]\n----\n$ pkl eval -f json /Users/me/tutorial/intro.pkl\n{\n \"name\": \"Pkl: Configure your Systems in New Ways\",\n \"attendants\": 100,\n \"isInteractive\": true,\n \"amountLearned\": 13.37\n}\n----\n\nOr _PropertyList_ format:\n\n[source,shell]\n----\n$ pkl eval -f plist /Users/me/tutorial/intro.pkl\n\n\n\n\n name\n Pkl: Configure your Systems in New Ways\n attendants\n 100\n isInteractive\n \n amountLearned\n 13.37\n\n\n----\n\nNotice that Pkl generated ``, ``, `` and `` for the values in your configuration.\nThis means it has _both_ correctly derived the types of the literal values _and_ translated those types to the corresponding elements in the PropertyList.\nxref:03_writing_a_template.adoc[Part III] goes into types in more detail.\n\n\n== Structure: Classes, objects, modules\n\nA configuration often requires more than just basic values.\nTypically, you need some kind of (hierarchical) structure.\nPkl provides _immutable objects_ for this.\n\nObjects have three kinds of members: properties, elements and entries.\nFirst, look at the syntax for objects and their members.\n\n=== Properties\n\n[source,{pkl}]\n.simpleObjectWithProperties.pkl\n----\nbird { // <1>\n name = \"Common wood pigeon\" // <2>\n diet = \"Seeds\"\n taxonomy { // <3>\n species = \"Columba palumbus\"\n }\n}\n----\n<1> This _defines_ `bird` to be an object\n<2> For primitive values, Pkl has the `=` syntax (more on this later).\n<3> Just like `bird {`, but to show that objects can be nested.\n\nThis defines an object called `bird` with three _named properties_: `name`, `diet`, and `taxonomy`.\nThe first two of these are strings, but `taxonomy` is another object.\nThis means properties in an object can have different types and objects can be nested.\n\n=== Elements\n\nOf course, you don't always have names for every individual structure in your configuration.\nWhat if you want \"just a bunch of things\" without knowing how many?\nPkl offers _elements_ for this purpose.\nElements are object members, just like properties.\nWhere you index properties by their name, you index elements by an integer.\nYou can think of an object that only contains elements as _array_.\nMuch like arrays in many languages, you can use square brackets to access an element, for example, `myObject[42]`.\n\nYou write an element, by writing only an expression.\nPkl derives the index from the number of elements already in the object.\nFor example:\n\n[source,{pkl}]\n.simpleObjectsWithElements.pkl\n----\nexampleObjectWithJustIntElements {\n 100 // <1>\n 42\n}\n\nexampleObjectWithMixedElements {\n \"Bird Breeder Conference\"\n (2000 + 23) // <2>\n exampleObjectWithJustIntElements // <3>\n}\n----\n<1> When you write only the value (without a name), you describe an _element_.\n<2> Elements don't have to be literal values; they can be arbitrary _expressions_.\n<3> Elements can really be _any_ value, not just primitive values.\n\n[[entries]]\n=== Entries\n\nObjects can have one more kind of member; _entries_.\nLike a _property_, an _entry_ is \"named\" (technically _keyed_).\nUnlike a property, the name does not need to be known at declaration time.\nOf course, we need a syntax to tell entries apart from properties.\nYou write entry \"names\" by enclosing them in square brackets (\"names\" is quoted, because the names do not need to be strings; any value can index entries).\n\n[source,{pkl}]\n.simpleObjectsWithEntries.pkl\n----\npigeonShelter {\n [\"bird\"] { // <1>\n name = \"Common wood pigeon\"\n diet = \"Seeds\"\n taxonomy {\n species = \"Columba palumbus\"\n }\n }\n [\"address\"] = \"355 Bird St.\" // <2>\n}\n\nbirdCount {\n [pigeonShelter] = 42 // <3>\n}\n----\n<1> The difference with properties is the notation of the key: `[]`.\n<2> As with properties, entries can be primitive values or objects.\n<3> Any object can be used as a key for an entry.\n\n\n=== Mixed members\n\nIn the examples so far, you have seen objects with properties, object with elements and object with entries.\nThese object members can be freely mixed.\n\n[source,{pkl}]\n.mixedObject.pkl\n----\nmixedObject {\n name = \"Pigeon\"\n lifespan = 8\n \"wing\"\n \"claw\"\n [\"wing\"] = \"Not related to the _element_ \\\"wing\\\"\"\n 42\n extinct = false\n [false] {\n description = \"Construed object example\"\n }\n}\n----\n\nNotice, how properties (`name`, `lifespan` and `extinct`), elements (`\"wing\"`, `\"claw\"`, `42`) and entries (`\"wing\"`, `false`) are mixed together in this one object.\nYou don't have to order them by kind, and you don't require (other) special syntax.\n\n=== Collections\n\nThis free-for-all mixing of object members can become confusing.\nAlso, target formats are often considerably more restrictive.\nIn the following example, you see what happens when you try to produce JSON from `mixedObject`:\n\n[source,shell]\n----\n$ pkl eval -f json /Users/me/tutorial/mixedObject.pkl\n–– Pkl Error ––\nCannot render object with both properties/entries and elements as JSON.\nObject: \"Pigeon\"\n\n89 | text = renderer.renderDocument(value)\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nat pkl.base#Module.output.text (https://github.com/apple/pkl/blob/0.24.0/stdlib/base.pkl#L90)\n----\n\nThis is why Pkl has two special types of object, namely _listings_, which contain _exclusively_ elements, and _mappings_, which contain _exclusively_ entries.\nBoth listings and mappings _are_ \"just objects,\" so, they don't require syntax besides that of objects:\n\n[source,{pkl}]\n.collections.pkl\n----\nbirds { // <1>\n \"Pigeon\"\n \"Parrot\"\n \"Barn owl\"\n \"Falcon\"\n}\n\nhabitats { // <2>\n [\"Pigeon\"] = \"Streets\"\n [\"Parrot\"] = \"Parks\"\n [\"Barn owl\"] = \"Forests\"\n [\"Falcon\"] = \"Mountains\"\n}\n----\n<1> A listing containing four elements.\n<2> A mapping containing four entries.\n\n[NOTE]\n====\n_Technically_, the correct way to define `birds` and `habitats` is by using `new Listing {...}` and `new Mapping {...}` explicitly.\nYou will see what these mean in part xref:03_writing_a_template.adoc[three] of this tutorial.\n====\n\nWhen you render _this_ configuration as JSON, everything works:\n\n[source,json]\n----\n{\n \"birds\": [\n \"Pigeon\",\n \"Parrot\",\n \"Barn owl\",\n \"Falcon\"\n ],\n \"habitats\": {\n \"Pigeon\": \"Streets\",\n \"Parrot\": \"Parks\",\n \"Barn owl\": \"Forests\",\n \"Falcon\": \"Mountains\"\n }\n}\n----\n\nNotice particularly, that you rendered the listing as a JSON _array_.\nWhen you index the listing with an integer, you're referring to the element inside the listing at the corresponding position (starting from `0`).\nFor example:\n\n[source,{pkl}]\n.indexedListing.pkl\n----\nbirds {\n \"Pigeon\"\n \"Parrot\"\n \"Barn owl\"\n \"Falcon\"\n}\n\nrelatedToSnowOwl = birds[2]\n----\nresults in\n[source,{pkl}]\n----\nbirds {\n \"Pigeon\"\n \"Parrot\"\n \"Barn owl\"\n \"Falcon\"\n}\nrelatedToSnowOwl = \"Barn owl\"\n----\n\n== Exercises\n\n1. Given the following JSON snippet (taken from W3C examples), write the `.pkl` file that produces this JSON:\n\n+\n[source,json]\n----\n{\n \"name\": \"Common wood pigeon\",\n \"lifespan\": 8,\n \"friends\": {\n \"bird1\": \"Parrot\",\n \"bird2\": \"Albatross\",\n \"bird3\": \"Falcon\"\n }\n}\n----\n\n2. For some reason, we decide we no longer need the birdX names of the different birds; we just need them as an array.\n Change your solution to the previous question to produce the following JSON result:\n\n+\n[source,json]\n----\n{\n \"name\": \"Common wood pigeon\",\n \"lifespan\": 8,\n \"birds\": [\"Parrot\", \"Barn owl\", \"Falcon\"]\n}\n----\n" }, { "path": "docs/modules/language-tutorial/pages/02_filling_out_a_template.adoc", "content": "= Filling out a Template\ninclude::ROOT:partial$component-attributes.adoc[]\n\nIn this second part of xref:index.adoc[the Pkl tutorial], you will learn how to write one (part of a) configuration in terms of another.\nYou will also find and fill out an existing _template_.\n\n== Composing configurations\n=== Amending\n\nThe central mechanism in Pkl for expressing one (part of a) configuration in terms of another is _amending_.\nConsider the following example.\n\n[source,{pkl}]\n.amendingObjects.pkl\n----\nbird {\n name = \"Pigeon\"\n diet = \"Seeds\"\n taxonomy {\n kingdom = \"Animalia\"\n clade = \"Dinosauria\"\n order = \"Columbiformes\"\n }\n}\n\nparrot = (bird) {\n name = \"Parrot\"\n diet = \"Berries\"\n taxonomy {\n order = \"Psittaciformes\"\n }\n}\n----\n\nParrot and Pigeon have nearly identical properties.\nThey only differ in their name and taxonomy, so if you have already written out `bird`, you can say that `parrot` is just like `bird` except `name` is `\"Parrot\"`, diet is `\"Berries\"` the `taxonomy.order` is `\"Psittaciformes\"`.\nWhen you run this, Pkl expands everything fully.\n\n[source,{pkl}]\n----\nbird {\n name = \"Pigeon\"\n diet = \"Seeds\"\n taxonomy {\n kingdom = \"Animalia\"\n clade = \"Dinosauria\"\n order = \"Columbiformes\"\n }\n}\nparrot {\n name = \"Parrot\"\n diet = \"Berries\"\n taxonomy {\n kingdom = \"Animalia\"\n clade = \"Dinosauria\"\n order = \"Psittaciformes\"\n }\n}\n----\n\n[NOTE]\n====\nSo far, you have only worked with link:{uri-stdlib-Dynamic}[Dynamic] objects.\nPkl also offers link:{uri-stdlib-Typed}[Typed] objects.\n_Amending_ allows you to override, amend, and add new properties to a dynamic object.\nTyped objects will only let you amend or override existing properties, not add entirely new ones.\nThe xref:03_writing_a_template.adoc[next part of the tutorial] discusses types in more detail.\nThere, you see that amending _never changes the type_ of the object.\n====\n\nYou can also amend nested objects.\nThis allows you to only describe the difference with the outermost object for arbitrarily deeply nested structures.\nConsider the following example.\n\n[source,{pkl}]\n.nestedAmends.pkl\n----\nstockPigeon {\n name = \"Stock pigeon\"\n diet = \"Seeds\"\n taxonomy {\n kingdom = \"Animalia\"\n clade = \"Columbimorphae\"\n order = \"Columbiformes\"\n species = \"Columba oenas\"\n }\n}\n\nwoodPigeon = (stockPigeon) {\n name = \"Common wood pigeon\"\n taxonomy { // <1>\n species = \"Columba palumbus\"\n }\n}\n\ndodo = (woodPigeon) { // <2>\n name = \"Dodo\"\n extinct = true // <3>\n taxonomy {\n species = \"Raphus cucullatus\"\n }\n}\n----\n<1> This amends `species`, _as it occurs in_ `stockPigeon`.\n<2> Amended objects can, themselves, be amended.\n<3> New fields can be added to objects when amending.\n\nNotice how you only have to change `taxonomy.species`.\nIn this example, `stockPigeon.taxonomy` has `kingdom`, `clade`, `order` and `species`.\nYou are amending `stockPigeon`, to define `woodPigeon`.\nThey have the same `taxonomy`, except for `species`.\nThis notation says that everything in `taxonomy` should be what it is in the object you are amending (`stockPigeon`), except for `species`, which should be `\"Columba palumbus\"` .\n\nFor the input above, Pkl produces the following output.\n[source,{pkl}]\n----\nstockPigeon {\n name = \"Stock pigeon\"\n diet = \"Seeds\"\n taxonomy {\n kingdom = \"Animalia\"\n clade = \"Columbimorphae\"\n order = \"Columbiformes\"\n species = \"Columba oenas\"\n }\n}\nwoodPigeon {\n name = \"Common wood pigeon\"\n diet = \"Seeds\"\n taxonomy {\n kingdom = \"Animalia\"\n clade = \"Columbimorphae\"\n order = \"Columbiformes\"\n species = \"Columba palumbus\"\n }\n}\ndodo {\n name = \"Dodo\"\n diet = \"Seeds\"\n taxonomy {\n kingdom = \"Animalia\"\n clade = \"Columbimorphae\"\n order = \"Columbiformes\"\n species = \"Raphus cucullatus\"\n }\n extinct = true\n}\n----\n\nSo far, you have only amended _properties_.\nSince you refer to them by name, it makes sense that you \"overwrite\" the value from the object you're amending.\nWhat if you include _elements_ or _entries_ in an amends expression?\n\n[source,{pkl}]\n.amendElementsAndEntries.pkl\n----\nfavoriteFoods {\n \"red berries\"\n \"blue berries\"\n [\"Barn owl\"] {\n \"mice\"\n }\n}\n\nadultBirdFoods = (favoriteFoods) {\n [1] = \"pebbles\" // <1>\n \"worms\" // <2>\n [\"Falcon\"] { // <3>\n \"insects\"\n \"amphibians\"\n }\n [\"Barn owl\"] { // <4>\n \"fish\"\n }\n}\n----\n<1> Explicitly amending _by index_ replaces the element at that index.\n<2> Without explicit indices, Pkl can't know which element to overwrite, so, instead, it _adds_ an element to the object you're amending.\n<3> When you write \"new\" entries (using a key that does not occur in the object you're amending), Pkl also _adds_ them.\n<4> When you write an entry using a key that exists, this notation amends its value.\n\nPkl can't know which of the `favoriteFoods` to overwrite only by their _value_.\nWhen you want to _replace_ an element, you have to explicitly amend the element at a specific index.\nThis is why a \"plain\" element in an amends expression is _added_ to the object being amended.\nResult:\n\n[source,{pkl}]\n----\nfavoriteFoods {\n [\"Barn owl\"] {\n \"mice\"\n }\n \"red berries\"\n \"blue berries\"\n}\nadultBirdFoods {\n [\"Barn owl\"] {\n \"mice\"\n \"fish\"\n }\n \"red berries\"\n \"pebbles\"\n [\"Falcon\"] {\n \"insects\"\n \"amphibians\"\n }\n \"worms\"\n}\n----\n\n\n=== Modules\n\nA `.pkl` file describes a _module_.\nModules are objects that can be referred to from other modules.\nGoing back to the example above, you can write `pigeon` as a separate module.\n\n[source,{pkl}]\n.pigeon.pkl\n----\nname = \"Common wood pigeon\"\ndiet = \"Seeds\"\ntaxonomy {\n kingdom = \"Animalia\"\n clade = \"Dinosauria\"\n species = \"Columba palumbus\"\n}\n----\n\nYou can `import` this module and express `parrot` like you did before.\n\n[source,{pkl}]\n.parrot.pkl\n----\nimport \"pigeon.pkl\" // <1>\n\nparrot = (pigeon) {\n name = \"Great green macaw\"\n diet = \"Berries\"\n taxonomy {\n species = \"Ara ambiguus\"\n }\n}\n----\n<1> Importing `pigeon.pkl` creates the object `pigeon`, so you can refer to `pigeon` in this code, like you did before.\n\nIf you run Pkl on both, you will see that it works.\nLooking at the result, however, you see a (possibly) unexpected difference.\n\n[source,{pkl}]\n----\n$ pkl eval /Users/me/tutorial/pigeon.pkl\nname = \"Common wood pigeon\"\ndiet = \"Seeds\"\ntaxonomy {\n kingdom = \"Animalia\"\n clade = \"Dinosauria\"\n species = \"Columba palumbus\"\n}\n\n$ pkl eval /Users/me/tutorial/parrot.pkl\nparrot {\n name = \"Great green macaw\"\n diet = \"Berries\"\n taxonomy {\n kingdom = \"Animalia\"\n clade = \"Dinosauria\"\n species = \"Ara ambiguus\"\n }\n}\n----\n\nThe object `pigeon` is \"spread\" in the top-level, while `parrot` is a nested and named object.\nThis is because writing `parrot {...}` defines an object property _in_ the \"current\" module.\n\nIn order to say that \"this module is an object, amended from the `pigeon` module,\" you use an _amends clause_.\n\n[source,{pkl}]\n.parrot.pkl\n----\namends \"pigeon.pkl\" // <1>\n\nname = \"Great green macaw\"\n----\n<1> \"This\" module is the same as `\"pigeon.pkl\"`, except for what is in the remainder of the file.\n\n[NOTE]\n====\nAs a first intuition, think of \"amending a module\" as \"filling out a form.\"\n====\n\n== Amending templates\n\nA Pkl file can be either a _template_ or a _\"normal\" module_.\nThis terminology describes the _intended use_ of the module and doesn't imply anything about its structure.\nIn other words: just by looking at Pkl code, you can't tell whether it is a template or a \"normal\" module.\n\n[source,{pkl}]\n.AcmeCICD.pkl\n----\nmodule AcmeCICD\n\nclass Pipeline {\n name: String(nameRequiresBranchName)?\n\n hidden nameRequiresBranchName = (_) ->\n if (branchName == null)\n throw(\"Pipelines that set a 'name' must also set a 'branchName'.\")\n else true\n\n branchName: String?\n}\n\ntimeout: Int(this >= 3)\n\npipelines: Listing\n\noutput {\n renderer = new YamlRenderer {}\n}\n----\n\nRemember that amending is like filling out a form.\nThat's exactly what you're doing here; you're filling out \"work order forms\".\n\nNext, add a time-out of one minute for your job.\n\n[source,{pkl}]\n.cicd.pkl\n----\namends \"AcmeCICD.pkl\"\n\ntimeout = 1\n----\nUnfortunately, Pkl does not accept this configuration and provides a rather elaborate error message:\n[source,plain]\n----\n–– Pkl Error –– // <1>\nType constraint `this >= 3` violated. // <2>\nValue: 1 // <3>\n\n225 | timeout: Int(this >= 3)? // <4>\n ^^^^^^^^^\nat AcmeCICD#timeout (file:///Users/me/tutorial/AcmeCICD.pkl, line 8)\n\n3 | timeout = 1 // <5>\n ^\nat cicd#timeout (file:///Users/me/tutorial/cicd.pkl, line 3)\n\n90 | text = renderer.renderDocument(value) // <6>\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nat pkl.base#Module.output.text (https://github.com/apple/pkl/blob/e4d8c882d/stdlib/base.pkl#L90)\n\n----\n<1> Pkl found an error.\n<2> Which error Pkl found.\n<3> What the offending value is.\n<4> Where Pkl found its expectation (line 8 of the amended module).\n<5> Where Pkl found the offending value (line 3 of the input module).\n<6> What Pkl evaluated to discover the error.\n\nWhen Pkl prints source locations, it also prints clickable links for easy access.\nFor local files, it generates a link for your development environment (https://pkl-lang.org/main/current/pkl-cli/index.html#settings-file[configurable in `+~/.pkl/settings.pkl+`]).\nFor packages imported from elsewhere, if available, Pkl produces `https://` links to their repository.\n\nPkl complains about a _type constraint_.\nPkl's type system doesn't just protect you from providing a `String` where you expected an `Int`, it even checks which _values_ are allowed.\nIn this case, the minimum time-out is _three_ minutes.\nIf you change the value to `3`, Pkl accepts your configuration.\n\n[source, shell]\n----\n$ pkl eval cicd.pkl\ntimeout: 3\npipelines: []\n----\n\nYou can now define a pipeline.\nStart off by specifying the name of the pipeline and nothing else.\n\n[source,{pkl}]\n.cicd.pkl\n----\namends \"AcmeCICD.pkl\"\n\ntimeout = 3\npipelines {\n new { // <1>\n name = \"prb\"\n }\n}\n----\n<1> There is no pipeline object to amend. The `new` keyword gives you an object to amend.\n\nSo far, you've defined objects the same way you amended them.\nIf the name `foo` didn't occur before, `foo { ... }` _creates_ a property called `foo` and assigns to it the contents in place of the `...` (given that `...` is not valid Pkl, but an abbreviation for illustration purposes).\nIf `foo` is an existing object, this notation is an _amend expression_; resulting in a new _object_ (value), but _not_ a new (named) property.\nSince `pipelines` is a listing, you can _add_ elements by writing expressions in an amend expression.\n\nIn this case, though, there is no object to amend. Writing `myNewPipeline { ... }` defines a _property_, but listings may only include _elements_.\nThis is where you can use the keyword `new`.\n\n`new` gives you an object to amend.\nPkl derives from the context in which `new` is used and what the object to amend should look like.\nThis is called the _default value_ for the context.\nxref:03_writing_a_template.adoc[The next part] goes into detail about how Pkl does this.\n\nRunning Pkl on your new configuration produces a verbose error.\n\n[source,plain]\n.cicd.pkl\n----\n–– Pkl Error ––\nPipelines that set a 'name' must also set a 'branchName'.\n\n8 | throw(\"Pipelines that set a 'name' must also set a 'branchName'.\")\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nat AcmeCICD#Pipeline.nameRequiresBranchName. (file:///Users/me/tutorial/AcmeCICD.pkl, line 8)\n\n6 | name = \"prb\"\n ^^^^^\nat cicd#pipelines[#1].name (file:///Users/me/tutorial/cicd.pkl, line 6)\n\n90 | text = renderer.renderDocument(value)\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nat pkl.base#Module.output.text (https://github.com/apple/pkl/blob/e4d8c882d/stdlib/base.pkl#L90)\n\n----\n\nYou have hit another type constraint, like `timeout: Int(this >= 3)` before.\nIn this case, the error message consists of an English language sentence, instead of Pkl code.\nWhen constraints are complicated or very application specific, template authors can `throw` a more descriptive error message like this.\n\nThe message is quite instructive, so you can fix the error by adding a `branchName`.\n\n[source,{pkl}]\n.cicd.pkl\n----\namends \"AcmeCICD.pkl\"\n\ntimeout = 3\npipelines {\n new {\n name = \"prb\"\n branchName = \"main\"\n }\n}\n----\n\nand indeed\n\n[source,{pkl}]\n----\n$ pkl eval -f yml /Users/me/tutorial/cicd.pkl\ntimeout: 3\npipelines:\n- name: prb\n branchName: main\n----\n" }, { "path": "docs/modules/language-tutorial/pages/03_writing_a_template.adoc", "content": "= Writing a Template\ninclude::ROOT:partial$component-attributes.adoc[]\n\nIn parts xref:01_basic_config.adoc[one] and xref:02_filling_out_a_template.adoc[two], you saw that Pkl provides _validation_ of our configurations.\nIt checks syntax, types and constraints.\nAs you saw in the `AcmeCICD` example xref:02_filling_out_a_template.adoc#amending-templates[here], the template can provide informative error messages when an amending module violates a type constraint.\n\nIn this final part, you will see some of Pkl's techniques that are particularly relevant for writing a template.\n\n== Basic types\n\nPkl always checks the _syntax_ of its input.\nAs it evaluates your configuration, it also checks _types_.\nYou've seen objects, listings, and mappings already.\nThese provide ways to write structured configuration.\nBefore you can write types for them, you need to know how to write the types for the simplest (unstructured) values.\n\nThese are all Pkl's _basic_ types:\n\n[source,{pkl}]\n.pklTutorialPart3.pkl\n----\nname: String = \"Writing a Template\"\n\npart: Int = 3\n\nhasExercises: Boolean = true\n\namountLearned: Float = 13.37\n\nduration: Duration = 30.min\n\nbandwidthRequirementPerSecond: DataSize = 52.4288.mb\n----\n\nIn the above, you've explicitly annotated the code with type signatures.\nThe default output of Pkl is actually `pcf`, which is a subset of Pkl.\nSince `pcf` does not have type signatures, running Pkl on this example removes them.\n\n[source,shell]\n----\n$ pkl eval pklTutorialPart3.pkl\nname = \"Writing a Template\"\npart = 3\nhasExercises = true\namountLearned = 13.37\nduration = 30.min\nbandwidthRequirementPerSecond = 52.4288.mb\n----\n\nNote how `Duration` and `DataSize` help you prevent https://en.wikipedia.org/wiki/Mars_Climate_Orbiter[unit errors] in these common (for configuration) domains.\n\n== Typed objects, properties and amending\n\nHaving a notation for basic types, you can now write _typed objects_.\n\n[source,{pkl}]\n.simpleClass.pkl\n----\nclass Language { // <1>\n name: String\n}\n\nbestForConfig: Language = new { // <2>\n name = \"Pkl\"\n}\n----\n<1> A class definition.\n<2> A property definition, using the `Language` class.\n\n[NOTE]\n====\nAlthough not required (or enforced), it's customary to name properties starting with a lower-case letter. Class names, by that same convention, start with an upper-case letter.\n====\n\nYou can type objects with _classes_.\nIn this example, you define a class called `Language`.\nYou can now be certain that every instance of `Language` has a property `name` with type `String`.\n\nTypes and values are different things in Pkl.\nPkl does not render types in its output,footnote:[Although, some output formats can contain their own form of type annotation. This may be derived from the Pkl type. Type definitions (`class` and `typealias`) themselves are never rendered.] so when you run Pkl on this, you don't see the class _definition_ at all.\n\n[source,{pkl}]\n----\n$ pkl eval simpleClass.pkl\nbestForConfig {\n name = \"Pkl\"\n}\n\n----\n\nDid you notice that the output doesn't just omit the type signature, but also the `= new`?\nWe will discuss this further in the next section.\n\nWhen your configuration describes a few different parts like this, you can define one instance and amend it for every other instance.\n\nFor example:\n\n[source,{pkl}]\n.pklTutorialParts.pkl\n----\nclass TutorialPart {\n name: String\n \n part: Int\n \n hasExercises: Boolean\n \n amountLearned: Float\n \n duration: Duration\n \n bandwidthRequirementPerSecond: DataSize\n}\n\npklTutorialPart1: TutorialPart = new {\n name = \"Basic Configuration\"\n part = 1\n hasExercises = true\n amountLearned = 13.37\n duration = 30.min\n bandwidthRequirementPerSecond = 50.mib.toUnit(\"mb\")\n}\n\npklTutorialPart2: TutorialPart = (pklTutorialPart1) {\n name = \"Filling out a Template\"\n part = 2\n}\n\npklTutorialPart3: TutorialPart = (pklTutorialPart1) {\n name = \"Writing a Template\"\n part = 3\n}\n\n----\n\nYou can read this as saying \"``pklTutorialPart2`` & `pklTutorialPart3` are exactly like `pklTutorialPart1`, except for their `name` and `part`.\"\nRunning Pkl confirms this:\n\n[source,shell]\n----\n$ pkl eval pklTutorialParts.pkl\npklTutorialPart1 {\n name = \"Basic Configuration\"\n part = 1\n hasExercises = true\n amountLearned = 13.37\n duration = 30.min\n bandwidthRequirementPerSecond = 52.4288.mb\n}\npklTutorialPart2 {\n name = \"Filling out a Template\"\n part = 2\n hasExercises = true\n amountLearned = 13.37\n duration = 30.min\n bandwidthRequirementPerSecond = 52.4288.mb\n}\npklTutorialPart3 {\n name = \"Writing a Template\"\n part = 3\n hasExercises = true\n amountLearned = 13.37\n duration = 30.min\n bandwidthRequirementPerSecond = 52.4288.mb\n}\n\n----\n\nSadly, `pklTutorialParts.pkl` is a _rewrite_ of `pklTutorialPart3.pkl`.\nIt creates a separate `class TutorialPart` and instantiates three properties with it (`pklTutorialPart1`, `pklTutorialPart2` and `pklTutorialPart3`).\nIn doing so, it implicitly moves everything \"down\" one level (`pklTutorialPart3` is now a property in the module `pklTutorialParts`, whereas above, in `pklTutorialPart3.pkl` it was its own module).\nThis is not very DRY.\nAs a matter of fact, you don't need this rewrite.\n\nAny `.pkl` file defines a _module_ in Pkl.\nAny module is represented by a _module class_, which is an actual Pkl `class`.\nA module is not quite the same as any other class, because Pkl never renders class definitions on the output.\nHowever, when you ran Pkl on `pklTutorialPart3.pkl`, it _did_ produce an output.\nThis is because a module also defines an _instance_ of the module class.\n\nThe values given to properties in a module (or in any \"normal\" class) are called _default values_.\nWhen you instantiate a class, all the properties for which you _don't_ provide a value are populated from the class' default values.\n\nIn our examples of tutorial parts, only the `name` and `part` varied across instances.\nYou can express this by adding default values to the (module) class definition.\nInstead of starting from a particular tutorial part, you can define the module `tutorialPart` as follows:\n\n[source,{pkl}]\n.TutorialPart.pkl\n----\nname: String // <1>\n\npart: Int // <1>\n\nhasExercises: Boolean = true // <2>\n\namountLearned: Float = 13.37 // <2>\n\nduration: Duration = 30.min // <2>\n\nbandwidthRequirementPerSecond: DataSize = 52.4288.mb // <2>\n----\n<1> No default value given.\n<2> Default value given.\n\nRunning this through Pkl gives an error, or course, because of the missing values:\n\n[source, shell]\n----\n$ pkl eval TutorialPart.pkl\n–– Pkl Error ––\nTried to read property `name` but its value is undefined.\n\n1 | name: String\n ^^^^\n...\n----\n\nAn individual part now only has to fill in the missing fields, so you can change `pklTutorialPart3.pkl` to amend this:\n\n[source,{pkl}]\n.pklTutorialPart3.pkl\n----\namends \"TutorialPart.pkl\"\n\nname = \"Writing a Template\"\n\npart = 3\n----\n\nThis results in\n\n[source, shell]\n----\n$ pkl eval pklTutorialPart3.pkl\nname = \"Writing a Template\"\npart = 3\nhasExercises = true\namountLearned = 13.37\nduration = 30.min\nbandwidthRequirementPerSecond = 52.4288.mb\n\n----\n\nThis now behaves exactly like our `pklTutorialPart3: TutorialPart = (pklTutorialPart1) {...` before.\n`pklTutorialPart3` is now defined as the value we get by amending `tutorialPart` and giving it a `name` and a `part`.\n\n[IMPORTANT]\n====\nAmending anything _never changes its type_.\nWhen we amend an object of type `Foo`, the result will always be precisely of type `Foo`.\nBy \"precisely\" we mean, that amending an object also can't \"turn it into\" an instance of a sub-class of the class of the object being amended.\n====\n\n== A new template\n\nNow that you know about types, you can start writing your first template.\nSo far, you've written configurations with Pkl, either without a template, or using the `AcmeCICD` template from xref:02_filling_out_a_template.adoc#amending-templates[Amending templates].\nIt is often easiest to first write a (typical) configuration for which you want to create a template.\nSuppose you want to define what a live workshop for this tutorial looks like.\nConsider this example:\n\n[source,{pkl}]\n.workshop2024.pkl\n----\ntitle = \"Pkl: Configure your Systems in New Ways\"\ninteractive = true\nseats = 100\noccupancy = 0.85\nduration = 1.5.h\n`abstract` = \"\"\"\n With more systems to configure, the software industry is drowning in repetitive and brittle configuration files.\n YAML and other configuration formats have been turned into programming languages against their will.\n Unsurprisingly, they don’t live up to the task.\n Pkl puts you back in control.\n \"\"\"\n\nevent {\n name = \"Migrating Birds between hemispheres\"\n year = 2024\n}\n\ninstructors {\n \"Kate Sparrow\"\n \"Jerome Owl\"\n}\n\nsessions {\n new {\n date = \"2/1/2024\"\n time = 30.min\n }\n new {\n date = \"2/1/2024\"\n time = 30.min\n }\n}\n\nassistants {\n [\"kevin\"] = \"Kevin Parrot\"\n [\"betty\"] = \"Betty Harrier\"\n}\n\nagenda {\n [\"beginners\"] {\n name = \"Basic Configuration\"\n part = 1\n duration = 45.min\n }\n [\"intermediates\"] {\n name = \"Filling out a Template\"\n part = 2\n duration = 45.min\n }\n [\"experts\"] {\n name = \"Writing a Template\"\n part = 3\n duration = 45.min\n }\n}\n----\n\nCall your new template `Workshop.pkl`.\nAlthough not required, it's good practice to always name your template with a `module`-clause.\nDefining the first few properties are like you saw in the previous section:\n\n[source,{pkl}]\n----\nmodule Workshop\n\ntitle: String\n\ninteractive: Boolean\n\nseats: Int\n\noccupancy: Float\n\nduration: Duration\n\n`abstract`: String\n----\n\nUnlike these first few properties, `event` is an object with multiple properties.\nTo be able to type `event`, you need a `class`.\nYou've seen before how to define this:\n\n[source,{pkl}]\n----\nclass Event {\n name: String\n\n year: Int\n}\n\nevent: Event\n----\n\nNext, `instructors` isn't an object with properties, but a list of unnamed values.\nPkl offers the `Listing` type for this:\n\n\n[source,{pkl}]\n----\ninstructors: Listing\n----\n\n`sessions` is a `Listing` of objects, so you need a `Session` class.\n[source,{pkl}]\n----\nclass Session {\n time: Duration\n\n date: String\n}\n\nsessions: Listing\n----\n\n`assistants` has a structure like an object, in that all the values are named, but the set of names is not fixed for all possible workshops (and some workshops may have more assistants than others). The Pkl type for this is a `Mapping`:\n\n[source,{pkl}]\n----\nassistants: Mapping\n----\n\nFinally, for every workshop session, there is an `agenda`, which describes which ``TutorialPart``s are covered.\nYou already defined `TutorialPart.pkl` as its own module, so you should not define a separate class, but rather `import` that module and reuse it here:\n\n[source,{pkl}]\n----\nimport \"TutorialPart.pkl\" // <1>\n\nagenda: Mapping\n----\n<1> This `import` clause brings the name `TutorialPart` into scope, which is the module class as discussed above. Note that import clauses must appear before property definitions.\n\nPutting it all together, your `Workshop.pkl` template looks like this:\n\n[source,{pkl}]\n.Workshop.pkl\n----\nmodule Workshop\n\nimport \"TutorialPart.pkl\"\n\ntitle: String\n\ninteractive: Boolean\n\nseats: Int\n\noccupancy: Float\n\nduration: Duration\n\n`abstract`: String\n\nclass Event {\n name: String\n\n year: Int\n}\n\nevent: Event\n\ninstructors: Listing\n\nclass Session {\n time: Duration\n\n date: String\n}\n\nsessions: Listing\n\nassistants: Mapping\n\nagenda: Mapping\n----\n" }, { "path": "docs/modules/language-tutorial/pages/index.adoc", "content": "= Tutorial\ninclude::ROOT:partial$component-attributes.adoc[]\n\nWelcome to the Pkl tutorial. We will get you up and running quickly!\nIf you are new to Pkl, we recommend that you follow along with the code examples.\nThis tutorial describes interactions with the xref:pkl-cli:index.adoc#repl[REPL].\nFor an even more interactive experience, follow along using a xref:main:ROOT:tools.adoc[supported editor].\n\nFor more comprehensive documentation, see xref:language-reference:index.adoc[Language Reference].\nFor ready-to-go examples with full source code, see xref:ROOT:examples.adoc[].\nFor API documentation, see xref:ROOT:standard-library.adoc[Standard Library].\n\nPick a tutorial by topic:\n\n1. xref:01_basic_config.adoc[Basic Configuration]\n2. xref:02_filling_out_a_template.adoc[Filling out a Template]\n3. xref:03_writing_a_template.adoc[Writing a Template]\n" }, { "path": "docs/modules/pkl-cli/pages/index.adoc", "content": "= CLI\ninclude::ROOT:partial$component-attributes.adoc[]\n:uri-homebrew: https://brew.sh\n:uri-mise: https://mise.jdx.dev\n:uri-winget: https://learn.microsoft.com/en-us/windows/package-manager/\n\n:uri-pkl-macos-amd64-download: {uri-sonatype-snapshot-download}&a=pkl-cli-macos-amd64&e=bin\n:uri-pkl-macos-aarch64-download: {uri-sonatype-snapshot-download}&a=pkl-cli-macos-aarch64&e=bin\n:uri-pkl-linux-amd64-download: {uri-sonatype-snapshot-download}&a=pkl-cli-linux-amd64&e=bin\n:uri-pkl-linux-aarch64-download: {uri-sonatype-snapshot-download}&a=pkl-cli-linux-aarch64&e=bin\n:uri-pkl-alpine-download: {uri-sonatype-snapshot-download}&a=pkl-cli-alpine-linux-amd64&e=bin\n:uri-pkl-windows-download: {uri-sonatype-snapshot-download}&a=pkl-cli-windows-amd64&e=exe\n:uri-pkl-java-download: {uri-sonatype-snapshot-download}&a=pkl-cli-java&e=jar\n\nifdef::is-release-version[]\n:uri-pkl-macos-amd64-download: {github-releases}/pkl-macos-amd64\n:uri-pkl-macos-aarch64-download: {github-releases}/pkl-macos-aarch64\n:uri-pkl-linux-amd64-download: {github-releases}/pkl-linux-amd64\n:uri-pkl-linux-aarch64-download: {github-releases}/pkl-linux-aarch64\n:uri-pkl-alpine-download: {github-releases}/pkl-alpine-linux-amd64\n:uri-pkl-windows-download: {github-releases}/pkl-windows-amd64.exe\n:uri-pkl-java-download: {uri-maven-repo}/org/pkl-lang/pkl-cli-java/{pkl-artifact-version}/pkl-cli-java-{pkl-artifact-version}.jar\nendif::[]\n\n:uri-pkl-stdlib-docs-settings: {uri-pkl-stdlib-docs}/settings/\n:uri-pkl-cli-main-sources: {uri-github-tree}/pkl-cli/src/main/kotlin/org/pkl/cli\n:uri-pkl-cli-CliEvaluatorOptions: {uri-pkl-cli-main-sources}/CliEvaluatorOptions.kt\n:uri-certificates: {uri-github-tree}/pkl-commons-cli/src/main/resources/org/pkl/commons/cli/commands\n:uri-ci-artifacts: https://s01.oss.sonatype.org/content/groups/public/org/pkl-lang/\n\nThe `pkl` command-line interface (CLI) evaluates Pkl modules and writes their output to the console or a file.\nFor interactive development, the CLI includes a Read-Eval-Print Loop (REPL).\n\n[[installation]]\n== Installation\n\nThe CLI comes in multiple flavors:\n\n* Native macOS executable for amd64 (tested on macOS 10.15)\n* Native Linux executable for amd64\n* Native Linux executable for aarch64\n* Native Alpine Linux executable for amd64 (cross-compiled and tested on Oracle Linux 8)\n* Native Windows executable for amd64 (tested on Windows Server 2022)\n* Java executable (tested with Java 17/21 on macOS and Oracle Linux)\n\nOn macOS, Linux, and Windows, we recommend using the native executables.\nThey are self-contained, start up instantly, and run complex Pkl code much faster than the Java executable.\n\n.What is the Difference Between the Linux and Alpine Linux Executables?\n[NOTE]\n====\nThe Linux executable is dynamically linked against _glibc_ and _libstdc{plus}{plus}_,\nwhereas, the Alpine Linux executable is statically linked against _musl libc_ and _libstdc{plus}{plus}_.\n====\n\nThe Java executable works on multiple platforms and has a smaller binary size than the native executables.\nHowever, it requires a Java 17 (or higher) runtime on the system path, and has a noticeable startup delay.\n\nAll flavors are built from the same codebase and undergo the same automated testing.\nExcept where noted otherwise, the rest of this page discusses the native executables.\n\n[[homebrew]]\n=== Homebrew\n\nOn macOS and Linux, release versions can be installed with {uri-homebrew}[Homebrew].\n\nifdef::is-release-version[]\nTo install Pkl, run:\n\n[source,shell]\n----\nbrew install pkl\n----\n\nTo update Pkl, run:\n\n[source,shell]\n----\nbrew update\nbrew upgrade pkl # or just `brew upgrade`\n----\nendif::[]\n\nifndef::is-release-version[]\nFor instructions, switch to a release version of this page.\nendif::[]\n\n[[mise]]\n=== Mise\n\nOn macOS, Linux, and Windows, release versions can be installed with {uri-mise}[Mise].\n\nifdef::is-release-version[]\nTo install Pkl, run:\n\n[source,shell]\n[subs=\"+attributes\"]\n----\n# Install and activate Pkl globally\nmise use -g pkl@{pkl-version}\n\n# Install and activate Pkl locally\nmise use pkl@{pkl-version}\n----\nendif::[]\n\nifndef::is-release-version[]\nFor instructions, switch to a release version of this page.\nendif::[]\n\n[[winget]]\n=== Windows Package Manager\n\nOn Windows, release versions can be installed with {uri-winget}[Windows Package Manager].\n\nifdef::is-release-version[]\nTo install Pkl, run:\n\n[source,shell]\n----\nwinget install Apple.Pkl\n----\n\nTo update Pkl, run:\n\n[source,shell]\n----\nwinget upgrade Apple.Pkl\n----\nendif::[]\n\nifndef::is-release-version[]\nFor instructions, switch to a release version of this page.\nendif::[]\n\n[[download]]\n=== Download\n\nDevelopment and release versions can be downloaded and installed manually.\n\n=== macOS Executable\n\nOn aarch64:\n\n[source,shell]\n[subs=\"+attributes\"]\n----\ncurl -L -o pkl '{uri-pkl-macos-aarch64-download}'\nchmod +x pkl\n./pkl --version\n----\n\nOn amd64:\n\n[source,shell]\n[subs=\"+attributes\"]\n----\ncurl -L -o pkl '{uri-pkl-macos-amd64-download}'\nchmod +x pkl\n./pkl --version\n----\n\nThis should print something similar to:\n\n[source]\n[subs=\"+attributes\"]\n----\nPkl {pkl-version} (macOS, native)\n----\n\n[[linux-executable]]\n=== Linux Executable\n\nThe Linux executable is dynamically linked against _glibc_ and _libstdc{plus}{plus}_ for the amd64 and aarch64 architectures.\nFor a statically linked executable, see <>.\n\nOn aarch64:\n\n[source,shell]\n[subs=\"+attributes\"]\n----\ncurl -L -o pkl '{uri-pkl-linux-aarch64-download}'\nchmod +x pkl\n./pkl --version\n----\n\nOn amd64:\n\n[source,shell]\n[subs=\"+attributes\"]\n----\ncurl -L -o pkl '{uri-pkl-linux-amd64-download}'\nchmod +x pkl\n./pkl --version\n----\n\nThis should print something similar to:\n\n[source]\n[subs=\"+attributes\"]\n----\nPkl {pkl-version} (Linux, native)\n----\n\n[[alpine-linux-executable]]\n=== Alpine Linux Executable\n\nThe Alpine Linux executable is statically linked against _musl libc_ and _libstdc{plus}{plus}_.\nFor a dynamically linked executable, see <>.\n\n[source,shell]\n[subs=\"+attributes\"]\n----\ncurl -L -o pkl '{uri-pkl-alpine-download}'\nchmod +x pkl\n./pkl --version\n----\n\nThis should print something similar to:\n\n[source]\n[subs=\"+attributes\"]\n----\nPkl {pkl-version} (Linux, native)\n----\n\nNOTE: We currently do not support the aarch64 architecture for Alpine Linux.\n\n[[windows-executable]]\n=== Windows Executable\n\n[source,PowerShell]\n[subs=\"+attributes\"]\n----\nInvoke-WebRequest '{uri-pkl-windows-download}' -OutFile pkl.exe\n.\\pkl --version\n----\n\nThis should print something similar to:\n\n[source]\n[subs=\"+attributes\"]\n----\nPkl {pkl-version} (Windows 10.0, native)\n----\n\nNOTE: We currently do not support the aarch64 architecture for Windows.\n\n[[java-executable]]\n=== Java Executable\n\nThe Java executable is a jar that can be executed directly on macOS, Linux, and Windows.\n\nIt requires `java` to be installed, and available on `$PATH`.\n\n[tabs]\n====\nmacOS/Linux::\n+\n[source,shell]\n[subs=\"+attributes\"]\n----\ncurl -L -o jpkl '{uri-pkl-java-download}'\nchmod +x jpkl\n./jpkl --version\n----\n\nWindows::\n+\n[source,PowerShell]\n[subs=\"+attributes\"]\n----\nInvoke-WebRequest '{uri-pkl-java-download}' -OutFile jpkl.bat\n.\\jpkl --version\n----\n====\n\nThis should print something similar to:\n\n[source,shell]\n[subs=\"+attributes\"]\n----\nPkl {pkl-version} (macOS 14.2, Java 17.0.10)\n----\n\nNOTE: The Java executable is named `jpkl`.\n\n[[usage]]\n== Usage\n\n*Synopsis:* `pkl [] []`\n\nFor a brief description of available options, run `pkl -h`.\n\nNOTE: The Java executable is named `jpkl`.\n\n[[command-eval]]\n=== `pkl eval`\n\n*Synopsis:* `pkl eval [] []`\n\nEvaluate the given Pkl `` and produce their rendering results.\n\n::\nThe absolute or relative URIs of the modules to evaluate.\nRelative URIs are resolved against the working directory.\n\n==== Options\n\n[[format]]\n.-f, --format\n[%collapsible]\n====\nDefault: (none) +\nExample: `yaml` +\nThe output format to generate.\nThe default output renderer for a module supports the following formats:\n\n* `json`\n* `jsonnet`\n* `pcf`\n* `plist`\n* `properties`\n* `textproto`\n* `xml`\n* `yaml`\n\nIf no format is set, the default renderer chooses `pcf`.\n====\n\n[[output-path]]\n.-o, --output-path\n[%collapsible]\n====\nDefault: (none) +\nExample: \"config.yaml\" +\nThe file path where the output file is placed.\nRelative paths are resolved against the project directory.\n\n// suppress inspection \"AsciiDocLinkResolve\"\nThis option is mutually exclusive with link:#multiple-file-output-path[`--multiple-file-output-path`].\nIf neither option is set, each module's `output.text` is written to standard output.\n\nIf multiple source modules are given, placeholders can be used to map them to different output files.\nThe following placeholders are supported:\n\n`%\\{moduleDir}`:::\nThe directory path of the module, relative to the working directory.\nOnly available when evaluating file-based modules.\n\n`%\\{moduleName}`:::\nThe simple module name as inferred from the module URI.\nFor hierarchical URIs such as `+file:///foo/bar/baz.pkl+`, this is the last path segment without file extension.\n\n`%\\{outputFormat}`:::\nThe requested output format.\nOnly available if `--format` is set.\n\nIf multiple source modules are mapped to the same output file, their outputs are concatenated.\nBy default, module outputs are separated with `---`, as in a YAML stream.\n// suppress inspection \"AsciiDocLinkResolve\"\nThe separator can be customized using the link:#module-output-separator[`--module-output-separator`] option.\n====\n\n[[module-output-separator]]\n.--module-output-separator\n[%collapsible]\n====\nDefault: `---` (as in a YAML stream) +\nThe separator to use when multiple module outputs are written to the same file, or to standard output.\n====\n\n[[multiple-file-output-path]]\n.-m, --multiple-file-output-path\n[%collapsible]\n====\nDefault: (none) +\nExample: \"output/\" +\nThe directory where a module's output files are placed.\n\nSetting this option causes Pkl to evaluate a module's `output.files` property\nand write the files specified therein.\nWithin `output.files`, a key determines a file's path relative to `--multiple-file-output-path`,\nand a value determines the file's contents.\n\n// suppress inspection \"AsciiDocLinkResolve\"\nThis option cannot be used together with any of the following:\n\n* xref:output-path[`--output-path`]\n* xref:expression[`--expression`]\n\n// suppress inspection \"AsciiDocLinkResolve\"\nThis option supports the same placeholders as link:#output-path[`--output-path`].\n\nExamples:\n\n[source,shell]\n----\n# Write files to `output/`\npkl eval -m output/ myFiles.pkl\n\n# Write files to the current working directory\npkl eval -m . myFiles.pkl\n\n# Write foo.pkl's files to the `foo` directory, and bar.pkl's files\n# to the `bar` directory\npkl eval -m \"%{moduleName}\" foo.pkl bar.pkl\n----\n\nFor additional details, see xref:language-reference:index.adoc#multiple-file-output[Multiple File Output]\nin the language reference.\n====\n\n[[expression]]\n.-x, --expression\n[%collapsible]\n====\nDefault: (none) +\nThe expression to be evaluated within the module.\n\nThis option causes Pkl to evaluate the provided expression instead of the module's `output.text` or `output.files` properties.\nThe resulting value is then stringified, and written to either standard out, or the designated output file.\n\nFor example, consider the following Pkl module:\n\n.pigeon.pkl\n[source%tested,{pkl}]\n----\nmetadata {\n species = \"Pigeon\"\n}\n----\n\nThe following command prints `Pigeon` to the console:\n\n[source,shell]\n----\npkl eval -x metadata.species pigeon.pkl\n# => Pigeon\n----\n\nSetting an `--expression` flag can be thought of as substituting the expression in place of a module's `output.text` property.\nRunning the previous command is conceptually the same as if the below module were evaluated without the `--expression` flag:\n\n[source,pkl]\n----\nmetadata {\n species = \"Pigeon\"\n}\n\noutput {\n text = metadata.species.toString()\n}\n----\n====\n\n[[power-assertions-eval]]\n.--power-assertions, --no-power-assertions\n[%collapsible]\n====\nDefault: enabled +\nEnable or disable power assertions for detailed assertion failure messages.\nWhen enabled, type constraint failures will show intermediate values in the assertion expression.\nUse `--no-power-assertions` to disable this feature if you prefer simpler output or better performance.\n====\n\nThis command also takes <>.\n\n[[command-server]]\n=== `pkl server`\n\n*Synopsis:* `pkl server`\n\nRun as a server that communicates over standard input/output.\n\nThis option is used for embedding Pkl in an external client, such as xref:swift:ROOT:index.adoc[pkl-swift] or xref:go:ROOT:index.adoc[pkl-go].\n\n[[command-test]]\n=== `pkl test`\n\n*Synopsis:* `pkl test [] []`\n\nEvaluate the given `` as _tests_, producing a test report and appropriate exit code.\n\nRenderers defined in test files will be ignored by the `test` command.\n\nTests that result in writing `pkl-expected.pcf` files are considered failing tests.\nIf these are the only failures, the command exits with exit code 10.\nOtherwise, failures result in exit code 1.\n\n::\nThe absolute or relative URIs of the modules to test.\nThe module must extend `pkl:test`.\nRelative URIs are resolved against the working directory.\n\n==== Options\n\n[[junit-reports]]\n.--junit-reports\n[%collapsible]\n====\nDefault: (none) +\nExample: `./build/test-results` +\nDirectory where to store JUnit reports.\n\nBy default, one file will be created for each test module. This behavior can be changed with `--junit-aggregate-reports`, which will instead create a single JUnit report file with all test results.\n\nNo JUnit reports will be generated if this option is not present.\n====\n\n[[junit-aggregate-reports]]\n.--junit-aggregate-reports\n[%collapsible]\n====\nAggregate JUnit reports into a single file.\n\nBy default it will be `pkl-tests.xml` but you can override it using `--junit-aggregate-suite-name` flag.\n====\n\n[[junit-aggregate-suite-name]]\n.--junit-aggregate-suite-name\n[%collapsible]\n====\nDefault: (none) +\nExample: `my-tests` +\nThe name of the root JUnit test suite.\n\nUsed in combination with `--junit-aggregate-reports` flag.\n====\n\n[[overwrite]]\n.--overwrite\n[%collapsible]\n====\nForce generation of expected examples. +\nThe old expected files will be deleted if present.\n====\n\n[[power-assertions-test]]\n.--power-assertions, --no-power-assertions\n[%collapsible]\n====\nDefault: enabled +\nEnable or disable power assertions for detailed assertion failure messages.\nWhen enabled, test failures will show intermediate values in the assertion expression, making it easier to understand why a test failed.\nUse `--no-power-assertions` to disable this feature if you prefer simpler output.\n====\n\nThis command also takes <>.\n\n[[command-run]]\n=== `pkl run`\n\n*Synopsis:* `pkl run [] [] []`\n\nEvaluate a <> defined by ``.\n\n::\nThe absolute or relative URIs of the command module to run.\nThe module must extend `pkl:Command`.\nRelative URIs are resolved against the working directory.\n\n::\nAdditional CLI options and arguments defined by ``.\n\nThis command also takes <>.\n\n[[command-repl]]\n=== `pkl repl`\n\n*Synopsis:* `pkl repl []`\n\nStart a REPL session.\n\nThis command takes <>.\n\n[[command-project-package]]\n=== `pkl project package`\n\n*Synopsis:* `pkl project package `\n\nThis command prepares a project to be published as a package.\nGiven a project directory, it creates the following artifacts:\n\n* `@` - the package metadata file\n* `@.sha256` - the dependency metadata file's SHA-256 checksum\n* `@.zip` - the package archive\n* `@.zip.sha256` - the package archive's SHA-256 checksum\n\nThese artifacts are expected to be published to an HTTPS server, such that the metadata and zip files can be fetched at their expected locations.\n\nThe package ZIP should be available at the `packageZipUrl` location specified in the `PklProject` file\nThe package metadata should be available at the package URI's derived HTTPS URL.\nFor example, given package `package://example.com/mypackage@1.0.0`, the metadata file should be published to `+https://example.com/mypackage@1.0.0+`.\n\nDuring packaging, this command runs these additional steps:\n\n1. Run the package's API tests, if any are defined.\n2. Validates that if the package has already been published, that the package's metadata is identical. This step can be skipped using the `--skip-publish-check` flag.\n\nExamples:\n\n[source,shell]\n----\n# Search the current working directory for a project, and package it.\npkl project package\n\n# Package all projects within the `packages/` directory to `.out`, writing each package's artifacts to its own directory.\npkl project package --output-path \".out/%{name}@%{version}/\" packages/*/\n----\n\n==== Options\n\n.--output-path\n[%collapsible]\n====\nDefault: `.out`\n\nThe directory to write artifacts to.\nAccepts the following placeholders:\n\n`%\\{name}`:: The name of the package\n`%\\{version}`:: The version of the package\n====\n\n.--skip-publish-check\n[%collapsible]\n====\nSkips checking whether a package has already been published with different contents.\n\nBy default, the packager will check whether a package at the same version has already been published.\nIf the package has been published, it validates that the package's metadata is identical to the locally generated metadata.\n====\n\n.--junit-reports\n[%collapsible]\n====\nDefault: (none) +\nExample: `./build/test-results` +\nDirectory where to store JUnit reports.\n\nNo JUnit reports will be generated if this option is not present.\n====\n\n.--junit-aggregate-reports\n[%collapsible]\n====\nAggregate JUnit reports into a single file.\n\nBy default it will be `pkl-tests.xml` but you can override it using `--junit-aggregate-suite-name` flag.\n====\n\n.--junit-aggregate-suite-name\n[%collapsible]\n====\nDefault: (none) +\nExample: `my-tests` +\nThe name of the root JUnit test suite.\n\nUsed in combination with `--junit-aggregate-reports` flag.\n====\n\n.--overwrite\n[%collapsible]\n====\nForce generation of expected examples. +\nThe old expected files will be deleted if present.\n====\n\nThis command also takes <>.\n\n[[command-project-resolve]]\n=== `pkl project resolve`\n\n*Synopsis:* `pkl project resolve `\n\nThis command takes the dependencies of a project, and writes the resolved versions a file at path `PklProject.deps.json`.\n\nIt builds a dependency list, taking the latest minor version in case of version conflicts.\nFor more details, see the xref:language-reference:index.adoc#resolving-dependencies[resolving dependencies] section of the language reference.\n\nExamples:\n[source,shell]\n----\n# Search the current working directory for a project, and resolve its dependencies.\npkl project resolve\n\n# Resolve dependencies for all projects within the `packages/` directory.\npkl project resolve packages/*/\n----\n\n==== Options\n\nThis command accepts <>.\n\n[[command-download-package]]\n=== `pkl download-package`\n\n*Synopsis*: `pkl download-package `\n\nThis command downloads the specified packages to the cache directory.\nIf the\npackage already exists in the cache directory, this command is a no-op.\n\n==== Options\n\nThis command accepts <>.\n\n[[command-analyze-imports]]\n=== `pkl analyze imports`\n\n*Synopsis*: `pkl analyze imports []`\n\nThis command builds a graph of imports declared in the provided modules.\n\nThis is a lower level command that is meant to be useful for Pkl-related tooling.\nFor example, this command feeds into the xref:pkl-gradle:index.adoc[] to determine if tasks are considered up-to-date or not.\n\nThis command produces an object with two properties, `imports` and `resolvedImports`.\n\nThe `imports` property is a mapping of a module's absolute URI, to the set of imports declared within that module.\n\nThe `resolvedImports` property is a mapping of a module's absolute URI (as stated in `imports`), to the resolved absolute URI that might be useful for fetching the module's contents.\nFor example, a xref:language-reference:index.adoc#local-dependencies[local dependency] import will have an in-language URI with scheme `projectpackage:`, and may have resolved URI with scheme `file:` (assuming that the project is file-based).\n\nExamples:\n\n[source,shell]\n----\n# Analyze the imports of a single module\npkl analyze imports myModule.pkl\n\n# Same as the previous command, but output in JSON.\npkl analyze imports -f json myModule.pkl\n\n# Analyze imports of all modules declared within src/\npkl analyze imports src/*.pkl\n----\n\n::\nThe absolute or relative URIs of the modules to analyze. Relative URIs are resolved against the working directory.\n\n==== Options\n\n.-f, --format\n[%collapsible]\n====\nSame meaning as <> in <>.\n====\n\n.-o, --output-path\n[%collapsible]\n====\nSame meaning as <> in <>.\n====\n\nThis command also takes <>.\n\n[[command-shell-completion]]\n=== `pkl shell-completion`\n\n*Synopsis*: `pkl shell-completion `\n\nGenerate shell completion script. Supported shells are: `bash`, `zsh`, `fish`.\n\n[source,shell]\n----\n# Generate shell completion script for bash\npkl shell-completion bash\n\n# Generate shell completion script for zsh\npkl shell-completion zsh\n----\n\n[[command-format]]\n=== `pkl format`\n\n*Synopsis*: `pkl format []`\n\nThis command formats or checks formatting of Pkl files. +\nExit codes:\n\n* 0: No violations found or files were updated.\n* 1: An unexpected error happened (ex.: IO error)\n* 11: Violations were found (when running without `--write`).\n\nIf the path is a directory, recursively looks for files with a `.pkl` extension, or files named `PklProject`.\n\nBy default, the input files are formatted, and written to standard out.\n\n==== Options\n\n.--grammar-version\n[%collapsible]\n====\nDefault: `2` (latest version) +\nSelect the grammar compatibility version for the formatter.\nNew versions are created for each backward incompatible grammar change.\n====\n\n.-s, --silent\n[%collapsible]\n====\nSkip writing to standard out. Mutually exclusive with `--diff-name-only`.\n====\n\n.-w, --write\n[%collapsible]\n====\nFormat files in place, overwriting them. Implies `--diff-name-only`.\n====\n\n.--diff-name-only\n[%collapsible]\n====\nWrite the path of files with formatting violations to stdout.\n====\n\n[[common-options]]\n=== Common options\n\nThe <>, <>, <>, <>, <>, <>, <>, and <> commands support the following common options:\n\ninclude::../../pkl-cli/partials/cli-common-options.adoc[]\n\nThe <>, <>, <>, <>, and <> commands also take the following options:\n\ninclude::../../pkl-cli/partials/cli-project-options.adoc[]\n\n[[root-options]]\n=== Root options\n\nThe root `pkl` command supports the following options:\n\n.-v, --version\n[%collapsible]\n====\nDisplay version information.\n====\n\n== Evaluating Modules\n\nSay we have the following module:\n\n[[config.pkl]]\n.config.pkl\n[source,{pkl}]\n----\nbird {\n species = \"Pigeon\"\n diet = \"Seeds\"\n}\nparrot = (bird) {\n species = \"Parrot\"\n diet = \"Berries\"\n}\n----\n\nTo evaluate this module and write its output to standard output, run:\n\n[source,shell]\n----\npkl eval config.pkl\n----\n\nYou should see the following output:\n\n[source,{pkl}]\n----\nbird {\n species = \"Pigeon\"\n diet = \"Seeds\"\n}\nparrot {\n species = \"Parrot\"\n diet = \"Berries\"\n}\n----\n\nTo render output as JSON, YAML, XML property list, or Java properties,\nuse `--format json`, `--format yaml`, `--format plist`, or `--format properties`, respectively.\n\nTo control the output format from within Pkl code, see xref:language-reference:index.adoc#module-output[Module Output].\n\nTo read a source module from standard input rather than a file, use `-` as a module name:\n\n[source,shell]\n----\necho mod2.pkl | pkl eval mod1.pkl - mod3.pkl\n----\n\nThis is especially useful in environments that don't support `/dev/stdin`.\n\nTo write output to a file rather than standard output, use `--output-path some/file.ext`.\n\n[[batch-evaluation]]\n=== Batch Evaluation\n\nMultiple modules can be evaluated at once:\n\n[source,shell]\n----\npkl eval config1.pkl config2.pkl config3.pkl\n----\n\nTo write module outputs to separate output files, `--output-path` supports the following placeholders:\n\n`%\\{moduleDir}`:: the directory path of the source module, relative to the working directory (only available for file based modules)\n`%\\{moduleName}`:: the last path segment of the module URI, without file extension\n`%\\{outputFormat}`:: the target format (only available if `--format` is set)\n\nThe following run produces three JSON files placed next to the given source modules:\n\n[source,shell]\n----\npkl eval --format=json --output-path=%{moduleDir}/%{moduleName}.json config1.pkl config2.pkl config3.pkl\n----\n\nIf multiple module outputs are written to the same file, or to standard output, their outputs are concatenated.\nBy default, module outputs are separated with `---`, as in a YAML stream.\nThe separator can be customized using the `--module-output-separator` option.\n\n[[cli-tools]]\n== Implementing CLI Tools\n\nCLI tools can be implemented in Pkl by modules extending the `pkl:Command` module.\nWith `pkl:Command`, you can define a script in Pkl that is executed by your shell, providing a better CLI experience.\n\nRegular evaluation requires use of xref:language-reference:index.adoc#resources[resources] like properties and evironment variables to provide parameters:\n[source,bash]\n----\n$ pkl eval script.pkl -p username=me -p password=password\n----\n\nCommands provide a native, familiar CLI experience:\n[source,bash]\n----\n$ pkl run script.pkl --username=admin --password=hunter2\n$ ./script.pkl --username=admin --password=hunter2\n----\n\nPkl commands have a few properties that distinguish them from standard module evaluation:\n\n* Users provide input to commands using familiar command line idioms, providing a better experience than deriving inputs from xref:language-reference:index.adoc#resources[resources] like external properties or environment variables.\n* Commands can dynamically import modules when they are specified as command line options.\n* Commands may write to standard output (via `output.text` or `output.bytes`) and the filesystem (via `output.files`) in the same evaluation.\n* Command file output may write to any absolute path (not only relative to the `--multiple-file-output-path` option).\n** Relative output paths are written relative to the current working directory (or `--working-dir`, if specified).\n** Paths of output file are printed to the command's standard error.\n\nIMPORTANT: Users of `pkl run` must be aware of the security implications of this behavior.\nUsing `pkl eval` prevents accidental overwrites by not allowing absolute paths, but `pkl run` does not offer this protection.\nCommands may write to any path the invoking user has permissions to modify.\n\nCommands are implemented as regular modules and declare their supported command line flags and positional arguments using a class with annotated properties.\n\n=== Defining Commands\n\nCommands are defined by creating a module that extends `pkl:Command`:\n\n[source,pkl%tested]\n.my-tool.pkl\n----\n/// This doc comment becomes part of the command's CLI help!\n/// Markdown formatting is **allowed!**\nextends \"pkl:Command\"\n\noptions: Options // <1>\n\nclass Options {\n // Define CLI flags/arguments...\n}\n\n// Regular module code...\n----\n<1> Re-declaration of the `options` property's type.\n\nLike `pkl eval`, when a command completes without an evaluation error the process exits successfully (exit code 0).\nCommands can return a failure using `throw` (exit code 1), but otherwise may not control the exit code.\n\nOther than the differences listed above, commands behave like any other Pkl module.\nFor example, there is no way to execute other programs or make arbitrary HTTP requests.\nIf additional functionality is desired, xref:language-reference:index.adoc#external-readers[external readers] may be used to extends Pkl's capabilities.\n\n=== Command Options\n\nEach property of a command's options class becomes a command line option.\nProperties with the `local`, `hidden`, `fixed`, and/or `const` modifiers are not parsed as options\nA property's doc comment, if present, becomes the corresponding option's CLI help description.\nDoc comments are interpreted as Markdown text and formatted nicely when displayed to users.\nProperties must have xref:language-reference:index.adoc#type-annotations[type annotations] to determine how they are parsed.\n\nProperties may be xref:language-reference:index.adoc#annotations[annotated] to influence how they behave:\n\n* Properties annotated with link:{uri-stdlib-Command-Flag}[`@Flag`] become CLI flags named `--` that accept a value.\n* `Boolean` properties annotated with link:{uri-stdlib-Command-BooleanFlag}[`@BooleanFlag`] become CLI flags named `--` and `--no-` that result in `true` and `false` values, respectively.\n* `Int` (and type aliases of `Int`) properties annotated with link:{uri-stdlib-Command-CountedFlag}[`@CountedFlag`] become CLI flags named `--` that produce a value equal to the number of times they are present on the command line.\n* Properties annotated with link:{uri-stdlib-Command-Argument}[`@Argument`] become positional CLI arguments and are parsed in the order they appear in the class.\n* Properties with no annotation are treated the same as `@Flag` with no further customization.\n\nFlag options may set a `shortName` property to define a single-character abbreviation (`-`).\nFlag abbreviations may be combined (e.g. `-a -b -v -v -q some-value` is equivalent to `-abvvq some-value`).\n\n[CAUTION]\n====\nFlag names and short names may not conflict with <>.\nFuture versions of Pkl may introduce additional common options and the names of these options will become forbidden for use in `pkl:Command`.\nThus, any Pkl release that adds common options may introduce breaking changes for commands.\n\nWhile unfortunate, this behavior eliminates potentially dangerous or misleading ambiguities between Pkl-defined and user-defined options.\n====\n\nA `@Flag` or `@Argument` property's type annotation determines how it is converted from the raw string value:\n\n|===\n|Type |Behavior\n\n|`String`\n|Value is used verbatim.\n\n|`Char`\n|Value is used verbatim but must be exactly one character.\n\n|`Boolean`\n|True values: `true`, `t`, `1`, `yes`, `y`, `on`\n\nFalse values: `false`, `f`, `0`, `no`, `n`, `off`\n\n|`Number`\n|Value is parsed as an `Int` if possible, otherwise parsed as `Float`.\n\n|`Float`\n|Value is parsed as a `Float`.\n\n|`Int`\n|Value is parsed as a `Int`.\n\n|`Int8`, `Int16`, `Int32`, `UInt`, `UInt8`, `UInt16`, `UInt32`\n|Value is parsed as a `Int` and must be within the type's range.\n\n|xref:language-reference:index.adoc#union-types[Union] of xref:language-reference:index.adoc#string-literal-types[string literals]\n|Value is used verbatim but must match a member of the union.\n\n|`List`, `Listing`, `Set`\n|Each occurrence of the option becomes an element of the final value.\n\n`Element` values are parsed based on the above primitive types.\n\n|`Map`, `Mapping`\n|Each occurrence of the option becomes an entry of the final value.\n\nValues are split on the first `\"=\"` character; the first part is parsed as `Key` and the second as `Value`, both based on the above primitive types.\n\n|`Pair`\n|Value is split on the first `\"=\"` character; the first part is parsed as `First` and the second as `Second`, both based on the above primitive types.\n\n|===\n\nIf a flag that accepts only a single value is provided multiple times, the last occurrence becomes the final value.\n\nOnly a single positional argument accepting multiple values is permitted per command.\n\nA property with a xref:language-reference:index.adoc#nullable-types[nullable type] is optional and, if not specified on the command line, will have value `null`.\nProperties with default values are also optional.\nType constraints are evaluated when the command is executed, so additional restrictions on option values are enforced at runtime.\n\n==== Custom Option Conversion and Aggregation\n\nA property may be annotated with any type if its `@Flag` or `@Argument` annotation sets the `convert` or `transformAll` properties.\nThe `convert` property is a xref:language-reference:index.adoc#anonymous-functions[function] that overrides how _each_ raw option value is interpreted.\nThe `transformAll` property is a function that overrides how _all_ parsed option values become the final property value.\n\nThe `convert` and `transformAll` functions may return an pkldoc:Import[pkl:Command] value that is replaced during option parsing with the actual value of the module specified by its `uri` property.\nIf `glob` is `true`, the replacement value is a `Mapping`; its keys are the _absolute_ URIs of the matched modules and its values are the actual module values.\nWhen specifying glob import options on the command line, it is often necessary to quote the value to avoid it being interpreted by the shell.\nIf the return value of `convert` or `transformAll` is a `List`, `Set`, `Map`, or `Pair`, each contained value (elements and entry keys/values) that are `Import` values are also replaced.\n\n[IMPORTANT]\n====\nIf an option has type `Mapping` and should accept a single glob pattern value, the option's annotation must also set `multiple = false` to override the default behavior of `Mapping` options accepting multiple values.\nExample:\n[source%parsed,{pkl}]\n----\n@Flag {\n convert = (it) -> new Import { uri = it; glob = true }\n multiple = false\n}\nbirds: Mapping\n----\n\nIf multiple glob patterns values should be accepted and merged, `transformAll` may be used to merge every glob-imported `Mapping`:\n[source%parsed,{pkl}]\n----\n@Flag {\n convert = (it) -> new Import { uri = it; glob = true }\n transformAll =\n (values) -> values.fold(new Mapping {}, (result, element) ->\n (result) { ...element }\n )\n}\nbirds: Mapping\n----\n====\n\n=== Subcommands\n\nLike many other command line libraries, `pkl:Command` allows building commands into a hierarchy with a root command and subcommands:\n\n[source,pkl%tested]\n.my-tool.pkl\n----\nextends \"pkl:Command\"\n\ncommand {\n subcommands {\n import(\"subcommand1.pkl\")\n import(\"subcommand2.pkl\")\n for (_, subcommand in import*(\"./subcommands/*.pkl\")) {\n subcommand\n }\n }\n}\n----\n\n[source,pkl%tested]\n.subcommand1.pkl\n----\nextends \"pkl:Command\"\n\nimport \"my-tool.pkl\"\n\nparent: `my-tool` // <1>\n\n// Regular module code...\n----\n<1> Optional; asserts that this is a subcommand of `my-tool` and simplifies accessing properties and options of the parent command\n\nEach element of `subcommands` must have a unique value for `command.name`.\n\n=== Testing Commands\n\nCommand modules are normal Pkl modules, so they may be imported and used like any other module.\nThis is particularly helpful when testing commands, as the command's `options` and `parent` properties can be populated by test code.\n\nTesting the above command and subcommand might look like this:\n\n[source,pkl%tested]\n----\namends \"pkl:test\"\n\nimport \"my-tool.pkl\"\nimport \"subcommand1.pkl\"\n\nexamples {\n [\"Test my-tool\"] {\n (`my-tool`) {\n options {\n // Set my-tool options here...\n }\n }.output.text\n }\n [\"Test subcommand1\"] {\n (subcommand1) {\n parent { // this amends `my-tool`\n options {\n // Set my-tool options here...\n }\n }\n options {\n // Set subcommand options here...\n }\n }.output.text\n }\n}\n----\n\n[[commands-as-standalone-scripts]]\n=== Commands as standalone scripts\n\nOn *nix platforms, Pkl commands can be configured to run as standalone tools that can be invoked without the `pkl run` command.\nTo achieve this, the command file must be marked executable (i.e. `chmod +x my-tool.pkl`) and a link:https://en.wikipedia.org/wiki/Shebang_(Unix)[shebang comment] must be added on the first line of the file:\n\n[source,pkl%parsed]\n----\n#!/usr/bin/env -S pkl run\n----\n\nNOTE: The `-S` flag for `env` is required on Linux systems due to a limitation of shebang handling in the Linux kernel.\nWhile not required on other *nix platforms like macOS, but it should be included for compatibility.\n\n==== Shell Completion\n\nLike with Pkl's own CLI, <> can be generated for standalone scripts.\n\n[source,shell]\n----\n# Generate shell completion script for bash\n./my-tool.pkl shell-completion bash\n\n# Generate shell completion script for zsh\n./my-tool.pkl shell-completion zsh\n----\n\n==== Customizing Completion Candidates\n\n`@Flag` and `@Argument` annotations may specify the `completionCandidates` to improve generated shell completions.\n\nValid values include:\n\n* A `Listing` of literal string values to offer for completion.\n* The literal string `\"path\"`, which offers local file paths for completion.\n\nOptions with a string literal union type implicitly offer the members of the union as completion candidates.\n\n=== Flag name ambiguities\n\nIt is possible for commands to define flags with names or short names that collide with Pkl's own command line options.\nTo avoid ambiguity in parsing these options, all flags for Pkl itself (e.g. `--root-dir`) must be placed before the root command module's URI.\nCommand authors are encouraged to avoid overlapping with Pkl's built-in flags, but this may not always be feasible, especially for single-character abbreviated names.\n\nThis imposes a limitation around <> that prevents users from customizing Pkl evaluator options when they are invoked.\nThere are two recommended workarounds for this limitation:\n\n* Use a `PklProject` to define evaluator settings instead of doing so on the command line.\n* If the command line must be used, switch to invoking via `pkl run [] []`.\n\n[[repl]]\n== Working with the REPL\n\nTo start a REPL session, run `pkl repl`:\n\n[source,shell]\n[subs=\"+attributes\"]\n----\n$ pkl repl\nWelcome to Pkl {pkl-version}.\nType an expression to have it evaluated.\nType :help or :examples for more information.\n\npkl>\n----\n\n=== Loading Modules\n\nTo load <> into the REPL, run:\n\n[source,shell]\n----\npkl> :load config.pkl\n----\n\nTo evaluate the `bird.species` property, run:\n\n[source,shell]\n----\npkl> bird.species\n\"Pigeon\"\n----\n\nTo evaluate the entire module, force-evaluate `this`:\n\n[source,shell]\n----\npkl> :force this\n----\n\n=== REPL Commands\n\nCommands start with `:` and can be tab-completed:\n\n[source,shell]\n[subs=\"+attributes,+macros\"]\n----\npkl> :{empty}kbd:[Tab]\nclear examples force help load quit reset\npkl> :q{empty}kbd:[Tab]\npkl> :quit{empty}kbd:[Return]\n$\n----\n\nCommands can be abbreviated with any unique name prefix:\n\n[source,shell]\n[subs=\"+attributes,+macros\"]\n----\npkl> :q{empty}kbd:[Return]\n$\n----\n\nTo learn more about each command, run the `:help` command.\n\nSome commands support further command-specific tab completion.\nFor example, the `:load` command supports completing file paths.\n\nWith commands out of the way, let's move on to evaluating code.\n\n=== Evaluating Code\n\nTo evaluate an expression, type the expression and hit kbd:[Return].\n\n[source,shell]\n----\npkl> 2 + 4\n6\n----\n\nApart from expressions, the REPL also accepts property, function, and class definitions.\n(See the xref:language-reference:index.adoc[Language Reference] to learn more about these language concepts.)\n\n[source,shell]\n----\npkl> hello = \"Hello, World!\"\npkl> hello\n\"Hello, World!\"\npkl> function double(n) = 2 * n\npkl> double(5)\n10\npkl> class Bird { species: String }\npkl> new Bird { species = \"Pigeon\" }\n{\n name = ?\n}\n----\n\nTop-level expressions are only supported in the REPL.\nIn a regular module, every expression is contained in a definition, and only definitions exist at the top level.\n\n=== Redefining Members\n\nExisting members can be redefined:\n\n[source,shell]\n----\npkl> species = \"Pigeon\"\npkl> species\n\"Pigeon\"\npkl> species = \"Barn\"\npkl> species\n\"Barn\"\npkl> species + \" Owl\"\npkl> species\n\"Barn Owl\"\n----\n\nDue to Pkl's late binding semantics, redefining a member affects dependent members:\n\n[source,shell]\n----\npkl> name = \"Barn\"\npkl> species = \"\\(name) Owl\"\npkl> species\n\"Barn Owl\"\npkl> name = \"Elf\"\npkl> species\n\"Elf Owl\"\n----\n\nRedefining members is only supported in the REPL. Under the hood,\nit works as follows:\n\n* The REPL environment is represented as a synthetic Pkl module.\n* When a new member is defined, it is added to the current REPL module.\n* When an existing member is redefined, it is added to a new REPL module that xref:language-reference:index.adoc#module-amend[amends] the previous REPL module.\n\n[[settings-file]]\n== Settings File\n\nThe Pkl settings file allows to customize the CLI experience.\n\nA settings file is a Pkl module amending the `pkl.settings` standard library module.\nIts default location is `~/.pkl/settings.pkl`.\nTo use a different settings file, set the `--settings` command line option, for example `--settings mysettings.pkl`.\nTo enforce default settings, use `--settings pkl:settings`.\nThe settings file is also honored by (and configurable through) the Gradle plugin and `CliEvaluator` API.\n\nHere is a typical settings file:\n\n.~/.pkl/settings.pkl\n[source%parsed,{pkl}]\n----\namends \"pkl:settings\" // <1>\n\neditor = Idea // <2>\n----\n<1> A settings file should amend the `pkl.settings` standard library module.\n<2> Configures IntelliJ IDEA as the preferred editor.\nOther supported values are `System`, `GoLand`, `TextMate`, `Sublime`, `Atom`, and `VsCode`.\n\nWith the above settings file in place, kbd:[Cmd]+Double-clicking a source code link in a stack trace opens the corresponding file in IntelliJ IDEA at the correct location.\n\nTo learn more about available settings, see link:{uri-pkl-stdlib-docs-settings}[pkl.settings].\n\n[[ca-certs]]\n== CA Certificates\n\nWhen making TLS requests, Pkl comes with its own set of {uri-certificates}[CA certificates].\nThese certificates can be overridden via either of the two options:\n\n- Set them directly via the CLI option `--ca-certificates `.\n- Add them to a directory at path `~/.pkl/cacerts/`.\n\nBoth these options will *replace* the default CA certificates bundled with Pkl. +\nThe CLI option takes precedence over the certificates in `~/.pkl/cacerts/`. +\nCertificates need to be X.509 certificates in PEM format.\n\n[[http-proxy]]\n== HTTP Proxying\n\nWhen making HTTP(s) requests, Pkl can possibly make use of an HTTP proxy.\n\nThere are two values that determine proxy settings; the proxy address and list of noproxy rules.\nWhen determining proxy settings, Pkl will look at the following locations, in order of precedence (lowest to highest):\n\n1. OS settings (on macOS, Windows, and GNOME environments)\n2. <>\n3. xref:language-reference:index.adoc#projects[PklProject file]\n4. `--http-proxy` and `--http-no-proxy` CLI flags\n\n[NOTE]\n====\nThe proxy and noproxy values are individually set.\nFor example, using the `--http-no-proxy` flag but not the `--http-proxy` flag will cause Pkl to look at the PklProject file, then the settings file, then system settings for the proxy address.\n\nOne exception to this rule is that setting a proxy address will cause Pkl to ignore any noproxy values set at the OS level.\n====\n\nPkl only supports HTTP proxies, so neither HTTPS nor SOCKS proxies are supported.\nPkl does not support authentication with a proxy.\n\nWhen specifying a proxy address, it must have scheme `http`, and may not contain anything other than a host and port.\n\n=== Proxy exclusions\n\nPkl can be configured to bypass the proxy for specific requests via a proxy exclusion rule (i.e. the `--http-no-proxy` flag).\nIt may be provided either as a hostname, an IP address, or an IP range via https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation[CIDR notation].\nWhen determining whether a proxy should be excluded, hostnames do not get resolved to their IP address.\nFor example, a request to `localhost` will not match `--http-no-proxy=127.0.0.1`.\n\nFor individual hosts (not CIDRs), ports can be specified.\nWhen no port is specified for a given host, connections to all ports bypass the proxy.\n\nA hostname will match all of its subdomains.\nFor example, `example.com` will match `foo.example.com`, and `bar.foo.example.com`, but not `fooexample.com`.\n\nThe value `*` is a special wildcard that matches all hosts.\n\nA port can optionally be specified. If omitted, it matches all ports.\n\nNOTE: Pkl follows the rules described in https://about.gitlab.com/blog/2021/01/27/we-need-to-talk-no-proxy/#standardizing-no_proxy[Standardizing `no_proxy`], except it does not look at environment variables.\n" }, { "path": "docs/modules/pkl-cli/partials/cli-common-options.adoc", "content": "[[allowed-modules]]\n.--allowed-modules\n[%collapsible]\n====\nDefault: `pkl:,file:,modulepath:,https:,repl:,package:,projectpackage:` +\nComma-separated list of URI patterns that determine which modules can be loaded and evaluated.\nPatterns are matched against the beginning of module URIs.\n(File paths have been converted to `file:` URLs at this stage.)\nAt least one pattern needs to match for a module to be loadable.\n====\n\n[[allowed-resources]]\n.--allowed-resources\n[%collapsible]\n====\nDefault: `env:,prop:,package:,projectpackage:` +\nComma-separated list of URI patterns that determine which external resources can be read.\nPatterns are matched against the beginning of resource URIs.\nAt least one pattern needs to match for a resource to be readable.\n====\n\n[[color]]\n.--color\n[%collapsible]\n====\nDefault: `auto` +\nWhen to format messages with ANSI color codes.\nPossible values:\n\n- `\"never\"`: Never format\n- `\"auto\"`: Format if `stdin`, `stdout`, or `stderr` are connected to a console.\n- `\"always\"`: Always format\n====\n\n[[cache-dir]]\n.--cache-dir\n[%collapsible]\n====\nDefault: `~/.pkl/cache` +\nExample: `/path/to/module/cache/` +\nThe cache directory for storing packages.\n====\n\n.--no-cache\n[%collapsible]\n====\nDisable caching of packages.\n====\n\n.-e, --env-var\n[%collapsible]\n====\nDefault: OS environment variables for the current process +\nExample: `MY_VAR=myValue` +\nSets an environment variable that can be read by Pkl code with `read(\"env:\")`.\nRepeat this option to set multiple environment variables.\n====\n\n.-h, --help\n[%collapsible]\n====\nDisplay help information.\n====\n\n.--module-path\n[%collapsible]\n====\nDefault: (empty) +\nExample: `dir1:zip1.zip:jar1.jar` +\nDirectories, ZIP archives, or JAR archives to search when resolving `modulepath:` URIs.\nPaths are separated by the platform-specific path separator (`:` on *nix, `;` on Windows).\nRelative paths are resolved against the working directory.\n====\n\n.-p, --property\n[%collapsible]\n====\nDefault: (none) +\nExample: `myProp=myValue` +\nSets an external property that can be read by Pkl code with `read(\"prop:\")`.\nRepeat this option to set multiple external properties.\n====\n\n.--root-dir\n[%collapsible]\n====\nDefault: (none) +\nExample: `/some/path` +\nRoot directory for `file:` modules and resources.\nIf set, access to file-based modules and resources is restricted to those located under the specified root directory.\nAny symlinks are resolved before this check is performed.\n====\n\n.--settings\n[%collapsible]\n====\nDefault: (none) +\nExample: `mySettings.pkl` +\nFile path of the Pkl settings file to use.\nIf not set, `~/.pkl/settings.pkl` or defaults specified in the `pkl.settings` standard library module are used.\n====\n\n.-t, --timeout\n[%collapsible]\n====\nDefault: (none) +\nExample: `30` +\nDuration, in seconds, after which evaluation of a source module will be timed out.\nNote that a timeout is treated the same as a program error in that any subsequent source modules will not be evaluated.\n====\n\n.-w, --working-dir\n[%collapsible]\n====\nBase path that relative module paths passed as command-line arguments are resolved against.\nDefaults to the current working directory.\n====\n\n.--ca-certificates\n[%collapsible]\n====\nDefault: (none) +\nExample: `/some/path/certificates.pem` +\nPath to a file containing CA certificates to be used for TLS connections.\n\nSetting this option replaces the existing set of CA certificates bundled into the CLI.\nCertificates need to be X.509 certificates in PEM format.\n\nFor other methods of configuring certificates, see xref:pkl-cli:index.adoc#ca-certs[CA Certificates].\n====\n\n.--http-proxy\n[%collapsible]\n====\nDefault: (none) +\nExample: `\\http://proxy.example.com:1234` +\nConfigures HTTP connections to connect to the provided proxy address.\nThe URI must have scheme `http`, and may not contain anything other than a host and port.\n====\n\n.--http-no-proxy\n[%collapsible]\n====\nDefault: (none) +\nExample: `example.com,169.254.0.0/16` +\nComma separated list of hosts to which all connections should bypass the proxy.\nHosts can be specified by name, IP address, or IP range using https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation[CIDR notation].\n====\n\n.--http-rewrite\n[%collapsible]\n====\nDefault: (none) +\nExample: `\\https://pkg.pkl-lang.org/=https://my.internal.mirror/` +\nReplace outbound HTTP(S) requests from one URL with another URL.\nThe left-hand side describes the source prefix, and the right-hand describes the target prefix.\nThis option is commonly used to enable package mirroring.\nThe 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`.\n====\n\n.--trace-mode\n[%collapsible]\n====\nDefault: `compact` +\nSpecifies how `trace()` output is formatted.\nPossible options are `compact` and `pretty`.\n====\n" }, { "path": "docs/modules/pkl-cli/partials/cli-project-options.adoc", "content": "[[project-dir]]\n.--project-dir\n[%collapsible]\n====\nDefault: (none) +\nExample: `/some/path` +\nDirectory where the project lives.\n\nA project is a directory that contains a `PklProject` file, which is used to declare package dependencies, as well as common evaluator settings to be applied in the project.\n\nIf omitted, this is determined by searching up from the working directory for a directory that contains a `PklProject` file, until `--root-dir` or the file system root is reached.\n====\n\n[[omit-project-settings]]\n.--omit-project-settings\n[%collapsible]\n====\nDisables loading evaluator settings from the PklProject file.\n====\n\n[[no-project]]\n.--no-project\n[%collapsible]\n====\nDisables all behavior related to projects.\n====\n" }, { "path": "docs/modules/pkl-core/examples/CoreEvaluatorExample.java", "content": "import org.pkl.core.Evaluator;\nimport org.pkl.core.ModuleSource;\nimport java.util.List;\n\nimport org.pkl.core.PModule;\nimport org.pkl.core.PObject;\nimport org.junit.jupiter.api.Test;\n\n// the pkl-jvm-examples repo has a similar example\n@SuppressWarnings({\"unchecked\", \"unused\", \"ConstantConditions\", \"NewClassNamingConvention\"})\npublic class CoreEvaluatorExample {\n @Test\n public void usage() {\n // tag::usage[]\n PModule module;\n try (var evaluator =\n Evaluator.preconfigured()) { // <1>\n module = evaluator.evaluate(\n ModuleSource.text(\"pigeon { age = 30; hobbies = List(\\\"swimming\\\", \\\"surfing\\\") }\")); // <2>\n }\n var pigeon = (PObject) module.get(\"pigeon\"); // <3>\n var className = pigeon.getClassInfo().getQualifiedName(); // <4>\n var hobbies = (List) pigeon.get(\"hobbies\"); // <5>\n // end::usage[]\n }\n}\n" }, { "path": "docs/modules/pkl-core/pages/index.adoc", "content": "= pkl-core Library\ninclude::ROOT:partial$component-attributes.adoc[]\n:uri-pkl-core-maven-module: {uri-maven-docsite}/artifact/org.pkl-lang/pkl-core\n:uri-pkl-core-main-sources: {uri-github-tree}/pkl-core/src/main/java/org/pkl/core\n:uri-pkl-core-test-sources: {uri-github-tree}/pkl-core/src/test/kotlin/org/pkl/core\n:uri-pkl-core-Evaluator: {uri-pkl-core-main-sources}/Evaluator.java\n:uri-pkl-core-PModule: {uri-pkl-core-main-sources}/PModule.java\n:uri-pkl-core-PklException: {uri-pkl-core-main-sources}/PklException.java\n:uri-pkl-core-ValueVisitor: {uri-pkl-core-main-sources}/ValueVisitor.java\n:uri-pkl-core-JsonRenderer: {uri-pkl-core-main-sources}/JsonRenderer.java\n:uri-pkl-core-PcfRenderer: {uri-pkl-core-main-sources}/PcfRenderer.java\n:uri-pkl-core-PListRenderer: {uri-pkl-core-main-sources}/PListRenderer.java\n:uri-pkl-core-YamlRenderer: {uri-pkl-core-main-sources}/YamlRenderer.java\n:uri-pkl-core-SecurityManagers: {uri-pkl-core-main-sources}/SecurityManagers.java\n:uri-pkl-core-ModuleKeyFactories: {uri-pkl-core-main-sources}/module/ModuleKeyFactories.java\n\nThe _pkl-core_ library contains the Pkl parser, evaluator, REPL server, and xref:ROOT:standard-library.adoc[Standard Library].\nIt is the foundation for most of Pkl's other libraries and tools.\nThe library can also be used to embed Pkl in Java libraries and applications.\n\n[[pkl-core-installation]]\n== Installation\n\nThe _pkl-core_ library is available {uri-pkl-core-maven-module}[from Maven Central].\nIt requires Java 17 or higher.\n\n=== Gradle\n\nTo use the library in a Gradle project, declare the following dependency:\n\n[tabs]\n====\nKotlin::\n+\n.build.gradle.kts\n[source,kotlin,subs=\"+attributes\"]\n----\ndependencies {\n implementation(\"org.pkl-lang:pkl-core:{pkl-artifact-version}\")\n}\n\nrepositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven(url = \"{uri-sonatype}\")\nendif::[]\n}\n----\n\nGroovy::\n+\n.build.gradle\n[source,groovy,subs=\"+attributes\"]\n----\ndependencies {\n implementation \"org.pkl-lang:pkl-core:{pkl-artifact-version}\"\n}\n\nrepositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven { url \"{uri-sonatype}\" }\nendif::[]\n}\n----\n====\n\n=== Maven\n\nTo use the library in a Maven project, declare the following dependency:\n\n.pom.xml\n[source,xml,subs=\"+attributes\"]\n----\n\n \n org.pkl-lang\n pkl-core\n {pkl-artifact-version}\n \nifndef::is-release-version[]\n \n \n sonatype-s01\n Sonatype S01\n {uri-sonatype}\n \n \nendif::[]\n\n----\n\n== Usage\n\n{uri-pkl-core-Evaluator}[`Evaluator`] is the core evaluator that exposes multiple methods of evaluation.\n\nThe main evaluation method is `evaluate`, which returns a Java representation of the Pkl module object.\nIf evaluation succeeds, a {uri-pkl-core-PModule}[`PModule`] object representing the fully evaluated module is returned.\nOtherwise, an {uri-pkl-core-PklException}[`PklException`] with error details is thrown.\n\nLet's look at an example:\n\n[[config-evaluator-core-example]]\n[source,java,indent=0]\n----\ninclude::{examplesdir}/CoreEvaluatorExample.java[tags=usage]\n----\n<1> Build an `Evaluator` with default configuration.\nThe evaluator should be closed once it is no longer needed.\nIn this example, this is done with a try-with-resources statement.\nNote that objects returned by the evaluator remain valid after calling `close()`.\n<2> Build a `ModuleSource` using the given text as the module's contents. Evaluate the given module source. Alternatively, it's possible to build a `ModuleSource` from a file, path, uri, and other sources.\n<3> Get the module's `\"pigeon\"` property, which is represented as `PObject` in Java.\n<4> Get the class name for this object. In this example, the class name is `pkl.base#Dynamic`.\n<5> Get pigeon's `\"diet\"` property, which is represented as `List` in Java.\n\n[[value-visitor]]\nOften, {uri-pkl-core-ValueVisitor}[`ValueVisitor`] is a better way to process a module.\nSee {uri-pkl-core-PcfRenderer}[`PcfRenderer`], {uri-pkl-core-JsonRenderer}[`JsonRenderer`], {uri-pkl-core-YamlRenderer}[`YamlRenderer`] and {uri-pkl-core-PListRenderer}[`PListRenderer`] for examples.\n\n[[security-manager-spi]]\nThe (Pkl, not Java) security manager can be configured and customized using {uri-pkl-core-SecurityManagers}[`SecurityManagers`] and related classes.\n\n[[module-loader-spi]]\nModule loaders can be configured and customized using {uri-pkl-core-ModuleKeyFactories}[`ModuleKeyFactories`] and related classes.\n\n== Further Information\n\nRefer to the Javadoc and sources published with the library, or browse the library's {uri-pkl-core-main-sources}[main] and {uri-pkl-core-test-sources}[test] sources.\n" }, { "path": "docs/modules/pkl-doc/pages/index.adoc", "content": "= Pkldoc\ninclude::ROOT:partial$component-attributes.adoc[]\n:uri-pkl-doc-maven: {uri-maven-docsite}/artifact/org.pkl-lang/pkl-doc\n:uri-DocsiteInfo: {uri-pkl-stdlib-docs}/DocsiteInfo/\n:uri-DocPackageInfo: {uri-pkl-stdlib-docs}/DocPackageInfo/\n:uri-CliDocGenerator: {uri-pkl-doc-main-sources}/CliDocGenerator.kt\n:uri-DocGenerator: {uri-pkl-doc-main-sources}/DocGenerator.kt\n:uri-pkldoc-macos-amd64-download: {uri-sonatype-snapshot-download}&a=pkldoc-macos-amd64&e=bin\n:uri-pkldoc-macos-aarch64-download: {uri-sonatype-snapshot-download}&a=pkldoc-macos-aarch64&e=bin\n:uri-pkldoc-linux-amd64-download: {uri-sonatype-snapshot-download}&a=pkldoc-linux-amd64&e=bin\n:uri-pkldoc-linux-aarch64-download: {uri-sonatype-snapshot-download}&a=pkldoc-linux-aarch64&e=bin\n:uri-pkldoc-alpine-download: {uri-sonatype-snapshot-download}&a=pkldoc-alpine-linux-amd64&e=bin\n:uri-pkldoc-windows-download: {uri-sonatype-snapshot-download}&a=pkldoc-windows-amd64&e=exe\n:uri-pkldoc-java-download: {uri-sonatype-snapshot-download}&a=pkldoc-java&e=jar\n\nifdef::is-release-version[]\n:uri-pkldoc-macos-amd64-download: {github-releases}/pkldoc-macos-amd64\n:uri-pkldoc-macos-aarch64-download: {github-releases}/pkldoc-macos-aarch64\n:uri-pkldoc-linux-amd64-download: {github-releases}/pkldoc-linux-amd64\n:uri-pkldoc-linux-aarch64-download: {github-releases}/pkldoc-linux-aarch64\n:uri-pkldoc-alpine-download: {github-releases}/pkldoc-alpine-linux-amd64\n:uri-pkldoc-windows-download: {github-releases}/pkldoc-windows-amd64.exe\n:uri-pkldoc-java-download: {github-releases}/jpkldoc\nendif::[]\n\n_Pkldoc_ is a documentation website generator that produces navigable and searchable API documentation for Pkl modules.\n\nPkldoc's look and feel is inspired by Scaladoc.\nTo get a first impression, browse the link:{uri-pkl-stdlib-docs-index}[Standard Library API Docs].\n\n== Features\n\nPkldoc offers the following features:\n\nCode navigation::\nEasily navigate between hyperlinked modules, classes, functions, and properties.\nMember search::\nSearch the entire documentation by member name.\nSee the next section for details.\nComment folding::\nExpand and collapse multi-paragraph doc comments.\nMarkdown support::\nWrite doc comments in Markdown.\nSee xref:language-reference:index.adoc#doc-comments[Doc Comments] for details.\nMember links::\nLink to other members from your doc comments.\nSee xref:language-reference:index.adoc#member-links[Member Links] for details.\nMember anchors::\nGet a member's deep link by clicking its anchor symbol and copying the URL in the address bar.\nCross-site links::\nEnable cross-site member links simply by providing the URLs of other Pkldoc websites such as the standard library docs.\n\n[[member-search]]\n=== Member Search\n\nTo get a first impression of Pkldoc's member search, let's try and find property `MinFiniteFloat` in the link:{uri-pkl-stdlib-docs-index}[standard library docs]:\n\nimage::pkldoc-search.gif[title=\"Searching the standard library docs.\"]\n\nTo start a search, press kbd:[s]. Search results are displayed as you type.\n\nTo limit the search to a particular kind of member, prefix the search term with _m:_ for modules, _c:_ for classes, _f:_ for functions, or _p:_ for properties.\nFor example, search term _p:min_ finds property `MinFiniteFloat` but not function `min()`.\n\nCamel case matching is always enabled and does not require capitalizing the search term.\nFor example, search term _mff_ matches properties `MinFiniteFloat` and `MaxFiniteFloat`.\n\nBoth search terms and member names may contain non-ASCII Unicode characters.\nAs characters are normalized to their base form, search term _res_ matches `Réseau`.\n\nThe `@AlsoKnownAs` annotation, defined and used throughout the _pkl.base_ module, documents alternative names for a member used in other programming languages or earlier versions of a module.\nPkldoc's search takes these alternative names into account.\nFor example, searching the standard library docs for _count_ or _size_ finds property `String.length`.\nFeel free to use `@AlsoKnownAs` in your own modules.\n\nSearch results are categorized into _exact_ and _other_ (partial) matches.\nOn module and class pages, additional categories show matches in the same module and class.\nWithin a category, results are ranked by similarity with the search term.\n\nTo navigate to a search result, either click the result or select it with the up/down arrow keys and press kbd:[Enter].\n\n== Installation\n\nPkldoc is offered as Gradle plugin, Java library, and CLI.\n\n=== Gradle Plugin\n\nSee xref:pkl-gradle:index.adoc#installation[Installation] in the _Gradle Plugin_ chapter.\n\n[[install-library]]\n=== Java Library\n\nThe `pkl-doc` library is available {uri-pkl-doc-maven}[from Maven Central].\nIt requires Java 17 or higher.\n\nifndef::is-release-version[]\nNOTE: Snapshots are published to repository `{uri-snapshot-repo}`.\nendif::[]\n\n==== Gradle\n\nTo use the library in a Gradle project, declare the following dependency:\n\n[tabs]\n====\nKotlin::\n+\n.build.gradle.kts\n[source,kotlin,subs=\"+attributes\"]\n----\ndependencies {\n implementation(\"org.pkl-lang:pkl-doc:{pkl-artifact-version}\")\n}\n\nrepositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven(url = \"{uri-sonatype}\")\nendif::[]\n}\n----\n\nGroovy::\n+\n.build.gradle\n[source,groovy,subs=\"+attributes\"]\n----\ndependencies {\n implementation \"org.pkl-lang:pkl-doc:{pkl-artifact-version}\"\n}\n\nrepositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven { url \"{uri-sonatype}\" }\nendif::[]\n}\n----\n====\n\n==== Maven\n\nTo use the library in a Maven project, declare the following dependency:\n\n.pom.xml\n[source,xml,subs=\"+attributes\"]\n----\n\n \n org.pkl-lang\n pkl-doc\n {pkl-artifact-version}\n \nifndef::is-release-version[]\n \n \n sonatype-s01\n Sonatype S01\n {uri-sonatype}\n \n \nendif::[]\n\n----\n\n[[install-cli]]\n=== CLI\n\nThe CLI comes in multiple flavors:\n\n* Native macOS executable for amd64 (tested on macOS 10.15)\n* Native Linux executable for amd64\n* Native Linux executable for aarch64\n* Native Alpine Linux executable for amd64 (cross-compiled and tested on Oracle Linux 8)\n* Native Windows executable for amd64 (tested on Windows Server 2022)\n* Java executable (tested with Java 17/21 on macOS and Oracle Linux)\n\n.What is the Difference Between the Linux and Alpine Linux Executables?\n[NOTE]\n====\nThe Linux executable is dynamically linked against _glibc_ and _libstdc{plus}{plus}_,\nwhereas, the Alpine Linux executable is statically linked against _musl libc_ and _libstdc{plus}{plus}_.\n====\n\nThe Java executable works on multiple platforms and has a smaller binary size than the native executables.\nHowever, it requires a Java 17 (or higher) runtime on the system path, and has a noticeable startup delay.\n\nDownload links:\n\n* macOS aarch64: {uri-pkldoc-macos-aarch64-download}\n* macOS amd64: {uri-pkldoc-macos-amd64-download}\n* Linux aarch64: {uri-pkldoc-linux-aarch64-download}\n* Linux amd64: {uri-pkldoc-linux-amd64-download}\n* Alpine Linux amd64: {uri-pkldoc-alpine-download}\n* Windows amd64: {uri-pkldoc-windows-download}\n\n[[usage]]\n== Usage\n\nThe Pkldoc tool is offered as Gradle plugin, Java library, and CLI.\nIt can generate documentation either for modules directly, or generate documentation for _package uris_.\n\nThe tool requires an argument of a module named _docsite-info.pkl_, that amends link:{uri-DocsiteInfo}[pkl.DocsiteInfo].\n\n[discrete]\n==== Generating documentation for modules directly\n\nModules can be passed directly to Pkldoc for documentation generation.\nWhen generating documentation for these modules, there must also be a module named _doc-package-info.pkl_ that amends link:{uri-DocPackageInfo}[pkl.DocPackageInfo].\n\nThe _doc-package-info.pkl_ module defines a _doc package_, which describes how modules are grouped and versioned together. \n\nWhen generating documentation for modules, each such module must declare a module name that starts with a package name declared in a _doc-package-info.pkl_ module.\nFor example, the following are valid module declarations for package _com.example_:\n\n* `module com.example.Birds`\n* `module com.example.Birds.Parrot`\n\nThe part of the module name that comes after the package name\nmust match the module's relative path in its source code repository.\nFor example, module _com.example.Bird.Parrot_ is expected to be found at _$sourceCode/Bird/Parrot.pkl_,\nwhere _sourceCode_ is configured in _doc-package-info.pkl_.\n\n[discrete]\n==== Generating documentation for a _package_\n\nPkldoc can alternatively generate documentation for a _package_.\nWhen generating documentation for a package, the URI of the package must be passed as an argument to Pkldoc.\nThese packages must already be published and downloadable.\n\nWhen generating documentation for packages, modules within a package must declare a module name that is prefixed by the package's name declared in the `Package.name` property of its `PklProject` file.\nFor example, the following are valid module declarations for package `com.example`:\n\n* `module com.example.Birds`\n* `module com.example.Birds.Parrot`\n\nThe part of the module name that comes after the package name\nmust match the module's relative path in its source code repository.\nFor example, module _com.example.Bird.Parrot_ is expected to be found at _$sourceCode/Bird/Parrot.pkl_,\nwhere _sourceCode_ is configured in the `Package.sourceCode` property of its `PklProject` file.\n\n=== Gradle Plugin\n\nSee xref:pkl-gradle:index.adoc#pkldoc-generation[Pkldoc Generation] in the _Gradle Plugin_ chapter.\n\n=== Java Library\n\nThe Java library offers two APIs:\n\n* A high-level link:{uri-CliDocGenerator}[CliDocGenerator] API whose feature set corresponds to the CLI.\n* A low-level link:{uri-DocGenerator}[DocGenerator] API that offers additional features and control.\n\nFor more information, refer to the Javadoc documentation.\n\n=== CLI\n\n*Synopsis:* `pkldoc [] `\n\n``::\nThe absolute or relative URIs of docsite descriptors, package descriptors, and the modules for which to generate documentation.\n\nRelative URIs are resolved against the working directory.\n\n==== Options\n\n.-o, --output-dir\n[%collapsible]\n====\nDefault: (none) +\nExample: `pkldoc` +\nThe directory where generated documentation is placed.\n====\n\n.--no-symlinks\n[%collapsible]\n====\nCreate copies of files and directories instead of symbolic links.\nIn particular, this affects how the \"current\" directories containing documentation content for the last generated version should be created.\nBy default, a symbolic link is created pointing to the last generated version. If symlinks are disabled, a full copy of the last generated version is created.\n====\n\nCommon CLI options:\n\ninclude::../../pkl-cli/partials/cli-common-options.adoc[]\n\n[[full-example]]\n== Full Example\n\nFor a ready-to-go example with full source code and detailed walkthrough,\nsee link:{uri-pkldoc-example}[pkldoc] in the _pkl-jvm-examples_ repository.\n" }, { "path": "docs/modules/pkl-gradle/pages/index.adoc", "content": "= Gradle Plugin\ninclude::ROOT:partial$component-attributes.adoc[]\n:uri-pkl-gradle-maven-module: {uri-maven-docsite}/artifact/org.pkl-lang/org.pkl-lang.gradle.plugin\n:uri-pkl-gradle-main-sources: {uri-github-tree}/pkl-gradle/src/main/java/org/pkl/gradle\n:uri-pkl-gradle-Eval: {uri-pkl-gradle-main-sources}/Eval.java\n:uri-pkl-gradle-JavaCodeGen: {uri-pkl-gradle-main-sources}/JavaCodeGen.java\n:uri-pkl-gradle-KotlinCodeGen: {uri-pkl-gradle-main-sources}/KotlinCodeGen.java\n:uri-pkl-gradle-Pkldoc: {uri-pkl-gradle-main-sources}/Pkldoc.java\n\nThe Gradle plugin offers the following features:\n\n* <>\n* <>\n* <>\n* <>\n\nPlugin versions coincide with Pkl versions.\nThat is, plugin version `x.y.z` uses Pkl version `x.y.z`.\n\n[[installation]]\n== Installation\n\nThe Gradle plugin is available {uri-pkl-gradle-maven-module}[from Maven Central].\nIt requires Java 17 or higher and Gradle 8.1 or higher.\nEarlier Gradle versions are not supported.\n\nifndef::is-release-version[]\nNOTE: Snapshots are published to repository `{uri-snapshot-repo}`.\nendif::[]\n\nThe plugin is applied as follows:\n\n[tabs]\n====\nKotlin::\n+\n.build.gradle.kts\n[source,kotlin,subs=\"+attributes\"]\n----\nplugins {\n id(\"org.pkl-lang\") version \"{pkl-artifact-version}\"\n}\n----\n+\n.settings.gradle.kts\n[source,kotlin,subs=\"+attributes\"]\n----\npluginManagement {\n repositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven(url = \"{uri-sonatype}\")\nendif::[]\n }\n}\n----\n\nGroovy::\n+\n.build.gradle\n[source,groovy,subs=\"+attributes\"]\n----\nplugins {\n id \"org.pkl-lang\" version \"{pkl-artifact-version}\"\n}\n----\n+\n.settings.gradle\n[source,groovy,subs=\"+attributes\"]\n----\npluginManagement {\n repositories {\nifdef::is-release-version[]\n mavenCentral()\nendif::[]\nifndef::is-release-version[]\n maven { url \"{uri-sonatype}\" }\nendif::[]\n }\n}\n----\n====\n\n[[module-evaluation]]\n== Module Evaluation\n\nThis feature integrates the xref:pkl-cli:index.adoc[Pkl evaluator] into Gradle builds.\n\n=== Usage\n\nTo add an evaluator to the build, add a named configuration block inside `pkl.evaluators`:\n\n[tabs]\n====\nbuild.gradle::\n+\n[source,groovy]\n----\npkl {\n evaluators {\n evalPkl {\n sourceModules.add(file(\"module1.pkl\"))\n outputFile = layout.buildDirectory.file(\"module1.yaml\")\n outputFormat = \"yaml\"\n }\n }\n}\n----\n\nbuild.gradle.kts::\n+\n[source,kotlin]\n----\npkl {\n evaluators {\n register(\"evalPkl\") {\n sourceModules.add(file(\"module1.pkl\"))\n outputFile.set(layout.buildDirectory.file(\"module1.yaml\"))\n outputFormat.set(\"yaml\")\n }\n }\n}\n----\n====\n\nFor each declared evaluator, the Pkl plugin creates an equally named task.\nHence the above evaluator can be run with:\n\n[source,shell script]\n----\n$ ./gradlew evalPkl\n----\n\nFor a ready-to-go example with full source code,\nsee link:{uri-build-eval-example}[codegen-java] in the _pkl-jvm-examples_ repository.\n\n=== Configuration Options\n\n[[output-format]]\n.outputFormat: Property\n[%collapsible]\n====\nDefault: `\"pcf\"` +\nExample: `outputFormat = \"yaml\"` +\nThe output format to generate.\nThe default output renderer for a module supports the following formats:\n\n* `\"json\"`\n* `\"jsonnet\"`\n* `\"pcf\"`\n* `\"plist\"`\n* `\"properties\"`\n* `\"textproto\"`\n* `\"xml\"`\n* `\"yaml\"`\n====\n\n[[output-file]]\n.outputFile: RegularFileProperty\n[%collapsible]\n====\nDefault: `file(\"%\\{moduleDir}/%\\{moduleName}.%\\{outputFormat}\")` (places output files next to the source modules) +\nExample: `outputFile = layout.projectDirectory.file(\"config.yaml\")` +\nThe file path where the output file is placed.\nRelative paths are resolved against the project directory.\n\nIf multiple source modules are given, placeholders can be used to map them to different output files.\nThe following placeholders are supported:\n\n`%\\{moduleDir}`:::\nThe directory path of the module, relative to the working directory.\nOnly available when evaluating file-based modules.\n\n`%\\{moduleName}`:::\nThe simple module name as inferred from the module URI.\nFor hierarchical module URIs such as `+file:///foo/bar/baz.pkl+`, this is the last path segment without file extension.\n\n`%\\{outputFormat}`:::\nThe requested output format.\nOnly available if `outputFormat` is set.\n\nIf multiple sources modules are mapped to the same output file, their outputs are concatenated.\nBy default, module outputs are separated with `---`, as in a YAML stream.\n// suppress inspection \"AsciiDocLinkResolve\"\nThe separator can be customized using the link:#module-output-separator[`moduleOutputSeparator`] option.\n====\n\n[[multiple-file-output-dir]]\n.multipleFileOutputDir: DirectoryProperty\n[%collapsible]\n====\nExample 1: `multipleFileOutputDir = layout.projectDirectory.dir(\"output\")` +\nExample 2: `+multipleFileOutputDir = layout.projectDirectory.file(\"%{moduleDir}/output\")+`\nThe directory where a module's output files are placed.\n\nSetting this option causes Pkl to evaluate a module's `output.files` property\nand write the files specified therein.\nWithin `output.files`, a key determines a file's path relative to `multipleFileOutputDir`,\nand a value determines the file's contents.\n\nThis option cannot be used together with any of the following:\n\n* xref:output-file[outputFile]\n* xref:expression[expression]\n\nThis option supports the same placeholders as xref:output-file[outputFile].\n\nFor additional details, see xref:language-reference:index.adoc#multiple-file-output[Multiple File Output]\nin the language reference.\n====\n\n[[module-output-separator]]\n.moduleOutputSeparator: Property\n[%collapsible]\n====\nDefault: `\"---\"` (as in a YAML stream) +\nThe separator to use when multiple module outputs are written to the same file.\n====\n\n[[expression]]\n.expression: Property\n[%collapsible]\n====\nDefault: (none) +\nExample: `expression = \"topLevelProperty.subValue\"` +\nThe expression to be evaluated within the module.\n\nThis option causes Pkl to evaluate the provided expression instead of the module's `output.text` or `output.files` properties.\nThe resulting value is then stringified, and written to the designated output file.\n\nFor example, consider the following Pkl module:\n\n.my-pod.pkl\n[source%tested,{pkl}]\n----\nmetadata {\n name = \"my-pod\"\n}\n----\n\nThe expression `metadata.name` evaluates to text `my-pod`.\n====\n\nCommon properties:\n\ninclude::../partials/gradle-modules-properties.adoc[]\n\n[[tests]]\n== Tests\n\nThis feature integrates the xref:pkl-cli:index.adoc#usage[Pkl test evaluator] into Gradle builds.\n\n=== Usage\n\nTo add tests to the build, add a named configuration block inside `pkl.tests`:\n\n[tabs]\n====\nbuild.gradle::\n+\n[source,groovy]\n----\npkl {\n tests {\n testPkl {\n sourceModules.add(files(\"module1_test.pkl\", \"module2_test.pkl\"))\n junitReportsDir = layout.buildDirectory.dir(\"reports\")\n overwrite = false\n }\n }\n}\n----\n\nbuild.gradle.kts::\n+\n[source,kotlin]\n----\npkl {\n tests {\n register(\"testPkl\") {\n sourceModules.addAll(files(\"module1_test.pkl\", \"module2_test.pkl\"))\n junitReportsDir.set(layout.buildDirectory.dir(\"reports\"))\n overwrite.set(false)\n }\n }\n}\n----\n====\n\n[[junit-reports-path]]\n.junitReportsDir: DirectoryProperty\n[%collapsible]\n====\nDefault: `null` +\nExample: `junitReportsDir = layout.buildDirectory.dir(\"reports\")` +\nWhether and where to generate JUnit XML reports.\n====\n\n[[junit-aggregate-reports]]\n.junitAggregateReports: Property\n[%collapsible]\n====\nDefault: `false` +\nAggregate JUnit reports into a single file.\n====\n\n[[junit-aggregate-suite-name]]\n.junitAggregateSuiteName: Property\n[%collapsible]\n====\nDefault: `null` +\nThe name of the root JUnit test suite.\n====\n\n[[overwrite]]\n.overwrite: Property\n[%collapsible]\n====\nDefault: `false` +\nWhether to ignore expected example files and generate them again.\n====\n\n[[power-assertions-test]]\n.powerAssertions: Property\n[%collapsible]\n====\nDefault: `true` (for test tasks) +\nExample: `powerAssertions = false` +\nEnable or disable power assertions for detailed assertion failure messages.\nWhen enabled, test failures will show intermediate values in the assertion expression, making it easier to understand why a test failed.\n====\n\nCommon properties:\n\ninclude::../partials/gradle-modules-properties.adoc[]\n\n[[java-code-gen]]\n== Java Code Generation\n\nThis feature integrates the xref:java-binding:codegen.adoc[Java code generator] into Gradle builds.\n\n=== Usage\n\nTo add a Java code generator to the build, add a named configuration block inside `pkl.javaCodeGenerators`:\n\n[tabs]\n====\nbuild.gradle::\n+\n[source,groovy]\n----\npkl {\n javaCodeGenerators {\n genJava {\n sourceModules.addAll(files(\"Template1.pkl\", \"Template2.pkl\"))\n }\n }\n}\n----\n\nbuild.gradle.kts::\n+\n[source,kotlin]\n----\npkl {\n javaCodeGenerators {\n register(\"genJava\") {\n sourceModules.addAll(files(\"Template1.pkl\", \"Template2.pkl\"))\n }\n }\n}\n----\n====\n\nTo compile generated classes together with test code rather than main code, use `sourceSet = sourceSets.test`.\n\nTo generate getter methods instead of public final fields, use `generateGetters = true`.\n\nFor each declared Java code generator, the Pkl plugin creates an equally named task.\nHence, the above generator can be run with:\n\n[source,shell script]\n----\n$ ./gradlew genJava\n----\n\nFor a ready-to-go example with full source code,\nsee link:{uri-codegen-java-example}[codegen-java] in the _pkl-jvm-examples_ repository.\n\n=== Configuration Options\n\n.generateGetters: Property\n[%collapsible]\n====\nDefault: `false` +\nExample: `generateGetters = true` +\nWhether to generate private final fields and public getter methods rather than public final fields.\n====\n\n.paramsAnnotation: Property\n[%collapsible]\n====\nDefault: `null` if `generateSpringBootConfig` is `true`, `\"org.pkl.config.java.mapper.Named\"` otherwise+\nExample: `paramsAnnotation = \"org.project.MyAnnotation\"` +\nFully qualified name of the annotation type to use for annotating constructor parameters with their name. +\nThe specified annotation type must have a `value` parameter of type `String` or the generated code may not compile.\nIf set to `null`, constructor parameters are not annotated.\nWhether and how constructor parameters should be annotated depends on the library that instantiates the generated classes.\nFor Spring Boot applications, and for users of `pkl-config-java` compiling the generated classes with `-parameters`, no annotation is required.\n\n====\n.nonNullAnnotation: Property\n[%collapsible]\n====\nDefault: `\"org.pkl.config.java.mapper.NonNull\"` +\nExample: `nonNullAnnotation = \"org.project.MyAnnotation\"` +\nFully qualified name of the annotation type to use for annotating non-null types. +\nThe specified annotation type must be annotated with `@java.lang.annotation.Target(ElementType.TYPE_USE)`\nor the generated code may not compile.\n====\n\nCommon code generation properties:\n\ninclude::../partials/gradle-codegen-properties.adoc[]\n\nCommon properties:\n\ninclude::../partials/gradle-modules-properties.adoc[]\n\n[[kotlin-code-gen]]\n== Kotlin Code Generation\n\nThis feature integrates the xref:kotlin-binding:codegen.adoc[Kotlin code generator] into Gradle builds.\n\n=== Usage\n\nTo add a Kotlin code generator to the build, add a named configuration block inside `pkl.kotlinCodeGenerators`:\n\n[tabs]\n====\nbuild.gradle::\n+\n[source,groovy]\n----\npkl {\n kotlinCodeGenerators {\n genKotlin {\n sourceModules.addAll(files(\"Template1.pkl\", \"Template2.pkl\"))\n }\n }\n}\n----\n\nbuild.gradle.kts::\n+\n[source,kotlin]\n----\npkl {\n kotlinCodeGenerators {\n register(\"genKotlin\") {\n sourceModules.addAll(files(\"Template1.pkl\", \"Template2.pkl\"))\n }\n }\n}\n----\n====\n\nTo compile generated classes together with test code rather than main code, use `sourceSet = sourceSets.test`.\n\nFor each declared Kotlin code generator, the Pkl plugin creates an equally named task. Hence the above generator can be run with:\n\n[source,shell script]\n----\n$ ./gradlew genKotlin\n----\n\nFor a ready-to-go example with full source code,\nsee link:{uri-codegen-kotlin-example}[codegen-kotlin] in the _pkl-jvm-examples_ repository.\n\n=== Configuration Options\n\n=== Configuration Options\n\n.generateKdoc: Property\n[%collapsible]\n====\nDefault: `false` +\nExample: `generateKdoc = true` +\nWhether to preserve Pkl doc comments by generating corresponding KDoc comments.\n====\n\nCommon code generation properties:\n\ninclude::../partials/gradle-codegen-properties.adoc[]\n\nCommon properties:\n\ninclude::../partials/gradle-modules-properties.adoc[]\n\n[[pkldoc-generation]]\n== Pkldoc generation\n\nThis features integrates the xref:pkl-doc:index.adoc[Pkldoc] generator into Gradle builds.\n\n=== Usage\n\nTo add a Pkldoc generator to the build, add a named configuration block inside `pkl.pkldocGenerators`:\n\n[tabs]\n====\nbuild.gradle::\n+\n[source,groovy]\n----\npkl {\n pkldocGenerators {\n pkldoc {\n sourceModules.addAll(files(\"doc-package-info.pkl\", \"Template1.pkl\", \"Template2.pkl\"))\n }\n }\n}\n----\n\nbuild.gradle.kts::\n+\n[source,kotlin]\n----\npkl {\n pkldocGenerators {\n register(\"pkldoc\") {\n sourceModules.addAll(files(\"doc-package-info.pkl\", \"Template1.pkl\", \"Template2.pkl\"))\n }\n }\n}\n----\n====\n\nFor each declared Pkldoc generator, the Pkl plugin creates an equally named task.\nHence, the above generator can be run with:\n\n[source,shell script]\n----\n$ ./gradlew pkldoc\n----\n\nFor a ready-to-go example with full source code,\nsee link:{uri-pkldoc-example}[pkldoc] in the _pkl-jvm-examples_ repository.\n\n=== Configuration Options\n\nThe following properties can be configured inside a Pkldoc generator's configuration block:\n\n.outputDir: DirectoryProperty\n[%collapsible]\n====\nDefault: `layout.buildDirectory.dir(\"pkldoc/\")` +\nExample: `outputDir = layout.projectDirectory.dir(\"pkl-docs\")` +\nThe directory where generated documentation is placed.\n====\n\n.noSymlinks: Property\n[%collapsible]\n====\nDefault: `false` +\nExample: `noSymlinks = true` +\nCreate copies of files and directories instead of symbolic links.\nIn particular, this affects how the \"current\" directories containing documentation content for the last generated version should be created.\nBy default, a symbolic link is created pointing to the last generated version.\nIf symlinks are disabled, a full copy of the last generated version is created.\n====\n\nCommon properties:\n\ninclude::../partials/gradle-modules-properties.adoc[]\n\n[[project-package]]\n== Project packaging\nThis feature is the Gradle analogy for the xref:pkl-cli:index.adoc#command-project-package[project package] command in the CLI.\nIt prepares package assets to be published from a project.\n\nThere are two differences between this feature and the CLI:\n\n* Input project directories are required (the CLI determines a project from the current working directory if arguments are omitted).\n* Output directory defaults to a path within the build directory.\n\n=== Usage\n\n[tabs]\n====\nbuild.gradle::\n+\n[source,groovy]\n----\npkl {\n project {\n packagers {\n makePackages {\n projectDirectories.from(file(\"pkl-config/\"))\n }\n }\n }\n}\n----\n\nbuild.gradle.kts::\n+\n[source,kotlin]\n----\npkl {\n project {\n packagers {\n register(\"makePackages\") {\n projectDirectories.from(file(\"pkl-config/\"))\n }\n }\n }\n}\n----\n====\n\nFor each declared packager, the Pkl plugin creates an equally named task.\nHence, the above packager can be run with:\n\n[source,shell]\n----\n$ ./gradlew makePackages\n----\n\n=== Configuration Options\n\n.projectDirectories: ConfigurableFileCollection\n[%collapsible]\n====\nDefault: (none) +\nExample: `projectDirectories.from(file(\"pkl-config/\"\"))` +\nThe project directories to create packages for.\n====\n\n.skipPublishCheck: Property\n[%collapsible]\n====\nDefault: (false) +\nExample: `skipPublishCheck.set(true)`\n\nSkips checking whether a package has already been published with different contents.\n\nBy default, the packager will check whether a package at the same version has already been published.\nIf the package has been published, it validates that the package's metadata is identical to the locally generated metadata.\n====\n\n.outputPath: DirectoryProperty\n[%collapsible]\n====\nDefault: `project.getLayout().getBuildDirectory().dir(\"generated/pkl/packages\")`\n\nThe directory to write artifacts to.\nAccepts the following placeholders:\n\n`%\\{name}`:: The name of the package\n`%\\{version}`:: The version of the package\n====\n\n.junitReportsDir: DirectoryProperty\n[%collapsible]\n====\nDefault: `null` +\nExample: `junitReportsDir = layout.buildDirectory.dir(\"reports\")` +\nWhether and where to generate JUnit XML reports.\n====\n\n.overwrite: Property\n[%collapsible]\n====\nDefault: `false` +\nWhether to ignore expected example files and generate them again.\n====\n\nCommon properties:\n\ninclude::../partials/gradle-common-properties.adoc[]\n\n== Project Resolving\n\nThis feature is the Gradle analogy for the xref:pkl-cli:index.adoc#command-project-resolve[project resolve] command in the CLI.\nIt takes the dependencies of a project, and writes the resolved versions a file at path `PklProject.deps.json`, within the root directory of the project.\n\n=== Usage\n\n[tabs]\n====\nbuild.gradle::\n+\n[source,groovy]\n----\npkl {\n project {\n resolvers {\n resolvePklDeps {\n projectDirectories.from(file(\"pkl-config/\"))\n }\n }\n }\n}\n----\n\nbuild.gradle.kts::\n+\n[source,kotlin]\n----\npkl {\n project {\n resolvers {\n register(\"resolvePklDeps\") {\n projectDirectories.from(file(\"pkl-config/\"))\n }\n }\n }\n}\n----\n====\n\nFor each declared resolver, the Pkl plugin creates an equally named task.\nHence, the above resolver can be run with:\n\n[source,shell]\n----\n$ ./gradlew resolvePklDeps\n----\n\n=== Configuration Options\n\n.projectDirectories: ConfigurableFileCollection\n[%collapsible]\n====\nDefault: (none) +\nExample: `projectDirectories.from(file(\"pkl-config/\"\"))` +\nThe project directories to create packages for.\n====\n\nCommon properties:\n\ninclude::../partials/gradle-common-properties.adoc[]\n\n[[analyze-imports]]\n== Analyze Imports\n\nThis feature is the Gradle analogy for the xref:pkl-cli:index.adoc#command-analyze-imports[analyze imports] command in the CLI. It builds a graph of imports of the provided source modules.\n\n=== Usage\n\n[tabs]\n====\nbuild.gradle::\n+\n[source,groovy]\n----\npkl {\n analyzers {\n imports {\n appConfig {\n sourceModules.add(file(\"src/main/resources/appConfig.pkl\"))\n }\n }\n }\n}\n----\n\nbuild.gradle.kts::\n+\n[source,kotlin]\n----\npkl {\n analyzers {\n imports {\n register(\"appConfig\") {\n sourceModules.add(file(\"src/main/resources/appConfig.pkl\"))\n }\n }\n }\n}\n----\n====\n\n=== Configuration Options\n\n.outputFormat: Property\n[%collapsible]\n====\nSame meaning as <> in <>.\n====\n\n.outputFile: RegularFileProperty\n[%collapsible]\n====\nSame meaning as <> in <>.\n====\n\nCommon properties:\n\ninclude::../partials/gradle-modules-properties.adoc[]\n" }, { "path": "docs/modules/pkl-gradle/partials/gradle-codegen-properties.adoc", "content": ".indent: Property\n[%collapsible]\n====\nDefault: `\" \"` (two spaces) +\nExample: `indent = \"\\t\"` (one tab) +\nThe characters to use for indenting generated source code.\n====\n\n.outputDir: DirectoryProperty\n[%collapsible]\n====\nDefault: `layout.buildDirectory.dir(\"generated/pkl/\")` +\nExample: `outputDir = layout.projectDirectory.dir(\"src/main/pkl\")` +\nThe directory where generated classes are placed.\n\nThe default places generated sources within the build directory of the project, to avoid sources from being committed into the repository on accident.\n====\n\n.sourceSet: Property\n[%collapsible]\n====\nDefault: `sourceSets.main` (if it exists; no default otherwise) +\nExample: `sourceSet = sourceSets.test` +\nThe Gradle source set that generated code is compiled together with.\n\nFor the codegen tasks, the `modulePath` property defaults to the compilation classpath of this source set, as well as all of the source directories of the `resource` source directory set of this source set. This setup makes it possible to rely on modules defined in classpath dependencies of your project or in the resources of your project.\n\nFor projects which apply the `idea` plugin and are opened in IntelliJ IDEA, this option determines whether generated sources are marked as test sources (if the source set's name contains the word \"test\") or regular sources (otherwise).\n====\n\n.generateSpringBootConfig: Property\n[%collapsible]\n====\nDefault: `false` +\nExample: `generateSpringBootConfig = true` +\nWhether to generate config classes for use with Spring Boot.\n====\n\n.implementSerializable: Property\n[%collapsible]\n====\nDefault: `false` +\nExample: `implementSerializable = true` +\nWhether to generate classes that implement `java.io.Serializable`.\n====\n\n.addGeneratedAnnotation: Property\n[%collapsible]\n====\nDefault: `false` +\nExample: `addGeneratedAnnotation = true` +\nWhether to add the `org.pkl.config.java.Generated` annotation to generated types.\n====\n\n.renames: MapProperty\n[%collapsible]\n====\nDefault: `[:]` +\nExample: `renames = [\"foo.\": \"com.example.foo.\", \"bar.Config\": \"com.example.bar.Config\"]` +\nAllows to change default class and package names (derived from Pkl module names) in the generated code.\n\nWhen you need the generated class or package names to be different from the default names derived from the Pkl module names, you can define a rename mapping, where the key is the original Pkl module name prefix, and the value is its replacement.\nWhen you do, the generated code's `package` declarations, class names, as well as file locations, will be modified according to this mapping.\n\nThe prefixes are replaced literally, which means that dots at the end are important.\nIf you want to rename packages only, in most cases, you must ensure that you have an ending dot on both sides of a mapping (except for an empty mapping, if you use it), otherwise you may get unexpected results:\n\n----\n// Assuming the following mapping configuration:\nrenames = [\n \"com.foo.\": \"x\", // Dot on the left only\n \"org.bar\": \"y.\", // Dot on the right only\n \"net.baz\": \"z\" // No dots\n]\n\n// The following renames will be made:\n\"com.foo.bar\" -> \"xbar\" // Target prefix merged into the suffix\n\"org.bar.baz\" -> \"y..baz\" // Double dot, invalid name\n\"net.baz.qux\" -> \"z.qux\" // Looks okay, but...\n\"net.bazqux\" -> \"zqux\" // ...may cut the name in the middle.\n----\n\nWhen computing the appropriate target name, the longest matching prefix is used:\n\n----\n// Assuming the following mapping configuration:\nrenames = [\n \"com.foo.Main\": \"w.Main\",\n \"com.foo.\": \"x.\",\n \"com.\": \"y.\",\n \"\": \"z.\"\n]\n\n// The following renames will be made:\ncom.foo.Main -> w.Main\ncom.foo.bar -> x.bar\ncom.baz.qux -> y.baz.qux\norg.foo.bar -> z.org.foo.bar\n----\n\nKeys in this mapping can be arbitrary strings, including an empty string.\nValues must be valid dot-separated fully qualifed class name prefixes, possibly terminated by a dot.\n====\n\n" }, { "path": "docs/modules/pkl-gradle/partials/gradle-common-properties.adoc", "content": ".allowedModules: ListProperty\n[%collapsible]\n====\nDefault: `[\"pkl:\", \"file:\", \"modulepath:\", \"https:\", \"repl:\", \"package:\", \"projectpackage:\"]` +\nExample: `allowedModules = [\"file:\"]` +\nURI patterns that determine which modules can be loaded and evaluated.\nPatterns are matched against the beginning of module URIs.\n(File paths have been converted to `file:` URLs at this stage.)\nAt least one pattern needs to match for a module to be loadable.\n====\n\n.allowedResources: ListProperty\n[%collapsible]\n====\nDefault: `[\"env:\", \"prop:\", \"modulepath:\", \"https:\", \"file:\", \"package:\", \"projectpackage:\"]` +\nExample: `allowedResources = [\"env:\", \"prop:\"]` +\nURL patterns that determine which external resources can be read.\nPatterns are matched against the beginning of resource URLs.\nAt least one pattern needs to match for a resource to be readable.\n====\n\n.environmentVariables: MapProperty\n[%collapsible]\n====\nDefault: `[:]` (note that Gradle default differs from CLI default) +\nExample 1: `environmentVariables = [\"MY_VAR_1\": \"myValue1\", \"MY_VAR_2\": \"myValue2\"]` +\nExample 2: `environmentVariables = System.getenv()` +\nEnvironment variables that can be read by Pkl code with `read(\"env:\")`.\n====\n\n.evalRootDir: DirectoryProperty\n[%collapsible]\n====\nDefault: `rootProject.layout.projectDirectory` +\nExample 1: `evalRootDir = layout.projectDirectory.dir(\"pkl-modules\")` +\nExample 2: `evalRootDir.fileValue file(\"/some/absolute/path\")` +\n\nRoot directory for `file:` modules and resources.\nIf non-null, access to file-based modules and resources is restricted to those located under the root directory.\nAny symlinks are resolved before this check is performed.\n====\n\n.evalTimeout: Property\n[%collapsible]\n====\nDefault: `null` +\nExample: `evalTimeout = Duration.ofSeconds(10)` +\nDuration after which evaluation of a source module will be timed out.\nNote that a timeout is treated the same as a program error in that any subsequent source modules will not be evaluated.\n====\n\n.externalProperties: MapProperty\n[%collapsible]\n====\nDefault: `[:]` +\nExample: `externalProperties = [\"myProp1\": \"myValue1\", \"myProp2\": \"myValue2\"]` +\nExternal properties that can be read by Pkl code with `read(\"prop:\")`.\n====\n\n.moduleCacheDir: DirectoryProperty\n[%collapsible]\n====\nDefault: `null` +\nExample 1: `moduleCacheDir = layout.buildDirectory.dir(\"pkl-module-cache\")` +\nExample 2: `moduleCacheDir.fileValue file(\"/absolute/path/to/cache\")` +\nThe cache directory for storing packages.\nIf `null`, defaults to `~/.pkl/cache`.\n====\n\n.color: Property\n[%collapsible]\n====\nDefault: `false` +\nFormat messages using ANSI color.\n====\n\n.noCache: Property\n[%collapsible]\n====\nDefault: `false` +\nDisable caching of packages.\n====\n\n.modulePath: ConfigurableFileCollection\n[%collapsible]\n====\nDefault: `files()` (empty collection) +\nExample: `modulePath.from files(\"dir1\", \"zip1.zip\", \"jar1.jar\")` +\nThe directories, ZIP archives, or JAR archives to search when resolving `modulepath:` URIs.\nRelative paths are resolved against the project directory.\n====\n\n.proxy: Property\n[%collapsible]\n====\nDefault: `null` +\nExample: `proxy = uri(\"http://proxy.example.com:1234\")` +\nConfigures HTTP connections to connect to the provided proxy address.\nThe URI must have scheme `http`, and may not contain anything other than a host and port.\n====\n\n.noProxy: ListProperty\n[%collapsible]\n====\nDefault: `null` +\nExample: `noProxy = [\"example.com\", \"169.254.0.0/16\"]` +\nHosts to which all connections should bypass the proxy.\nHosts can be specified by name, IP address, or IP range using https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation[CIDR notation].\n====\n\n.httpRewrites: MapProperty\n[%collapsible]\n====\nDefault: `null` +\nExample: `httpRewrites = [uri(\"https://pkg.pkl-lang.org/\"): uri(\"https://my.internal.mirror/\")]` +\nReplace outbound HTTP(S) requests from one URL with another URL.\nThe left-hand side describes the source prefix, and the right-hand describes the target prefix.\nThis option is commonly used to enable package mirroring.\nThe 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`.\n====\n\n.powerAssertions: Property\n[%collapsible]\n====\nDefault: `false` (except for test tasks, which default to `true`) +\nExample: `powerAssertions = true` +\nEnable power assertions for detailed assertion failure messages.\nWhen enabled, type constraint failures will show intermediate values in the assertion expression.\nThis option has a performance impact when constraint failures occur.\n====\n" }, { "path": "docs/modules/pkl-gradle/partials/gradle-modules-properties.adoc", "content": "\n.sourceModules: ListProperty\n[%collapsible]\n====\nDefault: `[]` +\nExample 1: `sourceModules = [\"module1.pkl\", \"module2.pkl\"]` +\nExample 2: `+sourceModules = fileTree(\"config\").include(\"**/*.pkl\")+` +\nList of Pkl modules which are used for this operation.\n\nThis property accepts the following types to represent a module:\n\n* `java.net.URI`\n* `java.io.File`\n* `java.nio.file.Path`\n* `java.net.URL`\n* `java.lang.CharSequence` - if the represented string looks like a URI (it contains a scheme), the input is treated as a URI. Otherwise, it is treated as a path. Relative paths are resolved against the project directory.\n* `org.gradle.api.file.FileSystemLocation`\n====\n\n.transitiveModules: ConfigurableFileCollection\n[%collapsible]\n====\nDefault: [computed by pkl-gradle] +\nExample 1: `transitiveModules.from files(\"module1.pkl\", \"module2.pkl\")` +\nExample 2: `+transitiveModules.from fileTree(\"config\").include(\"**/*.pkl\")+` +\n\nFile paths of modules that are directly or indirectly used by source modules.\n\nThis property, along with `sourceModules`, is the set of input files used to determine whether this task is up-to-date or not.\n\nBy default, Pkl computes this property by analyzing the imports of the source modules.\nSetting this property explicitly causes Pkl to skip the analyze imports step.\n\nIncluding source modules in `transitiveModules` is permitted but not required.\nRelative paths are resolved against the project directory.\n====\n\n.projectDir: DirectoryProperty\n[%collapsible]\n====\nDefault: `null` +\nExample 1: `projectDir = layout.projectDirectory.dir(\"pkl\")` +\nExample 2: `projectDir.fileValue file(\"/some/absolute/path\")`\n\nDirectory where the project lives.\n\nA project is a directory that contains a `PklProject` file, which is used to declare package dependencies, as well as common evaluator settings to be applied in the project.\n\nIf `null`, this is determined by searching up from the working directory for a directory that contains a `PklProject` file, until `evalRootDir` or the file system root is reached.\n====\n\n.omitProjectSettings: Property\n[%collapsible]\n====\nDisables loading evaluator settings from the PklProject file.\n====\n\n.noProject: Property\n[%collapsible]\n====\nDisables all behavior related to projects.\n====\n\n.settingsModule: Property\n[%collapsible]\n====\nDefault: `null` +\nExample: `settingsModule = layout.projectDirectory.file(\"mySettings.pkl\")` +\nThe Pkl settings module to use.\nThis property accepts the same input types as the `sourceModules` property.\n\nIf `null`, `~/.pkl/settings.pkl` or defaults specified in the `pkl.settings` standard library module are used.\n====\n\ninclude::../partials/gradle-common-properties.adoc[]\n" }, { "path": "docs/modules/release-notes/pages/0.25.adoc", "content": "= Pkl 0.25 Release Notes\n:version: 0.25\n:version-minor: 0.25.1\n:release-date: February 1st, 2024\n\nPkl {version} was released on {release-date}. +\n[.small]#The latest bugfix release is {version-minor}. (xref:changelog.adoc[All Versions])#\n\nThis is the initial release of Pkl, a programming language for creating configuration.\n\nTo learn more about Pkl, refer to our xref:blog:ROOT:introducing-pkl.adoc[blog post].\n" }, { "path": "docs/modules/release-notes/pages/0.26.adoc", "content": "= Pkl 0.26 Release Notes\n:version: 0.26\n:version-minor: 0.26.3\n:release-date: June 17th, 2024\n\ninclude::ROOT:partial$component-attributes.adoc[]\n\nPkl {version} was released on {release-date}. +\n[.small]#The latest bugfix release is {version-minor}. (xref:changelog.adoc[All Versions])#\n\nThis release brings Windows support, improvements to controlling how Pkl talks over HTTP, and also fixes a scoping bug around typealiases.\n\nThe next release (0.27) is scheduled for October 10th, 2024.\n\nPlease 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]. +\n\n[small]#Pkl is hosted on https://github.com/apple/pkl[GitHub].\nTo get started, follow xref:pkl-cli:index.adoc#installation[Installation].#\n\n== Highlights [small]#💖#\n\nNews you don't want to miss.\n\n[[windows-support]]\n=== Windows Support\n\nPkl is now available on Windows! (https://github.com/apple/pkl/pull/492[#492])\n\n\nIn addition to macOS and Linux, Pkl is now available for download on Windows operating systems.\n\nFor installation instructions, consult xref:pkl-cli:index.adoc#windows-executable[Windows Executable] in the CLI reference.\n\n==== Writing cross-platform Pkl programs\n\nOn Windows, the in-language filepath separator is still `/`.\nThis means that most existing Pkl code should still continue working as-is.\n\nA small portion of programs will need to be updated to handle Windows support correctly.\nOne example is the various conversion scripts that read input files as CLI flags.\n\nFor example, here is a snippet from module https://github.com/apple/pkl-pantry/blob/d9571cdce407bb7f1687f81b945a4bfd24ce017d/packages/k8s.contrib/convert.pkl#L100C1-L103C74[k8s.contrib.convert]:\n\n.convert.pkl#L100-L103\n[source,pkl]\n----\nlocal inputUri =\n if (input.startsWith(Regex(#\"\\w+:\"#))) input // absolute URI\n else if (input.startsWith(\"/\")) \"file://\\(input)\" // absolute file path\n else \"file://\\(read(\"env:PWD\"))/\\(input)\" // relative file path\n----\n\nOn Windows, the env var `PWD` is a Windows-style path, like `C:\\Foo\\Bar\\Baz`.\nWith the above logic, `inputUri` can expand to a value like `\"\\file://C:\\Foo\\Bar\\Baz/input.yaml\"`.\nThis would an invalid URI; the correct URI should be `\"\\file:///C:/Foo/Bar/Baz/input.yaml\"`.\n\nHere is a possible fix for this code:\n\n[source,pkl]\n----\nimport \"pkl:platform\"\n\nlocal inputUri =\n if (input.startsWith(Regex(#\"\\w+:/\"#))) input\n else if (input.startsWith(\"/\")) \"file://\\(input)\"\n else\n let (pwd = read(\"env:PWD\"))\n let (\n path =\n if (platform.current.operatingSystem.name == \"Windows\")\n \"/\\(pwd)/\\(input)\".replaceAll(\"\\\\\", \"/\")\n else \"\\(pwd)/\\(input)\"\n )\n \"file://\\(path)\"\n----\n\nTo learn more about this design, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0006-import-paths-on-windows.adoc[SPICE-0006].\n\n[[http-proxying]]\n=== HTTP proxying\n\nPkl now supports proxying HTTP(S) requests (https://github.com/apple/pkl/pull/506[#506]).\n\nFor users of the CLI, Pkl will by default look for proxy settings configured within the OS when on macOS, Windows, and GNOME environments.\n\nThis can be changed by adding settings in the following locations:\n\n1. xref:pkl-cli:index.adoc#settings-file[Settings file]\n2. xref:language-reference:index.adoc#projects[PklProject file]\n3. `--http-proxy` and `--http-no-proxy` CLI flags\n\nAs part of this, some changes have been made to the standard library. For details, see <>.\n\nUsers of the Java/Kotlin bindings can specify proxy settings when building an <>.\n\nHTTP proxy settings are also added as new fields in the message-passing-api.\nAuthors of external Pkl clients are encouraged to support these new fields to provide proxy support in their libraries.\nFor details, see <>.\n\nTo read more about the design of HTTP proxying, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0004-HTTP-Proxy-Support.adoc[SPICE-0004], and also the xref:pkl-cli:index.adoc#http-proxy[documentation].\n\n[[scheme-agnostic-project-dependencies]]\n=== Scheme-agnostic project dependencies\n\nImprovements have been made to project dependencies (https://github.com/apple/pkl/pull/486[#486]).\n\nA project dependency is a way to manage `package`-based modules.\nIt provides two uses:\n\n1. A package can be imported through xref:language-reference:index.adoc#dependency-notation[dependency notation].\n2. Conflicting versions in the transitive dependency graph are resolved.\n\nCurrently, dependencies can only be used with file-based modules.\nThis can be limiting in some circumstances:\n\n1. JVM library users typically interact with Pkl by bundling Pkl files a classpath resources, and load them using `modulepath:` URIs.\n2. Go library users often embed Pkl code using the https://pkg.go.dev/embed#hdr-Directives[`go:embed` directive], and load them using https://pkg.go.dev/github.com/apple/pkl-go/pkl#WithFs[`WithFs`].\n\nThis means that these users miss out on the benefits of project dependencies.\n\nPkl 0.26 adds support for using dependencies in any hierarchical module scheme.\nThis means that `modulepath:` users in Java can now declare projects and dependencies.\nThis also means that other custom methods of embedding modules can also use dependency notation.\n\n[NOTE]\n====\nA _hierarchical_ URI is a URI whose path part starts with `/`, and in which `/` delimits path segments.\n\nThe URI `myscheme:/foo.pkl` is hierarchical, whereas the URI `myscheme:foo.pkl` is not.\n====\n\nTo read more about this design, consult https://github.com/apple/pkl-evolution/tree/main/spices/SPICE-0005-scheme-agnostic-projects.adoc[SPICE-0005].\n\n[[typealias-scoping-fix-and-change]]\n=== Typealias scoping fix and change\n\nImprovements have been made to `typealias`es (https://github.com/apple/pkl/pull/144[#144], https://github.com/apple/pkl/pull/373[#373], https://github.com/apple/pkl/pull/516[#516]).\n\nCurrently, a typealias that references a value on its enclosing module will break if used in another module.\n\n.myModule.pkl\n[source,pkl]\n----\ntypealias StartsWithFoo = String(startsWith(foo))\n\nfoo = \"foo\"\n----\n\n[source,pkl]\n----\nimport \"myModule.pkl\"\n\nmyStr: StartsWithFoo = \"fooey\"\n----\n\nThis results in error:\n\n[source]\n----\n–– Pkl Error ––\nCannot find property `foo`.\n\n1 | typealias StartsWithFoo = String(startsWith(foo))\n----\n\nThis is a language bug that has been fixed.\n\nIn the process of fixing this bug, we realized that the rules around variable resolution within typealiases were problematic.\nTypealiases are meant to be statically defined, and shouldn't be able to see properties that can be late-bound.\nThus, a new rule is introduced: a typealias can only reference properties/methods that are `const`.\n\nThis is a breaking change. To read more about this breakage and remediation steps, reference <>.\n\n== Noteworthy [small]#🎶#\n\nReady when you need them.\n\n[[pkldoc-improvements]]\n=== Pkldoc improvements\n\nThe following improvements have been made to xref:pkl-doc:index.adoc[Pkldoc]:\n\n1. The documentation for the standard library no longer shows dependent packages, because every package implicitly depends on the standard library (https://github.com/apple/pkl/pull/503[#503]).\n2. If the standard library exists in the package list, it is shown first (https://github.com/apple/pkl/pull/165[#165]).\n3. Fewer characters are percent-encoded. For example, the `(` and `)` characters are no longer percent-encoded (https://github.com/apple/pkl/pull/489[#489]).\n\n[[standard-library-changes]]\n=== Standard library changes\n\nTo support <>, several changes have been made to the standard library (https://github.com/apple/pkl/pull/506[#506]).\n\n* Module `pkl.settings` has new property `http`.\n* class `EvaluatorSettings` originally in `pkl.Project` has been moved to its own module.\nFor backwards compatibility, `pkl.Project` now has a `typealias EvaluatorSettings` pointing to the new module, but it is marked `@Deprecated`.\n\n=== Java API Changes\n\n[[http-java-client]]\n==== HTTP Java Client\n\nA new Java API is introduced, named `org.pkl.core.http.HttpClient` (https://github.com/apple/pkl/pull/217[#217], https://github.com/apple/pkl/pull/295[#295], https://github.com/apple/pkl/pull/506[#506], https://github.com/apple/pkl/pull/518[#518]).\nThis interface provides the ability to manage how Pkl makes HTTP(S) calls, including how it deals with CA certificates, as well as proxies.\n\nThis client can be passed to Pkl's evaluator using `EvaluatorBuilder` for users of pkl-core, and `ConfigEvaluatorBuilder` for users of pkl-config-java or pkl-config-kotlin.\n\n[[http-module-key-factory]]\n==== New HTTP ModuleKeyFactory\n\nA new module key factory for HTTP(S) modules has been added (https://github.com/apple/pkl/pull/495[#495]), and can be built with `org.pkl.core.ModuleKeyFactories#http`.\n\nThe preconfigured evaluator (`org.pkl.core.EvaluatorBuilder#preconfigured`) includes this module key.\nUsers that build their own evaluator from scratch should add this module key factory if HTTP(S) modules are needed.\n\nExample:\n\n[source,diff]\n----\n import org.pkl.core.EvaluatorBuilder;\n import org.pkl.core.module.ModuleKeyFactories;\n\n var evaluator = EvaluatorBuilder.unconfigured()\n+ .addModuleKeyFactory(ModuleKeyFactories.http) // <1>\n .build();\n----\n<1> Add `ModuleKeyFactories.http` to the set of module key factories used by this evaluator.\n\nIf this module key factory is not added, Pkl may still make HTTP(S) requests if `ModuleKeyFactories.genericUrl` is included.\nHowever, this bypasses proxy and CA certificate settings.\n\n[[pkl-executor-changes]]\n==== `pkl-executor` changes\n\nA new set of parameters are now available to `org.pkl.executor.Executor` (https://github.com/apple/pkl/pull/217[#217], https://github.com/apple/pkl/pull/518[#518]).\nThese new parameters are exposed by `org.pkl.executor.spi.v1.ExecutorSpiOptions2`.\n\nThe new parameters are:\n\n* `certificateFiles`: A set of CA certificate files to trust when making HTTPS requests.\n* `certificateBytes`: A set of PEM-encoded CA certificate bytes to trust when making HTTPS requests.\n* `testPort`: An option that is used for internal testing only.\n\nThese options are ignored when using a Pkl distribution whose version is lower than 0.26.0.\n\n[[message-passing-api-changes]]\n=== Message passing API changes\n\nA new property, `http`, is added to xref:bindings-specification:message-passing-api.adoc#create-evaluator-request[Create Evaluator Request] (https://github.com/apple/pkl/pull/506[#506], https://github.com/apple/pkl/pull/518[#518]).\n\nThis allows for the configuration of Pkl's HTTP proxy, as well as CA certificates.\n\n[[rename-codegen-classes]]\n=== Ability to rename classes produced by Java/Kotlin code generators\n\nThe Java and Kotlin code generators have a new option that allows users to change the name of Java/Kotlin classes that get produced during code generation (https://github.com/apple/pkl/pull/499[#499]).\n\nThe CLIs have a new flag, `--rename`, and the Gradle plugin receives a similarly named property called `renames`.\n\nThis option accepts a map from an old prefix to a new prefix, where longer prefixes have higher precedence than shorter prefixes.\n\nFor example, when generating `module foo.Bar`, specifying `--rename foo.=com.foo.` will cause the Java/Kotlin code generators to emit package `com.foo`, and class `Bar`.\n\n== Breaking Changes [small]#💔#\n\nThings to watch out for when upgrading.\n\n[[typealiases-are-treated-as-const]]\n=== Typealiases are treated as `const`\n\nA breaking change has been made to typealiases (https://github.com/apple/pkl/pull/516[#516]).\n\nTypealiases are types that can stand in for another type declaration.\n\nThe aliased type can have constraints, where these constraints can reference values defined on the enclosing module.\n\n.baseModule.pkl\n[source,pkl]\n----\ntypealias MyValue = Any(isValid) // <1>\n\nisValid = true\n----\n<1> `isValid` is defined on the enclosing module.\n\nOne problem with this is that typealiases are meant to be statically defined.\nLike classes, typealiases should not be changed by amending its enclosing module.\n\n[source,pkl]\n----\namends \"baseModule.pkl\"\n\nisValid = false // <1>\n----\n<1> Despite this amended value, `typealias MyValue` should still stand for `Any(true)`.\n\nTo have clearer semantics, a new rule is introduced: referenced members on the enclosing module must be `const`.\nEffectively, a typealias is treated as if it is also a `const` member.\n\nTo fix the above typealias, the `const` modifier should be added to `isValid`.\n\n[source,diff]\n----\n typealias MyValue = Any(isValid)\n \n-isValid = true\n+const isValid = true\n----\n\nIt might not always be valid to add the `const` modifier.\nFor example, this property may be overwritten in a downstream module, so adding the `const` modifier this would break that module.\nIn these cases, another fix is to self-import the enclosing module.\nThis works because import declarations introduce values that are implicitly marked `const`.\n\n.baseModule.pkl\n[source,diff]\n----\n+import \"baseModule.pkl\" // <1>\n+\n-typealias MyValue = Any(isValid)\n+typealias MyValue = Any(baseModule.isValid)\n \n isValid = true\n----\n<1> Self import\n\nThis change aligns with the behavior of class and annotation bodies.\n\nTo read more about the rationale behind this change, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0007-const-checks-in-typealiases.adoc[SPICE-0007].\n\n[[expanded-dependency-notation-uris]]\n=== Expanded dependency notation URIs\n\nThe parsing of relative path imports has changed (https://github.com/apple/pkl/pull/486[#486]).\n\nCurrently, the declaration `import \"@foo/bar.pkl\"` is treated as the import of a dependency named `foo`, but _only_ when declared within file-based and package-based modules.\nIn an HTTP-based module, for example, the above import is treated as \"bar.pkl inside directory @foo\".\n\nTo <>, such declarations are treated as dependency notation in all modules, and will fail with error \"Cannot find dependency\".\n\nAny import/reads that are intentionally relative-path imports will need to be updated to be prefixed with `./`.\n\nExample:\n\n[source,diff]\n----\n-import \"@bar/foo.pkl\"\n+import \"./@bar/foo.pkl\"\n----\n\n[[minimum-java-version-bump]]\n=== Minimum Java version bumped to Java 17\n\nThe minimum Java version for Pkl has been bumped to Java 17 (https://github.com/apple/pkl/pull/439[#439]).\n\nThis means that when running the xref:pkl-cli:index.adoc#java-executable[jpkl] CLI, the installed `java` is expected to be Java 17 or higher.\nThis also means that users of the JVM libraries need to be on at least Java 17 or higher.\n\n[[minimum-gradle-version-bump]]\n=== Gradle plugin minimum version bump\n\nThe minimum Gradle version for the xref:main:pkl-gradle:index.adoc[Gradle plugin] is now 8.1 (https://github.com/apple/pkl/pull/454[#454]).\n\n[[path-encoding-changes]]\n=== Path encoding changes\n\nIn order to support Windows, the output of some Pkl tools have unsafe characters encoded in a special format (https://github.com/apple/pkl/pull/489[#489]).\n\nOn Windows, the characters `<`, `>`, `:`, `\"`, `\\`, `|`, `?`, and `*` are reserved and cannot exist in a filename.\nAdditionally, the ASCII control character code points `0x0` through `0x1f` are also illegal.\n\nThese characters are encoded by wrapping their hexadecimal code point value in parentheses.\nFor example, the character `:` is encoded as `(3a)`.\n\nIn some scenarios, files that get written to disk will be encoded.\nThese are:\n\n* Files generated by Pkldoc.\n* `*.kt` files produced by the Kotlin code generator.\n* Packages written to the cache directory.\n\nTo learn more about this design, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0003-windows-safe-paths.adoc[SPICE-0003].\n\n==== Pkldoc links changes\n\nThe links generated by Pkldoc have changed.\n\nFor example, a module called `module `foo/package-1` to `/package-2`.\n\nIf Pkl's dependencies are vendored within a repository, these dependencies will need to be re-vendored.\n\n=== Java API Breaking Changes\n\nThe following Java APIs have breaking changes:\n\n|===\n|Class/method | Breaking change\n\n|`org.pkl.cli.commands.CliDownloadPackageCommand`\n|Renamed to `org.pkl.cli.commands.CliPackageDownloader`\n\n|`org.pkl.cli.commands.CliAbstractProjectCommand`\n|Renamed to `org.pkl.cli.commands.CliProjectCommand`\n\n|`org.pkl.config.java.InvalidMappingException`\n|Fields `pklName` and `javaName` are now `private`.\n\n|`org.pkl.core.packages.PackageResolver#getInstance`\n|New parameter `httpClient` added\n\n|`org.pkl.core.repl.ReplServer.ReplServer`\n|New parameter `httpClient` added\n\n|`org.pkl.commons.cli.CliBaseOptions`\n|New parameters `testPort`, `httpProxy`, `httpNoProxy` added\n|===\n\n[[standard-library-breaking-changes]]\n=== Standard library breaking changes\n\nClass `pkl.Project.EvaluatorSettings` has been removed.\nA new (deprecated) typealias is added that points to new module `pkl.EvaluatorSettings`.\nFor both of these, see https://github.com/apple/pkl/pull/506[#506].\n\n[[type-checked-settings-file]]\n=== Type-checked settings file\n\nThe loading of the xref:pkl-cli:index.adoc#settings-file[settings file] has changed (https://github.com/apple/pkl/pull/477[#477]).\n\nThe settings file is a way to control the behavior of the Pkl CLI.\nThis module is expected to `amends \"pkl:settings\"`, but this behavior was not checked.\n\nIn 0.26, it is an error if the settings module neither amends `\"pkl:settings\"`, nor set its `output.value` to an instance of the settings module.\n\n[[empty-directories-excluded-from-packaging]]\n=== Empty directories excluded from packaging\n\nCurrently, the `pkl project package` command will bundle empty directories into the resulting ZIP file.\n\nIn version 0.26, this has been changed to exclude these directories (https://github.com/apple/pkl/pull/330[#330]).\nThis means that the packages can produce a _different_ checksum if there are any empty directories.\n\nThis does not break the usage of existing packages, and does not affect compatibility of new packages used with older Pkl 0.25.\n\nHowever, this can break certain workflows.\nThe `pkl project package` command runs a publish check, to determine if a package has already been published but with a different checksum.\nWhen upgrading, users might encounter an error message like the following:\n\n[source]\n----\n-- Pkl Error --\nPackage `package://example.com/foo@1.0.0` was already published with different contents.\n----\n\nTo mitigate, the package's version needs to be bumped, even if package contents have not changed.\n\n== Miscellaneous [small]#🐸#\n\nThe following changes have been made that are neither new features nor breaking changes.\n\n* Pkl's user-agent header for HTTP requests has been tweaked to add a semicolon (https://github.com/apple/pkl/pull/221[#221]). Here is an example difference:\n+\nBefore: `Pkl/0.26 (macOS native)` + \nAfter: `Pkl/0.26 (macOS; native)`\n* Documentation improvements (https://github.com/apple/pkl/pull/120[#120], https://github.com/apple/pkl/pull/121[#121], https://github.com/apple/pkl/pull/142[#142], https://github.com/apple/pkl/pull/121[#121], https://github.com/apple/pkl/pull/337[#337], https://github.com/apple/pkl/pull/341[#341], https://github.com/apple/pkl/pull/372[#372], https://github.com/apple/pkl/pull/386[#386], https://github.com/apple/pkl/pull/391[#391], https://github.com/apple/pkl/pull/397[#397], https://github.com/apple/pkl/pull/422[#422], https://github.com/apple/pkl/pull/436[#436], https://github.com/apple/pkl/pull/469[#469], https://github.com/apple/pkl/pull/484[#484], https://github.com/apple/pkl/pull/485[#485], https://github.com/apple/pkl/pull/[#491]).\n* Optimization: `const` access is checked when variables are resolved, instead of every time the variable is accessed (https://github.com/apple/pkl/pull/438[#438]).\n* Optimization: use logical AND instead of bitwise AND when comparing numbers (https://github.com/apple/pkl/pull/102[#102]).\n* Mark Java classes `final` (https://github.com/apple/pkl/pull/458[#458]).\n* Migrate code to newer JDK17 features, and clean up existing Java code (https://github.com/apple/pkl/pull/451[#451], https://github.com/apple/pkl/pull/458[#458], https://github.com/apple/pkl/pull/512[#512]).\n* Improve rendering of string values within generated `.pkl-expected.pcf` files when running `pkl test` (https://github.com/apple/pkl/pull/416[#416]).\n* Improve performance of loading Pkl's built-in CA certificates (https://github.com/apple/pkl/pull/518[#518]).\n\n== Bug Fixes [small]#🐜#\n\nThe following bugs have been fixed.\n\n* `Collection#sortWith` produces un-sorted output (https://github.com/apple/pkl/pull/394[#394]).\n* Property `typedType` in module `pkl.reflect` reflects upon `Type`, instead of `Typed` (https://github.com/apple/pkl/pull/426[#426]).\n* `const` members can be assigned to when via an object spread (https://github.com/apple/pkl/pull/428[#428]).\n* Relative globbed reads resolve to the same value in different modules (https://github.com/apple/pkl/pull/449[#449]).\n* Performance bug: globbed imports and globbed reads expand to an unbounded number of root nodes (https://github.com/apple/pkl/pull/449[#449]).\n* Relative globbed imports within a package match no modules (https://github.com/apple/pkl/pull/496[#496]).\n* Constraints within typealiases resolve to the wrong values (https://github.com/apple/pkl/pull/144[#144]).\n* Members of `pkl.reflect` cannot be rendered (https://github.com/apple/pkl/pull/170[#170], https://github.com/apple/pkl/pull/470[#470]).\n* Throws `NullPointerException` if \"List Resources Response\" or \"List Modules Response\" messages contain both null `pathElements` and `error` (https://github.com/apple/pkl/pull/480[#480]).\n* Classes of `com.oracle.truffle` are not shaded in pkl-config-java-all and pkl-tools (https://github.com/apple/pkl/pull/238[#238]).\n* Throws `PklBugException` when running publish check on an invalid URL (https://github.com/apple/pkl/pull/441[#441]).\n\n== Contributors [small]#🙏#\n\nWe would like to thank the contributors to this release (in alphabetical order):\n\n* https://github.com/flyinprogrammer[@flyinprogrammer]\n* https://github.com/fumiya-kume[@fumiya-kume]\n* https://github.com/garysassano[@garysassano]\n* https://github.com/HT154[@HT154]\n* https://github.com/hoxell[@hoxell]\n* https://github.com/jw-y[@jw-y]\n* https://github.com/KushalP[@KushalP]\n* https://github.com/lilyball[@lilyball]\n* https://github.com/luuvish[@luuvish]\n* https://github.com/Malix-off[@Malix-off]\n* https://github.com/manuelsblanco[@manuelsblanco]\n* https://github.com/MarkSRobinson[@MarkSRobinson]\n* https://github.com/mitchcapper[@mitchcapper]\n* https://github.com/mrs1669[@mrs1669]\n* https://github.com/netvl[@netvl]\n* https://github.com/nirinchev[@nirinchev]\n* https://github.com/raj-j-shah[@raj-j-shah]\n* https://github.com/sgammon[@sgammon]\n* https://github.com/StefMa[@StefMa]\n* https://github.com/stefanobaghino[@stefanobaghino]\n* https://github.com/TimeTravelPenguin[@TimeTravelPenguin]\n* https://github.com/TheFruxz[@TheFruxz]\n* https://github.com/translatenix[@translatenix]\n* https://github.com/zihluwang[@zihluwang]\n\nA special thank-you goes out to https://github.com/translatenix[@translatenix]!\nThey submitted multiple bug fixes, improved the quality of the codebase, and provided HTTP improvements.\n" }, { "path": "docs/modules/release-notes/pages/0.27.adoc", "content": "= Pkl 0.27 Release Notes\n:version: 0.27\n:version-minor: 0.27.2\n:release-date: November 5th, 2024\n\ninclude::ROOT:partial$component-attributes.adoc[]\n\nPkl {version} was released on {release-date}. +\n[.small]#The latest bugfix release is {version-minor}. (xref:changelog.adoc[All Versions])#\n\nThis release brings improvements in typechecking of `Listing` and `Mapping`, the ability to use readers from external processes, as well as a new import graph analyzer API.\n\nThe next release (0.28) is scheduled for February 2025.\n\nPlease 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]. +\n\n[small]#Pkl is hosted on https://github.com/apple/pkl[GitHub].\nTo get started, follow xref:pkl-cli:index.adoc#installation[Installation].#\n\n== Highlights [small]#💖#\n\nNews you don't want to miss.\n\n[#typecheck-improvements]\n=== Improved typechecking of `Listing` and `Mapping` types\n\nTypechecking of `Listing` and `Mapping` types has been improved (https://github.com/apple/pkl/pull/628[#628], https://github.com/apple/pkl/pull/725[#725], https://github.com/apple/pkl/pull/740[#740], https://github.com/apple/pkl/pull/752[#752], https://github.com/apple/pkl/pull/778[#778], https://github.com/apple/pkl/pull/781[#781]).\n\nToday, the typecheck `listing: Listing` immediately evaluates all listing elements to check that they have type `E`.\nLikewise, the typecheck `mapping: Mapping` immediately evaluates all mapping values to check that they have type `V`.\n\nFor example, the typecheck `listing: Listing` proceeds as follows:\n\n1. Check that `listing` has type `Listing`\n2. Evaluate each listing element and check that it has type `Bird`\n\nThis behavior is different from how the rest of Pkl works.\nGenerally, Pkl only evaluates code that affects program output.\n\nFor example, consider the following program:\n\n[source,pkl]\n----\nclass Bird {\n name: String\n canFly: Boolean\n}\n\nlocal bird: Bird = new {\n name = \"Pidgy\"\n canFly = throw(\"uh oh\")\n}\n\nbirdName = bird.name\n----\n\nEven though `bird.canFly` throws an error, the above program succeeds because `bird.canFly` is not part of the program's output and hence is never accessed (Note that `bird` is a _local_ property).\n\nTypechecks of `Mapping` and `Listing` types have been changed to match this behavior.\nMapping and listing values are now only typechecked if and when they are accessed.\n\nNOTE: Mapping _keys_ are still eagerly checked.\n\nThis change causes some previously failing programs to evaluate successfully:\n\n[source,pkl]\n----\nlocal myNumbers: Listing = new { 1; 2; \"uh oh\" } \nresult = myNumbers[0]\n----\nIn Pkl 0.26 and below, the above program fails with a type mismatch error because element `\"uh oh\"` is typechecked when `myNumbers` is accessed.\nIn Pkl 0.27, the same program succeeds, because only element `myNumbers[0]` is part of the program's output and its typecheck succeeds.\n\nAs another consequence of this change, some Pkl programs now complete more quickly:\n\n[source,pkl]\n----\nlocal allBirds: Mapping = import*(\"**/bird.pkl\")\n\nenvironment: \"prod\"|\"qa\"\n\ncluster: String\n\nmyBird = allBirds[\"\\(environment)/\\(cluster)/bird.pkl\"] // <1>\n----\nIn Pkl 0.26 and below, all modules matching `**/bird.pkl` are imported when `allBirds` is accessed and typechecked.\nThis can take a long time.\nIn Pkl 0.27, only module `\"\\(environment)/\\(cluster)/bird.pkl\"` is imported because only this module is part of the program's output.\n\nTo learn more about this change, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0010-overhauled-mapping-listing-typechecks.adoc[SPICE-0010].\n\n=== External readers\n\nA new feature has been added to allow Pkl to spawn external processes to read resources and modules (https://github.com/apple/pkl/pull/660[#660], https://github.com/apple/pkl/pull/762[#762], https://github.com/apple/pkl/pull/766[#766], https://github.com/apple/pkl/pull/770[#770]).\n\nToday, users who use Pkl as a library can define custom module and resource readers.\nThis allows authors to extend how Pkl performs I/O.\n\nFor example, users can implement a reader that reads the `secret:` scheme, where they define exactly how the bytes are fetched in the host runtime.\n\n[source,pkl]\n----\nresult = read(\"secret:mypassword\") // <1>\n----\n<1> `secret:` is a custom scheme defined by the host runtime.\n\nHowever, CLI users have been left out.\n\nIn Pkl 0.27, a new extension point is added to allow users to implement module and resource readers as external processes.\nWhen run, Pkl will spawn the external process, and talk to the process via xref:bindings-specification:message-passing-api.adoc[message passing].\n\nTo learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0009-external-readers.adoc[SPICE-0009].\n\nThanks to https://github.com/HT154[@HT154] for contributing the feature!\n\n[[import-analysis]]\n=== Import analysis API\n\nA new API has been added to analyze the import graph of Pkl modules (https://github.com/apple/pkl/pull/695[#695]).\n\nThis API comes in four forms:\n\n1. A standard library module: `pkl:analyze`\n2. A CLI command: `pkl analyze imports`\n3. A Java API: `org.pkl.core.Analyzer`\n4. A Gradle API: `org.pkl.gradle.task.AnalyzeImportsTask`\n\nSome use-cases for this API are:\n\n* For build tools to perform out-of-date checks. Build tools can invalidate a cached result if any of the transitive modules have changed.\n* Static code analysis, to determine how Pkl modules depend on each other.\n\nWith this API, xref:pkl-gradle:index.adoc[] now by default <> for many of its tasks.\n\nHere is an example of the CLI in use:\n\n[source,shell]\n----\npkl analyze imports -f json myModule.pkl # <1>\n----\n<1> `-f` means: produce output in JSON.\n\nProduces:\n\n[source,json]\n----\n{\n \"imports\": {\n \"file:///my/proj/myModule.pkl\": [\n {\n \"uri\": \"projectpackage://example.com/birds@1.0.0#/Bird.pkl\"\n }\n ],\n \"projectpackage://example.com/birds@1.0.0#/Bird.pkl\": []\n },\n \"resolvedImports\": {\n \"file:///my/proj/myModule.pkl\": \"file:///my/proj/myModule.pkl\",\n \"projectpackage://example.com/birds@1.0.0#/Bird.pkl\": \"file:///my/birds/Bird.pkl\"\n }\n}\n----\n\nFrom this output, we can see that `myModule.pkl` imports `Bird.pkl` from the `birds` package.\nWe can also see that the module `projectpackage://example.com/birds@1.0.0#/Bird.pkl` resolves to disk location `\\file:///my/birds/Bird.pkl` (we can deduce that `birds` is a xref:language-reference:index.adoc#local-dependencies[local dependency]).\n\nTo learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0001-import-graph-analyzer-api.adoc[SPICE-0001].\n\n== Noteworthy [small]#🎶#\n\nReady when you need them.\n\n=== Colored output\n\nThe Pkl CLI will now emit some messages in color (https://github.com/apple/pkl/pull/552[#552], https://github.com/apple/pkl/pull/746[#746], https://github.com/apple/pkl/pull/771[#771], https://github.com/apple/pkl/pull/779[#779]).\n\nHere is a sneak peek of colored error messages in action.\n\nimage::error_sample.png[syntax highlighted output]\n\nThanks to https://github.com/thomaspurchas[@thomaspurchas] for contributing to this feature!\n\n=== `const local` object members\n\nThe `const` modifier can be applied to object members, provided that they are also `local` (https://github.com/apple/pkl/pull/678[#678]).\n\nCurrently, regular object members are not allowed to have the `const` modifier.\nThis introduces an artificial pain point.\n\nFor example, given the following module:\n\n[source,pkl]\n----\namends \"Bird.pkl\"\n\nimport \"Bird.pkl\"\n\nlocal northAmerica = \"North America\"\n\nlocal typealias NorthAmericanBird = Bird(this.origin == northAmerica) // <1>\n----\n<1> Error: cannot reference `northAmerica` from here because it is not `const`.\n\nThis is invalid code, because this typealias is referencing a non-const value on the enclosing module.\nHowever, is not possible fix this by adding the `const` modifier to `northAmerica`.\nThis is because this module `amends \"Bird.pkl\"`, which means that this module is considered a regular object and not a class.\nThis means that any members declared here are _object members_, and not _class members_.\n\nIn Pkl 0.27, a new rule is introduced to allow the `const` modifier to be applied to object members, provided that they are also `local`.\n\nThis change affects object properties, as well as object methods.\n\nTo read more about this design, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0011-const-object-members.adoc[SPICE-0011].\n\n=== Pkl CLI changes\n\n==== New CLI Flags\n\nSome new common flags have been added to the CLI (https://github.com/apple/pkl/pull/660[#660], https://github.com/apple/pkl/pull/746[#746]).\n\n|===\n|Flag |Description\n\n|`--color`\n|Format messages with ANSI color codes\n\n|`--external-module-reader`\n|Shell out to a process to read certain modules.\n\n|`--external-resource-reader`\n|Shell out to a process to read certain resources.\n|===\n\n==== New command: `pkl analyze imports`\n\nAs part of the set of APIs added for <>, a new subcommand has been added called `analyze imports` (https://github.com/apple/pkl/pull/695[#695]).\n\nFor details, consult the xref:pkl-cli:index.adoc#command-analyze-imports[CLI documentation].\n\n=== Kotlin/Java code generator improvements\n\nVarious improvements have been made to the Kotlin and Java code generators (https://github.com/apple/pkl/pull/705[#705], https://github.com/apple/pkl/pull/710[#710], https://github.com/apple/pkl/pull/714[#714], https://github.com/apple/pkl/pull/721[#721], https://github.com/apple/pkl/pull/729[#729]).\n\n==== Java codegen improvements\n\n* Only generate `hashCode()`, `equals()`, and `toString()` methods for Java classes that are instantiable.\n* Add support for Spring Boot 3.\n* Make module classes also implement serializable.\n* Make empty Java classes instantiable.\n\n==== Kotlin codegen improvements\n\n* Skip generation of `copy()`, `equals()`, `hashCode()`, `toString()` methods for abstract Kotlin classes.\n* Don't implement `Serializable` for abstract classes\n* Add support for Spring Boot 3.\n\nThanks to https://github.com/translatenix[@translatenix] for contributing these improvements!\n\n=== Gradle Plugin changes\n\n==== New `AnalyzeImportsTask`\n\nA new task called `org.pkl.gradle.task.AnalyzeImportsTask` is introduced (https://github.com/apple/pkl/pull/695[#695]).\n\nThis task is the Gradle analogy to `pkl analyze imports`.\n\nExample:\n\n[tabs]\n====\nbuild.gradle::\n+\n[source,groovy]\n----\npkl {\n analyzers {\n imports {\n appConfig {\n sourceModules.add(file(\"src/main/resources/appConfig.pkl\"))\n }\n }\n }\n}\n----\n\nbuild.gradle.kts::\n+\n[source,kotlin]\n----\npkl {\n analyzers {\n imports {\n register(\"appConfig\") {\n sourceModules.add(file(\"src/main/resources/appConfig.pkl\"))\n }\n }\n }\n}\n----\n====\n\nFor more details, consult the xref:pkl-gradle:index.adoc#analyze-imports[documentation].\n\n==== Tracked file outputs\n\nTasks created by the Pkl plugin now declare tracked output files (https://github.com/apple/pkl/pull/403[#403]).\n\nThis means that downstream tasks do not need to declare an explicit dependency on the Pkl task.\n\nFor example, assuming that `evalPkl` is an `EvalTask`:\n\n.build.gradle.kts\n[source,diff]\n----\n val myGradleTask by tasks.registering {\n inputs.files(evalPkl)\n- dependsOn(evalPkl) // <1>\n }\n----\n<1> No longer necessary to declare this dependency.\n\n[[transitive-modules-computed-by-default]]\n==== `transitiveModules` computed by default \n\nThe `transitiveModules` property of a task is now computed by building the import graph of the source modules (https://github.com/apple/pkl/pull/695[#695]).\n\nThis means that Pkl-related tasks no longer need to declare their set of transitive modules, because the pkl-gradle plugin will compute this automatically.\n\nNOTE: This adds latency to each task. To opt out of this behavior, set `transitiveModules` explicitly.\n\n=== Standard library changes\n\n==== Additions to `pkl:base`\n\nNew properties and methods have been added to the classes of `pkl:base` (https://github.com/apple/pkl/pull/666[#666], https://github.com/apple/pkl/pull/683[#683]).\n\nNew properties and methods have been added to {uri-stdlib-Listing}[`Listing`] and {uri-stdlib-Mapping}[`Mapping`].\n\nOne of the goals of this change is to improve the experience of authoring constraints.\nThis eliminates the need to convert to collection types as often.\n\nThe added properties and methods are:\n\n* {uri-stdlib-Listing}#first[`Listing.first`]\n* {uri-stdlib-Listing}#firstOrNull[`Listing.firstOrNull`]\n* {uri-stdlib-Listing}#last[`Listing.last`]\n* {uri-stdlib-Listing}#lastOrNull[`Listing.lastOrNull`]\n* {uri-stdlib-Listing}#single[`Listing.single`]\n* {uri-stdlib-Listing}#singleOrNull[`Listing.singleOrNull`]\n* {uri-stdlib-Listing}#every()[`Listing.every()`]\n* {uri-stdlib-Listing}#any()[`Listing.any()`]\n* {uri-stdlib-Listing}#contains()[`Listing.contains()`]\n* {uri-stdlib-Mapping}#containsValue()[`Mapping.containsValue()`]\n* {uri-stdlib-Mapping}#every()[`Mapping.every()`]\n* {uri-stdlib-Mapping}#any()[`Mapping.any()`]\n\nWith this, the following change can be made to existing constraints:\n\n[source,diff]\n----\n-ipAddresses: Listing(toList().contains(\"127.0.0.1\"))\n+ipAddresses: Listing(contains(\"127.0.0.1\"))\n----\n\nAdditionally, a new method is added to `String`, called {uri-stdlib-String}#splitLimit()[`String.splitLimit()`].\n\n==== Additions to `pkl:EvaluatorSettings`\n\nNew properties have been added to `pkl:EvaluatorSettings` (https://github.com/apple/pkl/pull/660[#660], https://github.com/apple/pkl/pull/746[#746]).\n\nThese are:\n\n* {uri-stdlib-evaluatorSettingsModule}/#color[`color`]\n* {uri-stdlib-evaluatorSettingsModule}/#externalModuleReaders[`externalModuleReaders`]\n* {uri-stdlib-evaluatorSettingsModule}/#externalResourceReaders[`externalResourceReaders`]\n\n==== `String` to `Number` conversion improvements.\n\nThe `String` to `Number` converter methods, for example, {uri-stdlib-StringToInt}[`String.toInt()`], can now handle underscore separators (https://github.com/apple/pkl/pull/578[#578], https://github.com/apple/pkl/pull/580[#580]).\n\nThis better aligns with the source code representation of xref:language-reference:index.adoc#integers[number literals].\n\n[source,pkl]\n----\nmyNum = \"1_000\".toInt() // <1>\n----\n<1> Result: `1000`\n\n==== New module: `pkl:analyze`\n\nAs part of <>, a new standard library module is added called `pkl:analyze` (https://github.com/apple/pkl/pull/695[#695]).\n\nThis module provides an API for computing the total import graph given a set of input modules.\nThis API treats the inputs as entrypoints, and produces a graph representing the entire dependency tree, including transitive imports.\n\nExample:\n[source,pkl]\n----\nimport \"pkl:analyze\"\n\nimportGraph: analyze.ImportGraph = analyze.importGraph(Set(\"file:///path/to/my/module.pkl\"))\n----\n\nFor details, see the {uri-stdlib-analyzeModule}[documentation].\n\n=== Annotations on `PklProject` added to packages\n\nWhen creating packages, some annotations on a `PklProject` will affect how pkldoc generates documentation.\n\n* `@Unlisted`: Omit the package from publishing documentation.\n* `@Deprecated`: Add information on the package to show that it is deprecated. \n\nExample:\n\n.PklProject\n[source,pkl]\n----\n@Deprecated\namends \"pkl:Project\"\n----\n\n=== Test report improvements\n\nThe report generated from `pkl test` has been overhauled and improved (https://github.com/apple/pkl/pull/498[#498], https://github.com/apple/pkl/pull/628[#682], https://github.com/apple/pkl/pull/738[#738], https://github.com/apple/pkl/pull/771[#771]).\n\n* Tests are grouped into either the `facts` or `examples` section.\n* A summary line is added, describing how many tests have passed and failed, and how many assertions have passed and failed.\n* Test results are colored.\n* The ✅ and ❌ emojis are replaced with ✔ and ✘.\n* Thrown errors are reported within the test.\n\nHere is a sneak peek of the new test result output.\n\nimage::test_sample.png[]\n\nThanks to https://github.com/jjmaestro[@jjmaestro] for contributing to this improvement!\n\n=== Java API additions\n\n==== New API: `org.pkl.core.Analyzer`\n\nAs part of <>, a new Java API called `org.pkl.core.Analyzer` is introduced (https://github.com/apple/pkl/pull/695[#695]).\n\n==== New methods\n\nThe following methods are added:\n\n**pkl-executor**\n\n* `org.pkl.executor.ExecutorException.getPklVersion`\n* `org.pkl.executor.ExecutorException.ExecutorException(java.lang.String, java.lang.Throwable, java.lang.String)`\n\n**pkl-core**\n\n* `org.pkl.core.module.ModuleKeyFactories.externalProcess(java.lang.String, org.pkl.core.externalreader.ExternalReaderProcess)`\n* `org.pkl.core.module.ModuleKeyFactories.externalProcess(java.lang.String, org.pkl.core.externalreader.ExternalReaderProcess, long)`\n\n== Breaking Changes [small]#💔#\n\nThings to watch out for when upgrading.\n\n=== Java API breaking changes\n\nThe following Java APIs have breaking changes:\n\n|===\n|Class/method | Breaking change\n\n|`org.pkl.core.runtime.TestResults`\n|Moved to `org.pkl.core.TestResults`, turned into a record, and largely restructured.\n\n|`org.pkl.core.module.ModuleKeyFactories.closeQuietly`\n|Deprecated for removal in favor of `org.pkl.core.Closeables.closeQuietly`.\n|===\n\n=== Spring Boot 2 support dropped\n\nThe Java code generator no longer supports Spring Boot 2.x (https://github.com/apple/pkl/pull/729[#729]).\n\nSpring Boot 2 users can continue to use the Pkl 0.26 code generator.\n\n=== `pkl test` considered failing when writing examples\n\nIf running `pkl test` results in `pkl-expected.pcf` files being written, the test now exits with exit code `10` (https://github.com/apple/pkl/pull/738[#738]).\n\nAdditionally, the junit reports will consider the test as failing.\n\n=== `Listing` and `Mapping` typecheck changes\n\nDue to changes to <>, some previously failing programs now succeed.\nThis can happen when erroneous code is never evaluated because it does not affect program output:\n\n[source,pkl]\n----\nlocal myNumbers: Listing = new { 1; 2; \"uh oh\" } \nresult = myNumbers[0] // <1>\n----\n<1> In Pkl 0.26 and below, throws a type mismatch error.\n+\nIn Pkl 0.27, yields `1`.\n\n== Miscellaneous [small]#🐸#\n\n* Make pkl-doc top box include a preview of the rest of module-level documentation (https://github.com/apple/pkl/pull/570[#570]).\n* Module `pkl-core` now has a dependency on `org.msgpack:msgpack-core` (https://github.com/apple/pkl/pull/660[#660]). Users concerned about potential version conflicts can use one of Pkl's shaded fat JARs (`pkl-config-java-all`, `pkl-tools`).\n* Make PklProject.deps.json files end in a newline (https://github.com/apple/pkl/pull/664[#644]).\n* Fix invalid syntax of code examples in stdlib doc comments (https://github.com/apple/pkl/pull/703[#703]).\n* Update Java dependencies (https://github.com/apple/pkl/pull/689[#689], https://github.com/apple/pkl/pull/767[#767]).\n* Add jbang catalog support (https://github.com/apple/pkl/pull/655[#655]).\n* Documentation improvements (https://github.com/apple/pkl/pull/623[#623], https://github.com/apple/pkl/pull/680[#680], https://github.com/apple/pkl/pull/682[#682], https://github.com/apple/pkl/pull/685[#685], https://github.com/apple/pkl/pull/687[#687], https://github.com/apple/pkl/pull/703[#703], https://github.com/apple/pkl/pull/704[#704], https://github.com/apple/pkl/pull/715[#715], https://github.com/apple/pkl/pull/730[#730], https://github.com/apple/pkl/pull/753[#753]).\n\n== Bug Fixes [small]#🐜#\n\nThe following bugs have been fixed.\n\n* CLI `--property` flags containing `=` in property values are not parsed correctly (https://github.com/apple/pkl/issues/630[#630]).\n* Thrown `PklBugException` when reading assets from a local project dependency (https://github.com/apple/pkl/issues/641[#641]).\n* Thrown `PklBugException` when PklProjects have a cyclical local dependency (https://github.com/apple/pkl/pull/731[#731]).\n* Thrown exception when sending `ReadResourceResponse` or `ReadModuleResponse` where both `contents` and `error` are `null` (https://github.com/apple/pkl/pull/657[#657]).\n* Double unary minus is evaluated as single unary minus (https://github.com/apple/pkl/pull/697[#697]).\n* Kotlin compiler fails to compiler generated classes with \"copy overrides nothing\" for subclasses of abstract classes (https://github.com/apple/pkl/issues/569[#569]).\n* \"Unexpected error\" thrown when `Module.output` has its type overridden (https://github.com/apple/pkl/issues/709[#709]).\n* \"Unexpected error\" thrown when loading files with non-ASCII characters (https://github.com/apple/pkl/issues/653[#653]).\n* Type parameters in `new Mapping`/`new Listing ` are not checked (https://github.com/apple/pkl/issues/405[#405]).\n* Comparison methods of `pkl:semver` are incorrect (https://github.com/apple/pkl/issues/772[#772]).\n\n== Contributors [small]#🙏#\n\nWe would like to thank the contributors to this release (in alphabetical order):\n\n* https://github.com/djarnis73[@djarnis73]\n* https://github.com/kasugamirai[@kasugamirai]\n* https://github.com/KushalP[@KushalP]\n* https://github.com/jjmaestro[@jjmaestro]\n* https://github.com/HT154[@HT154]\n* https://github.com/lamtrinhdev[@lamtrinhdev]\n* https://github.com/ManuW[@ManuW]\n* https://github.com/maxandersen[@maxandersen]\n* https://github.com/netvl[@netvl]\n* https://github.com/StefMa[@StefMa]\n* https://github.com/taichi-ishitani[@taichi-ishitani]\n* https://github.com/thomaspurchas[@thomaspurchas]\n* https://github.com/translatenix[@translatenix]\n" }, { "path": "docs/modules/release-notes/pages/0.28.adoc", "content": "= Pkl 0.28 Release Notes\n:version: 0.28\n:version-minor: 0.28.2\n:release-date: February 26th, 2025\n\ninclude::ROOT:partial$component-attributes.adoc[]\n\n:uri-snippet-tests: {uri-github-tree}/pkl-core/src/test/files/LanguageSnippetTests/input\n:uri-standard-library: {uri-github-tree}/stdlib/\n:uri-antlr: https://www.antlr.org\n:wbr: pass:[]\n\nPkl {version} was released on {release-date}. +\n[.small]#The latest bugfix release is {version-minor}. (xref:changelog.adoc[All Versions])#\n\nThe next release (0.29) is scheduled for June 2025.\nTo see what's coming in the future, follow the {uri-pkl-roadmap}[Pkl Roadmap].\n\nPlease 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]. +\n\n[small]#Pkl is hosted on https://github.com/apple/pkl[GitHub].\nTo get started, follow xref:pkl-cli:index.adoc#installation[Installation].#\n\n== Highlights [small]#💖#\n\nNews you don't want to miss.\n\n=== New parser\n\nPkl has new parser (https://github.com/apple/pkl/pull/917[#917], https://github.com/apple/pkl/pull/957[#957], https://github.com/apple/pkl/pull/962[#962])!\n\nThe first step to evaluating a program is to parse its source code into a parse tree.\nCurrently, Pkl uses link:{uri-antlr}[ANTLR] to generate parser code from grammar files.\n\nUsing this approach has allowed for rapidly iterating and changing the language's grammar.\nHowever, Pkl's grammar has matured; it's not as likely that the grammar will change from one version to the next.\nAdditionally, the current parser's performance has become more painful as projects written in Pkl grow in size.\nIn many cases, parsing can take up most of the time spent during evaluation.\n\nIn 0.28, the ANTLR-generated parser is being replaced by a handwritten parser.\nIn benchmarking tests, this has shown to improve parsing speed by around two orders of magnitude.\nHere are some quick comparisons between the two parsers, run on a MacBook Pro M4 Max machine, with 5 warmup iterations, and run for 10 iterations:\n\n|===\n||Old parser |New parser\n\n|link:{uri-snippet-tests}[Language snippet tests]\n|440.8ms\n|5.9ms\n\n|link:{uri-standard-library}[Standard library]\n|136.7msfootnote:[In the `pkl` CLI, the standard library is parsed during compilation rather than during evaluation. As a result, there is no parsing overhead.]\n|0.8ms\n\n|All https://github.com/apple/pkl-pantry[pkl-pantry] modules\n|1424.2ms\n|7.0ms\n|===\n\n== Noteworthy [small]#🎶#\n\nReady when you need them.\n\n=== CLI improvements\n\n==== Colored help messages\n\nThe `pkl`, `pkldoc`, `pkl-codegen-java`, and `pkl-codegen-kotlin` CLIs now emits help text with colors (https://github.com/apple/pkl/pull/947[#947]).\n\nHere is a sneak peek:\n\nimage::pkl-cli-help-new.png[new pkl cli help output]\n\nThanks to https://github.com/gordonbondon[@gordonbondon] for their contribution!\n\n==== `jpkl` support on Windows\n\nThe `jpkl` executable is now supported on Windows (https://github.com/apple/pkl/pull/872[#872]).\n\n`jpkl` is a fat jar that can be executed directly when on macOS and Linux, but current users of Windows are required to execute it with `java -jar `.\n\nIn 0.28, Windows users can also call execute this command directly.\nTo do so, the filename should be called `jpkl.bat`, and placed in `PATH`.\n\n=== Type constraint changes\n\nType annotations that are executed as a result of calling a constraint expressions now perform an eager typecheck (https://github.com/apple/pkl/pull/964[#964]).\n\nIn Pkl 0.27, we changed how xref:0.27.adoc#typecheck-improvements[typechecks are executed for `Listing` and `Mapping`] types.\n\nHowever, this had two unintended side effects:\n\nFor one, error messages from certain failing constraints show `?` in place of values that are failing.\n\nThe following snippet:\n\n[source%parsed,pkl]\n----\nclass Bird { name: String }\n\nbird: Listing(firstOneIsQuail) = new {\n new { name = \"Pigeon\" }\n new { name = \"Quail\" }\n}\n\nlocal firstOneIsQuail = (it: Listing) -> it[0].name == \"Quail\"\n----\n\nProduces the following error message:\n\n[source]\n----\n–– Pkl Error ––\nType constraint `firstOneIsQuail` violated.\nValue: new Listing { ?; ? }\n\n3 | bird: Listing(firstOneIsQuail) = new {\n ^^^^^^^^^^^^^^^\n----\n\n:fn-typecheck-details: footnote:[See https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0010-overhauled-mapping-listing-typechecks.adoc#delegating-objects[delegating objects] in SPICE-0010 for more details on this behavior.]\n\nThis is happening because lazy typechecks of mappings and listings will return a _new_ listing. Because the lambda's argument is defined as ``it: Listing``, the value being passed into the function body is this new listing{fn-typecheck-details}.\n\nSecondly, some constraints became less strict, allowing more values to pass.\n\nThe following snippet fails in Pkl 0.26, but passes in Pkl 0.27:\n\n[source%parsed,pkl]\n----\nclass Bird { name: String }\n\nlocal nonEmpty = (it: Listing) -> !it.isEmpty\n\nbirds: Listing(nonEmpty) = new { 1; 2; 3 }\n----\n\nThis is because the function parameter `it: Listing` does not actually check members of the argument until they are accessed, and the function body `!it.isEmpty` does not access any members.\n\nTo address both of these issues, the rule for executing type constraints has changed.\nWhen executing a type annotation, mapping and listing typechecks are always _eager_.\nThis means that Pkl will check that each member of the mapping/listing conforms to the type parameter.\n\n=== Java 22+ support\n\nPkl's Java libraries now support Java 22 and higher (https://github.com/apple/pkl/pull/876[#876]).\n\nThanks to https://github.com/sgammon[@sgammon] for their contribution!\n\n=== New standard library method\n\nThe `pkl:math` standard library module has a new method, called {uri-stdlib-mathModule}/index.html#atan2()[atan2] (https://github.com/apple/pkl/pull/819[#819]).\nIt computes the https://en.wikipedia.org/wiki/Atan2[2-argument arctangent].\n\nThanks to https://github.com/gordonbondon[@gordonbondon] for their contribution!\n\n=== Overhauled for-generator implementation\n\nThe implementation of xref:language-reference:index.adoc#for-generators[for-generators] has been overhauled (https://github.com/apple/pkl/pull/844[#844]).\n\nThis fixes some known bugs with the current for-generator implementation, and also improves code health by reducing complexity and removing workarounds and band-aids.\n\nThanks to https://github.com/odenix[@odenix] for their contribution!\n\n=== Java code generator improvements\n\nImprovements have been made to the Java code generator (https://github.com/apple/pkl/pull/792[#792]).\n\nIn pkl-codegen-java, the `--params-annotation` flag now accepts `none` as a value, which causes the code generator to skip adding annotations to a constructor's parameters.\nAdditionally, the Kotlin API `org.pkl.codegen.java.JavaCodeGeneratorOptions.paramsAnnotation` is now nullable.\nIf null, this also skips adding annotations.\n\nBy default, this annotation is set to `org.pkl.config.java.mapper.Named`, or none if the `--generate-spring-boot-config` flag is set.\n\nThis is useful for those compiling Java code with the `-parameters` flag set, because the pkl-config-java library is able to map into these classes without any extra annotations.\n\nThanks to https://github.com/odenix[@odenix] for their contribution!\n\n=== Kotlin code generator improvements\n\nImprovements have been made to the Kotlin code generator (https://github.com/apple/pkl/pull/793[#793]).\n\nCurrently, the output of `toString()` on a generated Kotlin class differs depending on if it was generated as a data class or as a regular class.\n\nIn Pkl 0.28, this method produces the same format, and matches the format used by data classes.\n\nThanks to https://github.com/odenix[@odenix] for their contribution!\n\n=== pkldoc improvements\n\npkldoc has a new flag to write real files instead of symlinks (https://github.com/apple/pkl/pull/824[#824]).\n\nCurrently, pkldoc creates a symlink called \"current\", which points to the latest non-prerelease version of a package.\nHowever, these symlinks can be problematic for some systems.\n\nA new flag, `--no-symlinks`, and a similarly named Gradle property, `noSymlinks`, instructs pkldoc to write real files instead of symlinks. \n\nThanks to https://github.com/netvl[@netvl] for their contributions!\n\n=== `jar:nested:` URIs are accepted by default\n\nTo improve integration with Spring Boot, the Pkl evaluator by default now accepts module URIs starting with `jar:nested:` (https://github.com/apple/pkl/pull/895[#895]).\n\nThe `--allowed-modules` flag (and the equally named option in other APIs) can be used to configure the set of allowed modules.\n\n== Breaking Changes [small]#💔#\n\nThings to watch out for when upgrading.\n\n=== Stricter grammar\n\nAs a result of implementing a new parser, the following previously accepted grammar is no longer valid (https://github.com/apple/pkl/pull/917[#917]).\n\n==== Inline object entries\n\nWhen declaring multiple xref:language-tutorial:01_basic_config.adoc#entries[entries] on the same line, a semicolon is now required to separate them.\n\nThe following code snippet is currently valid, and becomes a syntax error in 0.28.\n\n[source,pkl]\n----\nobj { [\"one\"] = 1 [\"two\"] = 2 }\n----\n\nTo fix, insert a semicolon between the two entries:\n\n[source,diff]\n----\n-obj { [\"one\"] = 1 [\"two\"] = 2 }\n+obj { [\"one\"] = 1; [\"two\"] = 2 }\n----\n\n==== String escapes\n\nWhen using xref:language-reference:index.adoc#custom-string-delimiters[custom string delimiters], the escape sequence becomes backslash (`\\`) plus the number of pounds used to delimit the string.\n\nDue to a parser bug, any extra pounds after this escape sequence are also permitted.\n\nIn Pkl 0.28, this becomes a syntax error.\n\n[source,pkl]\n----\nfoo = \"foo \\#(bar)\" // Invalid character escape sequence `\\#`.\n----\n\n==== Whitespace between generator members\n\nInline object spreads, for generators, and when generators all now require either whitespace or a semicolon separator.\n\n[source,pkl]\n----\nfoo { ...bar...baz } // Syntax error\n----\n\n=== Minimum Gradle version bump\n\nThe minimum Gradle version for the xref:main:pkl-gradle:index.adoc[Gradle Plugin] has been bumped to 8.2 (https://github.com/apple/pkl/pull/901[#901]).\n\n=== Minimum Kotlin version bump\n\nFor users of Pkl's Kotlin libraries, the minimum Kotlin version has been bumped to 2.0 (https://github.com/apple/pkl/pull/900[#900]).\n\n=== Java/Kotlin API breaking changes\n\nBreaking changes have been made to the Java/Kotlin APIs (https://github.com/apple/pkl/pull/748[#748], https://github.com/apple/pkl/pull/749[#749], https://github.com/apple/pkl/pull/776[#776], https://github.com/apple/pkl/pull/793[#793], https://github.com/apple/pkl/pull/808[#808], https://github.com/apple/pkl/pull/810[#810]).\n\n|===\n|API |Breakage\n\n| org.pkl.core.resource{wbr}.Resource \n| Converted into a record; previous getter methods are deprecated.\n\n| org.pkl.core.project{wbr}.Package \n| Converted into a record; previous getter methods are deprecated.\n\n| org.pkl.core.Member{wbr}.SourceLocation \n| Converted into a record; previous getter methods are deprecated.\n\n| org.pkl.core{wbr}.Release \n| Converted into a record; previous getter methods are deprecated.\n\n| org.pkl.core.Release{wbr}.SourceCode \n| Converted into a record; previous getter methods are deprecated.\n\n| org.pkl.core.Release{wbr}.Documentation \n| Converted into a record; previous getter methods are deprecated.\n\n| org.pkl.core.Release{wbr}.StandardLibrary \n| Converted into a record; previous getter methods are deprecated.\n\n| org.pkl.core.project{wbr}.DeclaredDependencies \n| Converted into a record; previous getter methods are deprecated.\n\n| org.pkl.core.evaluatorSettings{wbr}.PklEvaluatorSettings{wbr}.Proxy{wbr}.create \n| Deprecated; use the constructor instead.\n\n| org.pkl.core.module{wbr}.ExternalModuleResolver \n| Moved into package org.pkl.core.externalreader\n\n| org.pkl.core.resource{wbr}.ExternalResourceResolver \n| Moved into package org.pkl.core.externalreader\n\n| org.pkl.core.messaging{wbr}.MessageTransportModuleResolver \n| Renamed to ExternalModuleResolverImpl, made package-private\n\n| org.pkl.core.messaging{wbr}.MessageTransportResourceResolver \n| Renamed to ExternalResourceResolverImpl, made package-private\n\n| org.pkl.core.module{wbr}.ExternalModuleResolver{wbr}.Spec \n| Replaced with record org.pkl.core.externalreader.ModuleReaderSpec\n\n| org.pkl.core.resource{wbr}.ExternalResourceResolver{wbr}.Spec \n| Replaced with record org.pkl.core.externalreader.ResourceReaderSpec\n\n| org.pkl.core.messaging{wbr}.CreateEvaluatorRequest \n| Changed properties `allowedModules` and `allowedResources` to be of type `List` instead of `List`\n\n| org.pkl.codegen.kotlin{wbr}.KotlinCodegenOptions\n| Renamed to org.pkl.codegen.kotlin.KotlinCodeGeneratorOptions\n\n| org.pkl.codegen.kotlin{wbr}.CliKotlinCodeGeneratorOptions{wbr}.toKotlinCodegenOptions\n| Deprecated without replacement\n\n| org.pkl.codegen.java{wbr}.JavaCodegenOptions\n| Renamed to org.pkl.codegen.java.JavaCodeGeneratorOptions\n\n| org.pkl.codegen.java{wbr}.CliJavaCodeGeneratorOptions{wbr}.toJavaCodegenOptions()\n| Deprecated without replacement \n|===\n\n=== Fat jars no longer shade Truffle\n\nPkl publishes two fat jars to Maven Central: https://central.sonatype.com/artifact/org.pkl-lang/pkl-tools[pkl-tools], and https://central.sonatype.com/artifact/org.pkl-lang/pkl-config-java-all[pkl-config-java-all].\n\nDue a version bump in the Truffle library, the package `com.oracle.truffle` can no longer be shaded.\n\nFor users that use both Pkl and other Truffle languages, this means that their version of Truffle should match Pkl's version.\n\n== Miscellaneous [small]#🐸#\n\n* Documentation improvements (https://github.com/apple/pkl/pull/792[#792], https://github.com/apple/pkl/pull/846[#846], https://github.com/apple/pkl/pull/860[#860], https://github.com/apple/pkl/pull/892[#892], https://github.com/apple/pkl/pull/921[#921], https://github.com/apple/pkl/pull/937[#937], https://github.com/apple/pkl/pull/943[#943], https://github.com/apple/pkl/pull/944[#944], https://github.com/apple/pkl/pull/955[#955], https://github.com/apple/pkl/pull/956[#956], https://github.com/apple/pkl/pull/973[#973]).\n* The repository now requires Java 21 or higher to build (https://github.com/apple/pkl/pull/876[#876]).\n* Enable multi-jdk testing via `-DmultiJdkTesting=true` flag when building Pkl (https://github.com/apple/pkl/pull/876[#876]).\n* Allow setting commit id via `-DcommitId` flag when building Pkl (https://github.com/apple/pkl/pull/954[#954]).\n\n== Bugs fixed [small]#🐜#\n\nThe following bugs have been fixed.\n\n[smaller]\n* Optimization: `const` members should be cached for all children in the prototype chain (https://github.com/apple/pkl/issues/508[#508])\n* codegen-kotlin: Use same toString() representation for data classes and regular classes (https://github.com/apple/pkl/issues/717[#717])\n* Late-bound values of iteratees within nested for/spread fail to resolve for-generator variables (https://github.com/apple/pkl/issues/741[#741])\n* codegen-java/kotlin: Fix generation of equals/hashCode methods (https://github.com/apple/pkl/pull/802[#802]) \n* Not possible to render mapping with Int keys in YAML (https://github.com/apple/pkl/issues/878[#878])\n* Parser accepts wrong string escapes (https://github.com/apple/pkl/issues/888[#888])\n* Downstream native-image embedders are broken (https://github.com/apple/pkl/issues/907[#907])\n* Failed type constraint error messages do not show forced members (https://github.com/apple/pkl/issues/918[#918])\n* ANTLR incompatibilities (https://github.com/apple/pkl/issues/927[#927])\n* Doc comments with interleaving comments result in an error (https://github.com/apple/pkl/issues/931[#931])\n* Spread elements inside an object body don't need separators (https://github.com/apple/pkl/issues/932[#932])\n* Correctly set allowed modules/resoures when external reader scheme contain regex control characters (https://github.com/apple/pkl/pull/941[#941])\n* Bad import analysis fails with \"None (cause has no message)\" (https://github.com/apple/pkl/issues/949[#949])\n\n== Contributors [small]#🙏#\n\nWe would like to thank the contributors to this release (in alphabetical order):\n\n* https://github.com/gordonbondon[@gordonbondon]\n* https://github.com/HT154[@HT154]\n* https://github.com/jsoref[@jsoref]\n* https://github.com/KushalP[@KushalP]\n* https://github.com/netvl[@netvl]\n* https://github.com/odenix[@odenix]\n* https://github.com/romacafe[@romacafe]\n* https://github.com/sgammon[@sgammon]\n* https://github.com/sorcix[@sorcix]\n* https://github.com/stanleyycheung[@stanleyycheung]\n" }, { "path": "docs/modules/release-notes/pages/0.29.adoc", "content": "= Pkl 0.29 Release Notes\n:version: 0.29\n:version-minor: 0.29.1\n:release-date: July 24th, 2025\n\ninclude::ROOT:partial$component-attributes.adoc[]\n\nPkl {version} was released on {release-date}. +\n[.small]#The latest bugfix release is {version-minor}. (xref:changelog.adoc[All Versions])#\n\nThis release brings support for working with binary data, and also a new setting to control HTTP rewriting.\n\nThe next release (0.30) is scheduled for October 2025.\nTo see what's coming in the future, follow the {uri-pkl-roadmap}[Pkl Roadmap].\n\nPlease 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]. +\n\n[small]#Pkl is hosted on https://github.com/apple/pkl[GitHub].\nTo get started, follow xref:pkl-cli:index.adoc#installation[Installation].#\n\n== Highlights [small]#💖#\n\n[[bytes-standard-library-class]]\n=== `Bytes` standard library class\n\nA new standard library class is introduced, called `Bytes` (https://github.com/apple/pkl/pull/1019[#1019]).\n\nCurrently, Pkl does not have a built-in way to describe binary data.\nIn situations where binary data is needed, the common pattern is to use a Base64 string.\nThis is sufficient in simple cases, but still introduces many shortcomings:\n\n1. `pkl eval` can only produce UTF-8 encoded strings.\n2. It is not possible to compute the checksum of binary content (except in the case of `read()`).\n3. It is hard to interop with configuration formats that allow binary data.\n4. It is hard to do transformations on binary data.\n\nTo address these shortcomings, the `Bytes` class is introduced.\nThis is a data type representing a sequence of bytes.\n\n[source,pkl]\n----\nmyBytes = Bytes(0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x2c, 0x20, 0x57, 0x6f, 0x72, 0x6c, 0x64, 0x21) // <1>\n----\n<1> ASCII bytes for the string \"Hello, World!\"\n\nTo learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0013-bytes-standard-library.adoc[SPICE-0013].\n\n==== Emitting binary output\n\nA new property called `bytes` is added to `FileOutput`.\nThe CLI has been changed to evaluate this property, and write its contents to the designated output location.\n\nThis change means that Pkl modules can now output binary content.\nFor example, here is a simple module that outputs bytes:\n\n[source,pkl]\n----\noutput {\n bytes = Bytes(1, 2, 3, 4) // <1>\n}\n----\n<1> Write bytes 1, 2, 3, 4\n\nThe same change applies when evaluating in multiple-file output mode.\n\n[source,pkl]\n----\noutput {\n files {\n [\"foo.bin\"] {\n bytes = Bytes(1, 2, 3, 4) // <1>\n }\n }\n}\n----\n<1> Write bytes 1, 2, 3, 4 to a file called `foo.bin`.\n\n==== Rendering `Bytes`\n\nOut of the box, only the `plist` and `pcf` formats are able to render `Bytes`.\nFor other formats, a renderer needs to be defined.\n\n[source,pkl]\n----\noutput {\n renderer = new JsonRenderer {\n [Bytes] = (it) -> it.base64 // <1>\n }\n}\n----\n<1> Render bytes as a base64 string in JSON.\n\n==== Using `Bytes` from language bindings\n\nUsers of Pkl's language bindings also benefit from the new type.\nWhen using code generation, the `Bytes` data type will turn into the following types:\n\n|===\n|Language |Type\n\n|Java\n|`byte[]`\n\n|Kotlin\n|`ByteArray`\n\n|Go\n|`[]byte`\n\n|Swift\n|`[UInt8]`\n|===\n\nMaintainers of other language bindings are encouraged to map `Bytes` into the corresponding binary type in their language.\n\n==== `Bytes` versus `List`\n\nConceptually, `Bytes` is very similar to `List`, because both are data types that describe sequences of `UInt8` values.\nHowever, they have different performance characteristics.\nA `List` is a https://en.wikipedia.org/wiki/Persistent_data_structure[persistent data structure].\nThis means that creating modified copies of lists is very cheap.\n\nHowever, lists have more overhead per element.\nA `List` with 1000 elements takes up about 5.4 kilobytes of heap space, whereas the same data in `Bytes` takes roughly 1 kilobyte.\n\n=== HTTP Rewrites and Package Mirroring\n\nA new evaluator setting is introduced, which rewrites URLs before making outbound HTTP calls (https://github.com/apple/pkl/pull/1062[#1062], https://github.com/apple/pkl/pull/1127[#1127], https://github.com/apple/pkl/pull/1133[#1133]).\n\nThis setting can be configured via CLI flag `--http-rewrite`, and also in other ways:\n\n* A builder option in `org.pkl.core.EvaluatorBuilder`\n* A builder option in `org.pkl.executor.ExecutorOptions`\n* A new property in `CreateEvaluatorRequest` in the Message Passing API\n* A new property in the Gradle plugin\n* A new property in `pkl.EvaluatorSettings#Http`\n\nThe main use-case for this setting is to enable package mirroring.\nFor example, let's assume that the following mirrors exist:\n\n|===\n|Original |Mirror\n\n|\\https://pkg.pkl-lang.org\n|\\https://my.internal.mirror/pkg-pkl-lang\n\n|\\https://github.com\n|\\https://my.internal.mirror/github\n|===\n\nA user of the CLI can use these mirrors with the following settings.\n\n.~/.pkl/settings.pkl\n[source,pkl]\n----\namends \"pkl:settings\"\n\nhttp {\n rewrites {\n [\"https://pkg.pkl-lang.org/\"] = \"https://my.internal.mirror/pkg-pkl-lang/\"\n [\"https://github.com/\"] = \"https://my.internal.mirror/github/\"\n }\n}\n----\n\nTo learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0016-http-rewrites.adoc[SPICE-0016].\n\n== Noteworthy [small]#🎶#\n\nReady when you need them.\n\n=== pkldoc, pkl-codegen-java, pkl-codegen-kotlin executables\n\nThe pkldoc, pkl-config-java and pkl-config-kotlin CLIs are published as their own executables (https://github.com/apple/pkl/pull/1023[#1023]).\n\nCurrently, these tools have excellent support when called from within the pkl-gradle plugin.\nHowever, the story for using these as CLIs is much clunkier.\nUsers must call Java by including their published `.jar` files, as well as all of their dependencies via the `-classpath` argument.\n\nIn 0.29, they are all being published as executables.\nIn particular, pkldoc is being published as both a Java executable and a native executable.\nOn the other hand, pkl-codegen-java and pkl-codegen-kotlin are published as Java executables only.\n\nFor more information, see their download instructions:\n\n* xref:pkl-doc:index.adoc#install-cli[pkldoc]\n* xref:java-binding:codegen.adoc#install-cli[pkl-codegen-java]\n* xref:kotlin-binding:codegen.adoc#install-cli[pkl-codegen-kotlin]\n\n=== Java API changes\n\n==== Resource Readers SPI added to preconfigured evaluators\n\nA change was made to the preconfigured evaluators (https://github.com/apple/pkl/pull/1094[#1094]).\n\nCurrently, they add module key factories from service providers, but not resource readers.\n\nThis means that users of pkl-spring, for example, cannot add custom resource readers.\nThis is also inconsistent (in the preconfigured evaluator, import can use custom schemes, but not read).\n\nIn Pkl 0.29, any resource reader registered via the Service Provider Interface will be added to the preconfigured evalutors.\n\n==== New methods\n\nNew methods are introduced to the Java API.\n\n* `org.pkl.core.Evaluator.evaluateOutputBytes`\n* `org.pkl.core.http.HttpClient.Builder.setRewrites`\n* `org.pkl.core.http.HttpClient.Builder.addRewrite`\n* `org.pkl.executor.ExecutorOptions.httpRewrites`\n* `org.pkl.config.java.ConfigEvaluatorBuilder.getHttpClient`\n* `org.pkl.config.java.ConfigEvaluatorBuilder.setHttpClient`\n\n=== Standard Library changes\n\nNew properties, methods, classes and typealiases have been added to the standard library (https://github.com/apple/pkl/pull/1019[#1019], https://github.com/apple/pkl/pull/1053[#1053], https://github.com/apple/pkl/pull/1063[#1063], https://github.com/apple/pkl/pull/1144[#1144]).\n\n==== Additions to `pkl:base`\n\n* {uri-stdlib-String}#isBase64[`String.isBase64`]\n* {uri-stdlib-String}#base64DecodedBytes[`String.base64DecodedBytes`]\n* {uri-stdlib-String}#encodeToBytes()[`String.encodeToBytes()`]\n* {uri-stdlib-List}#mapNonNullIndexed()[`List.mapNonNullIndexed()`]\n* {uri-stdlib-List}#toBytes()[`List.toBytes()`]\n* {uri-stdlib-Set}#mapNonNullIndexed()[`Set.mapNonNullIndexed()`]\n* {uri-stdlib-FileOutput}#bytes[`FileOutput.bytes`]\n* {uri-stdlib-Resource}#bytes[`Resource.bytes`]\n* {uri-stdlib-Mapping}#getOrDefault()[`Mapping.getOrDefault()`]\n* {uri-stdlib-Listing}#getOrDefault()[`Listing.getOrDefault()`]\n* {uri-stdlib-baseModule}#Charset[`Charset`]\n* {uri-stdlib-Bytes}[`Bytes`]\n\n==== Additions to `pkl:EvaluatorSettings`\n\n* {uri-stdlib-evaluatorSettingsHttpClass}#rewrites[`Http.rewrites`]\n\n==== Additions to `pkl:reflect`\n\n* {uri-stdlib-reflectModule}#bytesType[`bytesType`]\n\n=== `pkl` CLI changes\n\nNew features are added to the `pkl` CLI (https://github.com/apple/pkl/pull/1052[#1052], https://github.com/apple/pkl/pull/1056[#1056]).\n\n==== Aggregated JUnit reports\n\nA new set of CLI flags are introduced: `--junit-aggregate-reports`, and `--junit-aggregate-suite-name`.\nCollectively, these flags tell Pkl to combine the JUnit reports into a single file, instead of creating a file per Pkl module.\n\nThanks to https://github.com/gordonbondon[@gordonbondon] for contributing to this feature!\n\n==== shell-completion subcommand\n\nA new subcommand called `shell-completion` has been added to the Pkl CLI.\n\nThis command produces autocompletion scripts for a given shell.\n\nThe following example installs shell completions for https://fishshell.com[fish shell]:\n\n[source,shellscript]\n----\npkl shell-completion fish > \"~/.config/fish/completions/pkl.fish\"\n----\n\nThanks to https://github.com/gordonbondon[@gordonbondon] for contributing to this feature!\n\n=== `@Generated` annotation for Java/Kotlin codegen\n\nClasses generated by the Java and Kotlin code generator can optionally receive new annotation called `Generated` (https://github.com/apple/pkl/pull/1075[#1075], https://github.com/apple/pkl/pull/1115[#1115]).\n\nThis behavior is toggled with the `--generated-annotation` CLI flag, or the similarly named Gradle property.\n\nWhen enabled, classes are annotated with `org.pkl.config.java.Generated`.\n\nThis allows users of JaCoCo to exclude Pkl-generated classes from coverage reports.\n\nThanks to https://github.com/arouel[@arouel] for their contributions here!\n\n== Breaking Changes [small]#💔#\n\nThings to watch out for when upgrading.\n\n=== Standard library deprecations\n\nThe following methods have been deprecated in the standard library:\n\n|===\n|Method name |Details\n\n|`Resource.md5`\n|Replaced with `Resource.bytes.md5`\n\n|`Resource.sha1`\n|Replaced with `Resource.bytes.sha1`\n\n|`Resource.sha256`\n|Replaced with `Resource.bytes.sha256`\n\n|`Resource.sha256Int`\n|Replaced with `Resource.bytes.sha256Int`\n|===\n\n=== Grammar changes\n\nNew rules have been introduced to the parser (https://github.com/apple/pkl/pull/1022[#1022], https://github.com/apple/pkl/pull/1126[#1126]).\n\n==== Block comment nesting is removed\n\nCurrently, block comments can be nested.\nFor example, the comment `/* /* my comment */ */` is two block comments; one outer comment and one inner comment.\n\nHowever, this has some drawbacks.\n\n1. Block comments can be possibly be closed incorrectly, like `/* /* my comment */`. However, this is a valid block comment in most languages.\n2. Pkl's syntax highlighters do not support block comment nesting, leading to highlighting that is inconsistent with Pkl's parser.\n\nTo improve user experience, block comment nesting is removed.\nAs a result, block comments are always terminated upon the first `*/`.\n\n==== Shebang line can only appear at the start of a file\n\nThe grammar around shebang comments has been made stricter. \n\nPkl files allow for a https://en.wikipedia.org/wiki/Shebang_(Unix)[shebang comment].\nCurrently, this comment can appear anywhere in a file.\nIn 0.29, this comment must appear at the start of a file.\n\n=== Opaque `file:` URIs are invalid\n\nA new rule is introduced to treat opaque `file:` URIs as errors (https://github.com/apple/pkl/pull/1087[#1087]).\n\nOpaque file URIs are URIs whose scheme-specific part does not start with `/`.\nFor example, `file:foo/bar.txt` is an opaque URI.\n\nCurrently, this has the unintentional behavior of: look for file `foo/bar.txt` from the process working directory.\nThese are effectively dynamics imports; from a single import, we can't statically determine what file is actually being imported.\n\nAccording to https://datatracker.ietf.org/doc/html/rfc8089#section-2[RFC-8089], `file` URIs must have paths that start with /.\nSo, these are actually not valid URIs.\n\nIn Pkl 0.29, it is an error to load a module or resource with an opaque `file:` URI.\n\nNOTE: 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\")`.\n\n[[new-base-module-names]]\n=== New base module names: `Bytes` and `Charset`\n\nTwo new names are introduced to the base module: `Bytes` and `Charset`.\nThat means that any code that currently references these names on implicit `this` will break (https://github.com/apple/pkl/pull/1019[#1019]).\n\nThe following snippet demonstrates this breaking behavior.\nIn 0.28 and below, `obj2.prop` resolves to string \"my bytes\".\nIn 0.29, it resolves to class `Bytes` in the base module.\n\n[source,pkl]\n----\nobj1 {\n Bytes = \"my bytes\"\n}\n\nobj2 = (obj1) {\n prop = Bytes\n}\n----\n\nTo make this code continue to have the same meaning, an explicit `this` reference is required.\n\n[source,diff]\n----\n obj1 {\n Bytes = \"my bytes\"\n }\n \n obj2 = (obj1) {\n- prop = Bytes\n+ prop = this.Bytes\n }\n----\n\nThis only affects code that references these names off of implicit this.\nCode that references the name from the lexical scope will continue to work as-is.\n\nTo learn more about name resolution, consult the xref:language-reference:index.adoc#name-resolution[language reference].\n\n=== jpkl is not published to Maven Central\n\nDue to a breakage in release pipeline, the `jpkl` executable is not published to Maven Central (https://github.com/apple/pkl/pull/1147[#1147]).\n\nIt is still available to download as a GitHub release asset.\n\n== Miscellaneous [small]#🐸#\n\n* Documentation improvements (https://github.com/apple/pkl/pull/1065[#1065], https://github.com/apple/pkl/pull/1127[#1127]).\n* Dependency updates (https://github.com/apple/pkl/pull/1088[#1088], https://github.com/apple/pkl/pull/1128[#1128], https://github.com/apple/pkl/pull/1139[#1139]).\n* Use `javac -release` and `kotlinc -Xjdk-release` compiler flags for improved bytecode compatibilty (https://github.com/apple/pkl/pull/1080[#1080]).\n* Parser improvements (https://github.com/apple/pkl/pull/1066[#1066]).\n\n== Bugs fixed [small]#🐜#\n\nThe following bugs have been fixed.\n\n* New parser fails on nested multi line comments (https://github.com/apple/pkl/issues/1014[#1014])\n* Fix package dependency links when generating pkldoc (https://github.com/apple/pkl/pull/1078[#1078])\n* Don't show 100% when number of failures is rounded up (https://github.com/apple/pkl/pull/1110[#1110])\n* Quoting the module name crashes pkl (https://github.com/apple/pkl/issues/1111[#1111])\n* Shebang comment parsing is too lenient (https://github.com/apple/pkl/issues/1125[#1125])\n* CLI: noProxy option in settings.pkl and PklProject are ignored (https://github.com/apple/pkl/issues/1142[#1142])\n\n== Contributors [small]#🙏#\n\nWe would like to thank the contributors to this release (in alphabetical order):\n\n* https://github.com/arouel[@arouel]\n* https://github.com/gordonbondon[@gordonbondon]\n* https://github.com/HT154[@HT154]\n* https://github.com/KushalP[@KushalP]\n* https://github.com/madrob[@madrob]\n* https://github.com/MikeSchulze[@MikeSchulze]\n* https://github.com/sitaktif[@sitaktif]\n* https://github.com/vlsi[@vlsi]\n" }, { "path": "docs/modules/release-notes/pages/0.30.adoc", "content": "= Pkl 0.30 Release Notes\n:version: 0.30\n:version-minor: 0.30.2\n:release-date: November 3rd, 2025\n\n:yaml-binary-scalar: https://yaml.org/type/binary.html\n\ninclude::ROOT:partial$component-attributes.adoc[]\n\nPkl {version} was released on {release-date}. +\n[.small]#The latest bugfix release is {version-minor}. (xref:changelog.adoc[All Versions])#\n\nThis release introduces a code formatter, and an in-language API for producing `pkl-binary` output.\n\nThe next release (0.31) is scheduled for February 2026.\nTo see what's coming in the future, follow the {uri-pkl-roadmap}[Pkl Roadmap].\n\nPlease 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]. +\n\n[small]#Pkl is hosted on https://github.com/apple/pkl[GitHub].\nTo get started, follow xref:pkl-cli:index.adoc#installation[Installation].#\n\n== Highlights [small]#💖#\n\n[[formatter]]\n=== Formatter\n\nPkl 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/1268[#1268], 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], https://github.com/apple/pkl/pull/1280[#1280], https://github.com/apple/pkl/pull/1283[#1283], https://github.com/apple/pkl/pull/1289[#1289], https://github.com/apple/pkl/pull/1290[#1290])!\n\nPkl's formatter is _canonical_, which means that it has a single set of formatting rules, with (almost) no configuration options.\nThe goal is to eliminate the possibility of formatting debates, which can lead to churn and bike-shedding.\n\nThe formatter is available both as a CLI subcommand and as a Java API.\n\nTo learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0014-canonical-formatter.adoc[SPICE-0014].\n\n==== Using the CLI\n\nThe Pkl formatter is available under the `pkl format` subcommand. By default, the command will concatenate and write all formatted content to standard out.\n\nTo simply check for formatting violations, getting formatted output on stdout is likely too verbose.\nThe `--silent` flag can be used to omit any output, and the <> can be used to determine\nif there are formatting violations.\n\n[source,shell]\n----\npkl format --silent . || echo \"Formatting violations were found!\"\n----\n\nAlternatively, the `--names` flag will print out the names of any files that have formatting violations.\n\n[source,shell]\n----\npkl format --diff-name-only .\n----\n\nTo apply formatting, use the `--write` (`-w`) flag.\nThis also implies the `--diff-name-only` flag.\n\n[source,shell]\n----\npkl format -w .\n----\n\n[[formatting-exit-codes]]\n==== Exit codes\n\nThe formatter will exit with the following codes:\n\n|===\n|Code |Description\n\n|0\n|No formatting violations were found.\n\n|1\n|Non-formatting errors occurred.\n\n|11\n|Formatting violations were found.\n|===\n\n==== Grammar version\n\nThe formatter can be configured with a _grammar version_, which maps to a Pkl version range.\n\n|===\n|Grammar version |Pkl versions\n\n|1\n|0.25 - 0.29\n\n|2\n|0.30+\n|===\n\nGrammar version 2 uses the newly introduced <> feature, and therefore is not compatible with existing versions of Pkl.\nTo ensure compatibility, use the `--grammar-version 1` CLI flag.\n\n[[binary-renderer-parser]]\n=== `pkl-binary` in-language Renderer\n\nA 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],\nhttps://github.com/apple/pkl/pull/1250[#1250], https://github.com/apple/pkl/pull/1275[#1275]).\n\nIt's sometimes useful to separate Pkl evaluation from data consumption when used as application or service configuration.\nThis is possible with the `pkl-binary` format, which is a lossless encoding of Pkl data.\n\nIn this approach, Pkl is first rendered into `pkl-binary` during build time, and then deserialized into classes and structs at startup time.\nThis means that the Pkl evaluator does not need to be shipped with the application, which improves code portability and eliminates runtime overhead.\n\nHowever, currently, the API for getting this binary format is somewhat cumbersome.\nOnly 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).\nThis means that one-off logic must be written to render this format in the host language.\n\nIn 0.30, this renderer is added as an in-language API, through the {uri-stdlib-pklbinaryModule}[`pkl:pklbinary`] standard library module.\nAdditionally, it is available through CLI flag `--format pkl-binary`.\n\nFor example:\n\n// this is parsed instead of tested because DocSnippetTests only handles textual output (via ReplServer)\n[source%parsed,pkl]\n----\nimport \"pkl:pklbinary\"\n\noutput {\n renderer = new pklbinary.Renderer {}\n}\n----\n\nTo learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0021-binary-renderer-and-parser.adoc[SPICE-0021].\n\n==== New renderer type: `BytesRenderer`\n\nTo enable the `pkl-binary` renderer feature, Pkl now supports renderers that produce `Bytes` output (https://github.com/apple/pkl/pull/1203[#1203]).\n\nThe existing `ValueRenderer` class now extends new class `BaseValueRenderer`, and a new `BytesRenderer` class is introduced.\n\nSetting a module's output renderer to a `BytesRenderer` will control its resulting `output.bytes`.\n\nThis affects usage scenarios where a module's `output.bytes` is evaluated, for example, when using `pkl eval`.\n\n==== Using `pkl-binary` data\n\nUsers of Pkl's language binding libraries can decode `pkl-binary` data into instances of code-generated types.\n\n[tabs]\n====\nJava::\n+\n[source,java]\n----\nvar encodedData = fetchEncodedData(); // some byte[] or InputStream\nvar config = Config.fromPklBinary(encodedData);\nvar appConfig = config.as(AppConfig.class);\n----\n\nKotlin::\n+\n[source,kotlin]\n----\nval encodedData = fetchEncodedData() // some ByteArray or InputStream\nval config = Config.fromPklBinary(encodedData, ValueMapper.preconfigured().forKotlin())\nval appConfig = config.to()\n----\n\nGo::\n+\n[source,go]\n----\nencodedData := fetchEncodedData() // some []byte\nvar appConfig AppConfig\nif err := pkl.Unmarshal(encodedData, &appConfig); err != nil {\n // handle error\n} \n----\n\nSwift::\n+\n[source,swift]\n----\nlet encodedData = fetchEncodedData() // some [UInt8]\nlet appConfig = try PklDecoder.decode(AppConfig.self, from: encodedData)\n----\n====\n\n== Noteworthy [small]#🎶#\n\n[[trailing-commas]]\n=== Trailing Commas\n\nPkl'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]).\n\nThese syntax elements are affected:\n\n[source%tested,pkl]\n----\nfunction add(\n bar,\n baz, // <1>\n) = bar + baz\n\nfoo = add(\n 1,\n 2, // <2>\n)\n\ntypealias MyMapping<\n Key,\n Value, // <3>\n> = Mapping\n\nbar: Mapping<\n String,\n Int, // <4>\n>\n\nbaz: Mapping(\n !containsKey(\"forbidden key\"),\n !containsKey(\"forbidden value\"), // <5>\n)\n\nqux: (\n String,\n Int, // <6>\n) -> Dynamic =\n (paramA, paramB) -> new Dynamic {\n quux = \"\\(paramA): \\(paramB)\"\n }\n\ncorge = (qux) {\n paramA,\n paramB, // <7>\n ->\n grault = paramA.length * paramB\n}\n----\n<1> Function parameter lists in method definitions.\n<2> Argument lists in method calls.\n<3> Type parameter lists in generic type definitions.\n<4> Type argument lists in type annotations and casts.\n<5> Type constraint lists.\n<6> Function type parameter lists in function type annotations.\n<7> Object body parameter lists.\n\nTo learn more about this change, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0019-trailing-commas.adoc[SPICE-0019].\n\n=== Pretty-printed traces\n\nA 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]).\n\nCurrently, the `trace()` operator will render values as a single line, and trims the output after 100 characters.\nThis can obscure information when debugging.\n\nIn 0.30, a new evaluator option is added to control how traces are emitted.\nTwo trace modes are introduced:\n\n* `compact` - the current output mode (default).\n* `pretty` - multiline, with no limit on output size.\n\nFor example, users of the CLI can specify `--trace-mode` as a flag.\n\n[source,shell]\n----\npkl eval --trace-mode pretty myModule.pkl \n----\n\nThanks to https://github.com/ssalevan[@ssalevan] for their contribution to this feature!\n\n=== Better support for `Bytes` when rendering YAML\n\nPreviously, attempting to render a `Bytes` value using {uri-stdlib-YamlRenderer}[`YamlRenderer`] required the use of a link:{uri-stdlib-PcfRenderer-converters}[converter].\nNow, Pkl can natively render YAML containing link:{yaml-binary-scalar}[binary scalars] (https://github.com/apple/pkl/pull/1276[#1276]).\n\n[source,pkl%tested]\n----\nfoo {\n bar = Bytes(1, 2, 3)\n}\n\nrendered = new YamlRenderer {}.renderValue(foo) // <1>\n----\n<1> Result: `bar: !!binary AQID`\n\nSimilarly, link:{uri-stdlib-YamlParser}[`yaml.Parser`] now parses binary YAML values as Pkl link:{uri-stdlib-Bytes}[`Bytes`] values (https://github.com/apple/pkl/pull/1277[#1277]).\nThis is a breaking change; previously these values were parsed as link:{uri-stdlib-String}[`String`] value containing the base64-encoded binary data.\n\n[source,pkl%tested]\n----\nimport \"pkl:yaml\"\n\nyamlData = \n \"\"\"\n bytes: !!binary AQID\n \"\"\"\n\nparsed = new yaml.Parser {}.parse(yamlData).bytes // <1>\n----\n<1> Result: `Bytes(1, 2, 3)`\n\n[[pkldoc-perf-improvements]]\n=== `pkldoc` performance improvements\n\nThe `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]).\n\nCurrently, the `pkldoc` tool needs to consume much of an existing documentation website whenever generating new documentation.\nThis adds significant I/O overhead as a pkldoc documentation website grows.\n\nThe generator has been overhauled to minimize the amount of data needed to be read from the current site.\n\nTo read more about this change, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0018-pkldoc-io-improvements.adoc[SPICE-0018].\n\n[[pkldoc-migration]]\n==== Migration\n\nThe new pkldoc website introduces breaking changes to the data model.\nBecause of this, existing sites must be migrated before using the `0.30` version of pkldoc.\n\nTo migrate, run the one-time command `pkldoc --migrate`.\n\n=== Java API changes\n\n==== New classes\n\nNew classes are introduced to the Java API.\n\n* `org.pkl.core.PklBinaryDecoder`\n\n==== New methods\n\nNew methods are introduced to the Java API.\n\n* `org.pkl.core.Evaluator.evaluateExpressionPklBinary`\n* `org.pkl.core.EvaluatorBuilder.setTraceMode`\n* `org.pkl.core.EvaluatorBuilder.getTraceMode`\n* `org.pkl.config.java.Config.fromPklBinary`\n\n=== Standard Library changes\n\nNew modules, properties, methods, classes and typealiases have been added to the standard library (https://github.com/apple/pkl/pull/1106[#1106]).\n\n==== Changes to `pkl:base`\n\nAdditions:\n\n* New class: {uri-stdlib-BaseValueRenderer}[`BaseValueRenderer`]\n* {uri-stdlib-ValueRenderer}[`ValueRenderer`] (now a subclass of {uri-stdlib-BaseValueRenderer}[`BaseValueRenderer`])\n* {uri-stdlib-BytesRenderer}[`BytesRenderer`]\n* {uri-stdlib-baseModule}/RenderDirective#bytes[`RenderDirective.bytes`]\n\n==== Additions to `pkl:EvaluatorSettings`\n\n* {uri-stdlib-evaluatorSettingsModule}#traceMode[`traceMode`]\n\n==== Additions to `pkl:reflect`\n\n* {uri-stdlib-reflectModule}/Class#allMethods[`Class.allMethods`]\n* {uri-stdlib-reflectModule}/Class#allProperties[`Class.allProperties`]\n* {uri-stdlib-reflectModule}/Property#allAnnotations[`Propterty.allAnnotations`]\n* {uri-stdlib-reflectModule}/Propterty#allModifiers[`Propterty.allModifiers`]\n\n==== New module: `pkl:pklbinary`\n\nThe `pkl:pklbinary` standard library module is added.\n\n=== `pkl repl` improvements\n\nThe REPL now handles interrupts (Ctrl-C) in a more user-friendly way (https://github.com/apple/pkl/pull/1188[#1188]).\n\nInstead of exiting immediately, it behaves like other REPLs:\n\n* If the line is non-empty or in a continuation, the buffer is cleared.\n* If the line is empty, print a message with instructions on exiting the REPL.\n** If another interrupt is sent immediately after, exit.\n\n== Breaking Changes [small]#💔#\n\nThings to watch out for when upgrading.\n\n=== Binary data handling `yaml.Parser`\n\nlink:{yaml-binary-scalar}[YAML binary scalars] are now parsed as link:{uri-stdlib-Bytes}[`Bytes`] values.\nPrior versions of Pkl parsed binary scalars as link:{uri-stdlib-String}[`String`] values containing the base64-encoded binary data.\n\n=== Minimum Kotlin version bump\n\nFor users of Pkl's Kotlin libraries, the minimum Kotlin version has been bumped to 2.1 (https://github.com/apple/pkl/pull/1232[#1232]).\n\n=== New base module names: `BaseValueRenderer`, `BytesRenderer`\n\nTwo new names are introduced to the base module: `BaseValueRenderer`, and `BytesRenderer`.\nThat means that any code that currently references these names on implicit `this` will break (https://github.com/apple/pkl/pull/1203[#1203]).\n\nTo 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.\n\n=== `pkldoc` sites need to be migrated\n\nDue to breaking changes made in pkldoc's data model, existing pkldoc websites must be migrated.\n\nSee <> for more details.\n\n== Miscellaneous [small]#🐸#\n\n* 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]).\n* 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], https://github.com/apple/pkl/pull/1278[#1278], https://github.com/apple/pkl/pull/1279[#1279]).\n* Add internal IntelliJ plugin that's meant to assist with development of the Pkl codebase itself (https://github.com/apple/pkl/pull/1248[#1248]).\n* Update CircleCI macOS instance type and Xcode version (https://github.com/apple/pkl/pull/1243[#1243], https://github.com/apple/pkl/pull/1244[#1244]).\n* Disable multi-jdk testing when running on Windows ARM (https://github.com/apple/pkl/pull/1223[#1223]).\n* Refine documentation for class `Any` (https://github.com/apple/pkl/pull/1194[#1194]).\n\n== Bugs fixed [small]#🐜#\n\nThe following bugs have been fixed.\n\n* Incorrect error message when refusing to read past root dir (https://github.com/apple/pkl/pull/1234[#1233]).\n* Unicode U+7FFF character (翿) incorrectly parsed as EOF (https://github.com/apple/pkl/pull/1251[#1251]).\n* Fallback certificates do not work in certain classloader setups (https://github.com/apple/pkl/pull/1198[#1199]).\n\n== Contributors [small]#🙏#\n\nWe would like to thank the contributors to this release (in alphabetical order):\n\n* https://github.com/bioball[@bioball]\n* https://github.com/HT154[@HT154]\n* https://github.com/netvl[@netvl]\n* https://github.com/spyoungtech[@spyoungtech]\n* https://github.com/srueg[@srueg]\n* https://github.com/ssalevan[@ssalevan]\n* https://github.com/stackoverflow[@stackoverflow]\n" }, { "path": "docs/modules/release-notes/pages/0.31.adoc", "content": "= Pkl 0.31 Release Notes\n:version: 0.31\n:version-minor: 0.31.0\n:release-date: February 26th, 2026\n:version-next: 0.32\n:version-next-date: July 2026\n\ninclude::partial$intro.adoc[]\n\n== Highlights [small]#💖#\n\n[[power-assertions]]\n=== Power Assertions\n\nPkl's test output and error output has been improved with power assertions (pr:https://github.com/apple/pkl/pull/1384[], pr:https://github.com/apple/pkl/pull/1419[])!\n\nPkl has two places that are effectively assertions.\nThese are:\n\n* Type constraint expressions\n* Test facts\n\nCurrently, when these assertions fail, the error message prints the assertion's source section.\nHowever, this information can sometimes be lacking.\nIt tells you what the mechanics of the assertion is, but doesn't tell you _why_ the assertion is failing.\n\nFor example, here is the current error output of a failing typecheck.\n\n[source,text]\n----\n–– Pkl Error ––\nType constraint `name.endsWith(lastName)` violated.\nValue: new Person { name = \"Bub Johnson\" }\n\n7 | passenger: Person(name.endsWith(lastName)) = new { name = \"Bub Johnson\" }\n----\n\nJust from this error message, we don't know what the last name is supposed to be.\nWhat is `name` supposed to end with?\nWe just know it's some property called `lastName` but, we don't know what it _is_.\n\nIn Pkl 0.31, the error output becomes:\n\n[source,text]\n----\n–– Pkl Error ––\nType constraint `name.endsWith(lastName)` violated.\nValue: new Person { name = \"Bub Johnson\" }\n\n name.endsWith(lastName)\n │ │ │\n │ false \"Smith\"\n \"Bub Johnson\"\n\n7 | passenger: Person(name.endsWith(lastName)) = new { name = \"Bub Johnson\" }\n----\n\nNow, we know what the expectation is.\n\nThis type of diagram is also added to test facts.\nWhen tests fail, Pkl emits a diagram of the expression, and the values produced.\n\nFor example, given the following test:\n\n.math.pkl\n[source,pkl]\n----\namends \"pkl:test\"\n\nfacts {\n local function add(a: Int, b: Int) = a * b\n local function divide(a: Int, b: Int) = a % b\n [\"math\"] {\n add(3, 4) == 7\n divide(8, 2) == 4\n }\n}\n----\n\nThe error output now includes a power assertion diagram, which helps explain why the test failed.\n\n[source,text]\n----\nmodule math\n facts\n ✘ math\n add(3, 4) == 7 (math.pkl:9)\n │ │\n 12 false\n divide(8, 2) == 4 (math.pkl:10)\n │ │\n 0 false\n\n0.0% tests pass [1/1 failed], 0.0% asserts pass [2/2 failed]\n----\n\nTo learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0026-power-assertions.adoc[SPICE-0026].\n\n[[cli-framework]]\n=== CLI Framework\n\nPkl 0.31 introduces a new framework for implementing CLI tools in Pkl (pr:https://github.com/apple/pkl/pull/1367[], pr:https://github.com/apple/pkl/pull/1431[], pr:https://github.com/apple/pkl/pull/1432[], pr:https://github.com/apple/pkl/pull/1436[], pr:https://github.com/apple/pkl/pull/1440[], pr:https://github.com/apple/pkl/pull/1444[]).\n\nThe framework provides a way to build command line tools with user experience idioms that will be immediately familiar to users.\nCLI tools implemented in Pkl have largely the same capabilities as normal Pkl evaluation (i.e. writing to standard output and files), but this may be extended using xref:language-reference:index.adoc#external-readers[external readers].\n\nCommands are defined by extending the pkldoc:#[pkl:Command] module:\n\n.bird-generator.pkl\n[source,pkl]\n----\nextends \"pkl:Command\"\n\noptions: Options\n\nclass Options {\n /// Mapping of = pairs defining the list of birds.\n @Argument\n birds: Mapping\n\n /// Aggregation function to apply to all bird ages.\n aggregate: *\"sum\" | \"mean\" | \"count\"\n}\n\nclass Bird {\n /// Name of the bird.\n name: String\n\n /// Age of the bird in years.\n age: Number\n}\n\nbirds: Listing = new {\n for (_name, _age in options.birds) {\n new { name = _name; age = _age }\n }\n}\n\nresult: Number =\n if (options.aggregate == \"sum\")\n birds.toList().fold(0.0, (result, bird) -> result + bird.age)\n else if (options.aggregate == \"mean\")\n birds.toList().fold(0.0, (result, bird) -> result + bird.age) / birds.length\n else\n birds.length\n----\n\nCommands are executed using the `pkl run` CLI subcommand:\n\n[source,bash]\n----\n$ pkl run bird-generator.pkl pigeon --aggregate=mean Pigeon=1 Hawk=8 Eagle=3\nbirds {\n new {\n name = \"Pigeon\"\n age = 1\n }\n new {\n name = \"Hawk\"\n age = 8\n }\n new {\n name = \"Eagle\"\n age = 3\n }\n}\nresult = 4.0\n----\n\nAutomatic CLI help is provided:\n\n[source,bash]\n----\n$ pkl run test.pkl -h\nUsage: test.pkl [] []... []...\n\nOptions:\n --aggregate= Aggregation function to apply to all bird ages.\n -h, --help Show this message and exit\n\nArguments:\n Mapping of = pairs defining the list of birds.\n----\n\nTo learn more about this feature, consult xref:pkl-cli:index.adoc#cli-tools[the documentation] and https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0025-pkl-run-cli-framework.adoc[SPICE-0025].\n\n== Noteworthy [small]#🎶#\n\n=== Syntax Highlighting\n\nThe Pkl CLI displays Pkl code in several locations: stack frames within errors messages, <>, and in the xref:pkl-cli:index.adoc#repl[REPL].\nThis code is now syntax highlighted to improve readability (pr:https://github.com/apple/pkl/pull/1385[], pr:https://github.com/apple/pkl/pull/1409[]):\n\nimage::syntax-highlight-error.png[syntax highlighted output]\n\n[[cli-dependency-notation]]\n=== CLI Support for Dependency Notation\n\nThe Pkl CLI now supports specifying modules using xref:language-reference:index.adoc#project-dependencies[dependency notation] (pr:https://github.com/apple/pkl/pull/1434[], pr:https://github.com/apple/pkl/pull/1439[]).\nThis is especially helpful for <> defined in Packages:\n\n[source,bash]\n----\n$ pkl run @my-tool/cmd.pkl ...\n----\n\nThis enhancement applies to the `pkl eval`, `pkl run`, `pkl test`, and `pkl analyze imports` commands.\nIt also applies to the `pkldoc`, `pkl-codegen-java`, and `pkl-codegen-kotlin` tools.\n\n[NOTE]\nDependency notation only works for remote package dependencies. xref:language-reference:index.adoc#local-dependencies[Local dependencies] are not supported.\n\n=== Property Converter Annotations\n\nPkl provides the pkldoc:BaseValueRenderers#converters[] mechanism for transforming values during rendering.\nConverters are flexible, but their design makes some transformations awkward.\nIn particular, modifying property names during rendering required a lot of extra code.\n\nThe new pkldoc:ConvertProperty[] annotation adds a way to express parameterized per-property name and value transformations (pr:https://github.com/apple/pkl/pull/1333[]).\n\nTo learn more about this feature, consult https://github.com/apple/pkl-evolution/blob/main/spices/SPICE-0024-annotation-converters.adoc[SPICE-0024].\n\nAdditional new Pkl APIs for per-format property renaming will be added for many built-in renderers:\n\n.fmt.pkl\n[source,pkl]\n----\nimport \"pkl:json\"\nimport \"pkl:yaml\"\n\n@json.Property { name = \"foo_bar\" }\n@yaml.Property { name = \"foo-bar\" }\nfooBar: String = \"hello world\"\n----\n\n[source,terminaloutput]\n----\n$ pkl eval fmt.pkl -f json\n{\n \"foo_bar\": \"hello world\"\n}\n\n$ pkl eval fmt.pkl -f yaml\nfoo-bar: hello world\n----\n\n=== Java API changes\n\n==== New classes\n\nNew classes are introduced to the Java API.\n\n* `org.pkl.core.CommandSpec`\n\n==== New methods\n\nNew methods are introduced to the Java API.\n\n* `org.pkl.core.Evaluator.evaluateCommand`\n* `org.pkl.core.EvaluatorBuilder.setPowerAssertionsEnabled`\n* `org.pkl.core.EvaluatorBuilder.getPowerAssertionsEnabled`\n* `org.pkl.core.SecurityManager.resolveSecurePath`\n* `org.pkl.config.java.ConfigEvaluator.evaluateOutputValue`\n* `org.pkl.coznfig.java.ConfigEvaluator.evaluateExpression`\n\n=== Standard Library changes\n\nNew properties have been added to the standard library (pr:https://github.com/apple/pkl/pull/1396[]).\n\n==== Additions to `pkl:base`\n\n* pkldoc:List#isNotEmpty[]\n* pkldoc:Map#isNotEmpty[]\n* pkldoc:Set#isNotEmpty[]\n* pkldoc:Listing#isNotEmpty[]\n* pkldoc:Mapping#isNotEmpty[]\n* pkldoc:String#isNotEmpty[]\n* pkldoc:String#isNotBlank[]\n* pkldoc:ConvertProperty[]\n* pkldoc:BaseValueRenderer#convertPropertyTransformers[]\n\n==== New module `pkl:Command`\n\nThe pkldoc:#[pkl:Command] standard library module is added.\n\n==== Additions to `pkl:json`\n\n* pkldoc:Property[pkl:json]\n\n==== Additions to `pkl:jsonnet`\n\n* pkldoc:Property[pkl:jsonnet]\n\n==== Additions to `pkl:protobuf`\n\n* pkldoc:Property[pkl:protobuf]\n\n==== Additions to `pkl:xml`\n\n* pkldoc:Property[pkl:xml]\n\n==== Additions to `pkl:yaml`\n\n* pkldoc:Property[pkl:yaml]\n\n== Breaking Changes [small]#💔#\n\nThings to watch out for when upgrading.\n\n=== Removal of `@argfile` support\n\nPrior versions of Pkl had an undocumented feature allowing inclusion of CLI arguments from files using `@path/to/file`.\nIn order to support <> on the CLI, `@argfile` support has been removed from Pkl.\n\n=== Removal of `Collection#transpose()`\n\nPrior versions of Pkl defined a `transpose()` method on the `Collection` class.\nThis method was never implemented and threw an error when called.\nAs it was never functional, it has been removed entirely without a deprecation warning (pr:https://github.com/apple/pkl/pull/1437[]).\n\n== Miscellaneous [small]#🐸#\n\n* Improve formatting of imports to keep surrounding comments (pr:https://github.com/apple/pkl/pull/1424[]).\n* Add support for evaluating module output and expressions to `ConfigEvaluator` (pr:https://github.com/apple/pkl/pull/1297[]).\n* The `pkl format --write` command now exits successfully when formatting violations are found and updated (pr:https://github.com/apple/pkl/pull/1340[]).\n* Add `pkl-bom` module to aid in aligning Pkl Java dependencies (pr:https://github.com/apple/pkl/pull/1390[]).\n* Improve error message when writing `PklProject.deps.json` fails (pr:https://github.com/apple/pkl/pull/1405[]).\n* Add information about pkldoc:Annotation[]s to the language reference (pr:https://github.com/apple/pkl/pull/1427[]).\n* Improved usability for the `org.pkl.formatter.Formatter` Java API (pr:https://github.com/apple/pkl/pull/1428[]).\n\n== Bugs fixed [small]#🐜#\n\nThe following bugs have been fixed.\n\n* `Function.toString()` returns incorrect result (pr:https://github.com/apple/pkl/pull/1411[]).\n* Failure when `--multiple-file-output-path` is a symlink (pr:https://github.com/apple/pkl/pull/1389[]).\n* The `module` type in a non-final module has default value of type `Dynamic` (pr:https://github.com/apple/pkl/pull/1392[]).\n* The `module` type is cached incorrectly in some cases (pr:https://github.com/apple/pkl/pull/1393[]).\n* A possible race condition involving symlinks could bypass `--root-dir` during module and resource reading (pr:https://github.com/apple/pkl/pull/1426[]).\n* `pkl format` produces internal stack traces when lexing fails (pr:https://github.com/apple/pkl/pull/1430[]).\n* `super` access expressions are parsed incorrectly inside the spread operator (pr:https://github.com/apple/pkl/pull/1364[]).\n* Modules and resources with `jar:file:` URIs were not properly sandboxed by `--root-dir` (pr:https://github.com/apple/pkl/pull/1442[]).\n\n== Contributors [small]#🙏#\n\nWe would like to thank the contributors to this release (in alphabetical order):\n\n* https://github.com/bioball[@bioball]\n* https://github.com/eddie4941[@eddie4941]\n* https://github.com/HT154[@HT154]\n* https://github.com/stackoverflow[@stackoverflow]\n* https://github.com/StefMa[@StefMa]\n" }, { "path": "docs/modules/release-notes/pages/0.32.adoc", "content": "= Pkl 0.32.0 Release Notes\n:version: 0.32\n:version-minor: 0.32.0\n:release-date: TBD\n:version-next: 0.33\n:version-next-date: TBD\n\ninclude::partial$intro.adoc[]\n\n== Highlights [small]#💖#\n\nNews you don't want to miss.\n\n.XXX\n[%collapsible]\n====\nXXX\n====\n\n== Noteworthy [small]#🎶#\n\nReady when you need them.\n\n.XXX\n[%collapsible]\n====\nXXX\n====\n\n== Breaking Changes [small]#💔#\n\nThings to watch out for when upgrading.\n\n.XXX\n[%collapsible]\n====\nXXX\n====\n\n== Work In Progress [small]#🚆#\n\nThey missed the train but deserve a mention.\n\n.XXX\n[%collapsible]\n====\nXXX\n====\n\n== Contributors [small]#🙏#\n\nWe would like to thank the contributors to this release (in alphabetical order):\n\n* XXX\n" }, { "path": "docs/modules/release-notes/pages/changelog.adoc", "content": "= Changelog\ninclude::ROOT:partial$component-attributes.adoc[]\n\n[[release-0.32.0]]\n== 0.32.0 (UNRELEASED)\n\n[[release-0.31.0]]\n== 0.31.0 (2026-02-26)\n\nxref:0.31.adoc[Release Notes]\n[[release-0.30.2]]\n\n== 0.30.2 (2025-12-15)\n\n=== Fixes\n\n* Fixes formatting of blank files (https://github.com/apple/pkl/pull/1351[#1351]).\n* Fixes an issue where the `pkl format` CLI command adds an extra newline when writing formatted content to standard output (https://github.com/apple/pkl/issues/1346[#1346]).\n* Make linux executables link to glibc 2.17 (https://github.com/apple/pkl/pull/1352[#1352]).\n* Fix incorrect parsing of super expressions (https://github.com/apple/pkl/pull/1364[#1364]).\n\n=== Contributors ❤️\n\nThank you to all the contributors for this release!\n\n* https://github.com/bioball[@bioball]\n* https://github.com/HT154[@HT154]\n* https://github.com/stackoverflow[@stackoverflow]\n\n[[release-0.30.1]]\n== 0.30.1 (2025-12-03)\n\n=== Fixes\n\n* Fixes formatting of `Map` constructors with line comments (https://github.com/apple/pkl/pull/1312[#1312]).\n* Fixes a crash when parsing empty parenthesized types (https://github.com/apple/pkl/pull/1323[#1323]).\n* Fixes a parser issue allowing too many newlines between tokens (https://github.com/apple/pkl/pull/1328[#1328]).\n* Fixes parsing of URIs with schemes containing `+`, `-`, or `.` (https://github.com/apple/pkl/pull/1335[#1335]).\n* Fixes a crash when creating very large `List` instances (https://github.com/apple/pkl/pull/1337[#1337]).\n\n=== Contributors ❤️\n\nThank you to all the contributors for this release!\n\n* https://github.com/bioball[@bioball]\n* https://github.com/HT154[@HT154]\n* https://github.com/spyoungtech[@spyoungtech]\n* https://github.com/stackoverflow[@stackoverflow]\n\n[[release-0.30.0]]\n== 0.30.0 (2025-10-30)\n\nxref:0.30.adoc[Release notes]\n\n[[release-0.29.1]]\n== 0.29.1 (2025-08-27)\n\n=== Fixes\n\n* Fixes an issue where autocompletion in Bash and ZSH do noes not suggest filenames (https://github.com/apple/pkl/pull/1161[#1161]).\n* Fixes an issue where `pkldoc` throws a runtime error about failing to load class path resources (https://github.com/apple/pkl/issues/1174[#1174]).\n* Fixes an issue where `pkldoc` always runs with `testMode` set to true.\n* Fixes an issue where evaluating a module that ends with an unmatched backtick throws `ArrayIndexOutOfBoundsException` (https://github.com/apple/pkl/issues/1182[#1182]).\n* Fixes the formatting of YAML strings when emitting backslash characters within quoted strings (https://github.com/apple/pkl/pull/1165[#1165]).\n* Fixes an issue where `local` members inside `Mapping` objects are incorrectly encoded into binary format (https://github.com/apple/pkl/issues/1151[#1151]).\n\n=== Contributors ❤️\n\nThank you to all the contributors for this release!\n\n* https://github.com/bioball[@bioball]\n* https://github.com/gordonbondon[@gordonbondon]\n* https://github.com/HT154[@HT154]\n\n[[release-0.29.0]]\n== 0.29.0 (2025-07-24)\n\nxref:0.29.adoc[Release notes]\n\n[[release-0.28.2]]\n== 0.28.2 (2025-04-17)\n\n=== Fixes\n\n* Adds an optimization when object bodies with generators produce no members (https://github.com/apple/pkl/pull/1013[#1013]).\n* Fixes a runtime crash when `--output-path` points to a directory (https://github.com/apple/pkl/pull/1038[#1038]).\n* Fixes a bug that sometimes causes pkl-doc to crash (https://github.com/apple/pkl/pull/1028[#1028]).\n\n=== Miscellaneous\n\n* Documentation improvements (https://github.com/apple/pkl/pull/982[#982], https://github.com/apple/pkl/pull/1010[#1010], https://github.com/apple/pkl/pull/1031[#1031]).\n* CI improvements (https://github.com/apple/pkl/pull/1020[#1020]).\n\n=== Contributors ❤️\n\nThank you to all the contributors for this release!\n\n* https://github.com/JeroenSoeters[@JeroenSoeters]\n* https://github.com/KushalP[@KushalP]\n* https://github.com/mbvissers[@mbvissers]\n* https://github.com/pepicrft[@pepicrft]\n\n[[release-0.28.1]]\n== 0.28.1 (2025-03-03)\n\n=== Fixes\n\n* Fixes an issue where Pkl Gradle tasks can possibly fail with `java.lang.UnsatisfiedLinkError` (https://github.com/apple/pkl/pull/995[#995]).\n* Fixes an issue where the artifacts pkl-tools and pkl-config-java-all fail with `java.lang.ClassFormatError` (https://github.com/apple/pkl/pull/998[#998]).\n\n=== Changes\n\n* Adds the ability to configure `native-image` build with Gradle system properties (https://github.com/apple/pkl/pull/1001[#1001]).\n+\nNow, any system property starting with `\"pkl.native\"` will have that prefix stripped, and the rest passed as CLI arguments to `native-image`. For example, the native-image resource cache can be configured by passing Gradle flag `-Dpkl.native-Dpolyglot.engine.userResourceCache=/my/cache/dir`.\n\n[[release-0.28.0]]\n== 0.28.0 (2025-02-26)\n\nxref:0.28.adoc[Release notes]\n\n[[release-0.27.2]]\n== 0.27.2 (2025-01-22)\n\n=== Fixes\n\n* Fixes issues where server mode message decoding might result in null pointer exceptions (https://github.com/apple/pkl/pull/853[#853], https://github.com/apple/pkl/pull/882[#882]).\n* Fixes an issue where the test report outputs decimal numbers using local-specific decimals (https://github.com/apple/pkl/pull/868[#868]).\n* Fixes an issue where the native executables might not run on some environments, resulting in an error like \"Fatal error: Failed to create the main Isolate\" (https://github.com/apple/pkl/pull/875[#875]).\n\n=== Contributors ❤️\n\nThank you to all the contributors for this release!\n\n* link:https://github.com/HT154[@HT154]\n* link:https://github.com/StefMa[@StefMa]\n\n[[release-0.27.1]]\n== 0.27.1 (2024-12-06)\n\n=== Fixes\n\n- Fixes a broken \"number literals\" link in the 0.27 release notes (https://github.com/apple/pkl/pull/784[#784]).\n- Fixes a possible deadlock during external reader process close (https://github.com/apple/pkl/pull/786[#786]).\n- Fixes counting elements with computed indices multiple times in length computation of listings (https://github.com/apple/pkl/pull/797[#797]).\n- Fixes non Pkl modules being reported in GatherImports task, leading to plugin failures (https://github.com/apple/pkl/pull/821[#821]).\n- Fixes a problem where the delegate chain of type casts for Listing/Mapping get unreasonably big, even though the type nodes are the same, which may lead to a stack overflow or performance degradation (https://github.com/apple/pkl/pull/826[#826]).\n- Fixes incorrect scoping of type variables in lazy Listing/Mapping type checking in cross-module typealiases (https://github.com/apple/pkl/pull/789[#789]).\n- Fixes regression in type checking logic for Listing/Mapping (https://github.com/apple/pkl/pull/789[#789]).\n\n=== Contributors ❤️\n\nThank you to all the contributors for this release!\n\n* link:https://github.com/GUI[@GUI]\n* link:https://github.com/HT154[@HT154]\n* link:https://github.com/odenix[@odenix] (formerly @translatenix)\n\n\n[[release-0.27.0]]\n== 0.27.0 (2024-11-05)\n\nxref:0.27.adoc[Release notes]\n\n[[release-0.26.3]]\n== 0.26.3 (2024-08-06)\n\n=== Fixes\n\n* Fixes an issue where CLI argument `--property foo=\"\"` is effectively parsed as `--property foo=\"true\"`. This is now parsed as an empty string (https://github.com/apple/pkl/pull/596[#596]).\n* Fixes a regression where amending a globbed import or globbed read results in a PklBugException (https://github.com/apple/pkl/pull/607[#607]).\n* Fixes an issue around using `file()` notation when using the pkl-gradle plugin on Windows (https://github.com/apple/pkl/pull/611[#611]).\n\n[[release-0.26.2]]\n== 0.26.2 (2024-07-18)\n\n=== Fixes\n\n* Fixes a possible race condition where multiple concurrent Pkl evaluations results in a thrown exception when downloading packages (https://github.com/apple/pkl/pull/584[#584]).\n\n[[release-0.26.1]]\n== 0.26.1 (2024-06-28)\n\n=== Fixes\n\n* Fixes a regression where native executables fail to run on some environments that don't support newer CPU features (https://github.com/apple/pkl/pull/551[#551]).\n* Fixes a `PklBugException` when passing `.` as a project directory to `pkl project resolve` and `pkl project package` (https://github.com/apple/pkl/pull/544[#544]).\n\n=== Changes\n\n* Disable revocation checking of TLS certificates (https://github.com/apple/pkl/pull/553[#553]).\n+\nAs part of HTTP improvements in 0.26, we unwittingly fixed a bug where Pkl does not actually perform cert revocation checks when making HTTPS requests.\nThis fix, unfortunately, caused a regression in some cases.\nFor example, this happens when connecting to a server that bears a public trust certificate, while in an environment with no internet access.\nThis is because the HTTP client needs to check the revocation status of all certificates in the chain.\n+\nRevocation checks are a nuanced topic with some benefits, and also with its own problem areas.\nFor this reason, revocation checking is disabled for Pkl's native CLIs.\nUsers of Pkl's Java APIs will respect the revocation settings set in the JVM.\n\n[[release-0.26.0]]\n== 0.26.0 (2024-06-17)\n\nxref:0.26.adoc[Release notes]\n\n[[release-0.25.3]]\n== 0.25.3 (2024-03-26)\n\n=== Fixes\n\n* Fixes some issues with generated pkldoc websites (link:https://github.com/apple/pkl/pull/357[#357], link:https://github.com/apple/pkl/pull/362[#362])\n* Fixes a bug where amending a module that defines an abstract class might cause a Java `AssertionError` (link:https://github.com/apple/pkl/pull/319[#319])\n* Fixes a bug where a for/when generator within a lambda declared with `new {}` syntax might not resolve variables correctly (link:https://github.com/apple/pkl/pull/297[#297])\n* Fixes a bug where `const` and `local` modifiers are not exported when obtaining a class's mirror in `pkl:reflect` (link:https://github.com/apple/pkl/pull/265[#265]).\n\n=== Miscellaneous\n\n* Documentation improvements (link:https://github.com/apple/pkl/pull/93[#93], link:https://github.com/apple/pkl/pull/106[#106], link:https://github.com/apple/pkl/pull/143[#143], link:https://github.com/apple/pkl/pull/205[#205], link:https://github.com/apple/pkl/pull/214[#214], link:https://github.com/apple/pkl/pull/224[#224], link:https://github.com/apple/pkl/pull/257[#257], link:https://github.com/apple/pkl/pull/270[#270], link:https://github.com/apple/pkl/pull/282[#282], link:https://github.com/apple/pkl/pull/283[#283], link:https://github.com/apple/pkl/pull/299[#299], link:https://github.com/apple/pkl/pull/337[#337], link:https://github.com/apple/pkl/pull/340[#340])\n* Build script improvements (link:https://github.com/apple/pkl/pull/253[#253], link:https://github.com/apple/pkl/pull/314[#314], link:https://github.com/apple/pkl/pull/333[#333], link:https://github.com/apple/pkl/pull/338[#338])\n\n=== Changes\n\n* Add `jpkl` to the set of artifacts released to GitHub (link:https://github.com/apple/pkl/pull/314[#314])\n\n=== Contributors ❤️\n\nThank you to all the contributors for this release!\n\n* link:https://github.com/r1ft1[@r1ft1]\n* link:https://github.com/WardsParadox[@WardsParadox]\n* link:https://github.com/grantabbott[@grantabbott]\n* link:https://github.com/mshakhmaykin[@mshakhmaykin]\n* link:https://github.com/d4wae89d498[@d4wae89d498]\n* link:https://github.com/KushalP[@KushalP]\n* link:https://github.com/zihluwang[@zihluwang]\n* link:https://github.com/Malix-off[@Malix-off]\n\n[[release-0.25.2]]\n== 0.25.2 (2024-02-08)\n\n=== Fixes\n\n* Fixes some issues with generated pkldoc websites (link:https://github.com/apple/pkl/pull/70[#70],\nlink:https://github.com/apple/pkl/pull/81[#81], link:https://github.com/apple/pkl/pull/96[#96])\n* Fixes an issue where a PklBugException produces an incorrect URL to file issues (link:https://github.com/apple/pkl/pull/73[#73])\n\n=== Miscellaneous\n\n* Documentation fixes (link:https://github.com/apple/pkl/pull/21[#21], link:https://github.com/apple/pkl/pull/29[#29], link:https://github.com/apple/pkl/pull/41[#41], link:https://github.com/apple/pkl/pull/44[#44], link:https://github.com/apple/pkl/pull/51[#51], link:https://github.com/apple/pkl/pull/57[#57], link:https://github.com/apple/pkl/pull/60[#60], link:https://github.com/apple/pkl/pull/64[#64], link:https://github.com/apple/pkl/pull/68[#68], link:https://github.com/apple/pkl/pull/74[#74], link:https://github.com/apple/pkl/pull/77[#77], link:https://github.com/apple/pkl/pull/78[#78], link:https://github.com/apple/pkl/pull/82[#82], link:https://github.com/apple/pkl/pull/84[#84], link:https://github.com/apple/pkl/pull/86[#86], link:https://github.com/apple/pkl/pull/89[#89], link:https://github.com/apple/pkl/pull/91[#91], link:https://github.com/apple/pkl/pull/104[#104])\n* Build script improvements (https://github.com/apple/pkl/pull/53[#53], link:https://github.com/apple/pkl/pull/83[#83])\n\n=== Contributors ❤️\n\nThank you to all the contributors for this release!\n\n* link:https://github.com/uhooi[@uhooi]\n* link:https://github.com/mnin[@mnin]\n* link:https://github.com/TinkoLiu[@TinkoLiu]\n* link:https://github.com/shufanhao[@shufanhao]\n* link:https://github.com/pfeilbr[@pfeilbr]\n* link:https://github.com/KadoBOT[@KadoBOT]\n* link:https://github.com/KushalP[@KushalP]\n* link:https://github.com/translatenix[@translatenix]\n* link:https://github.com/Edward-Knight[@Edward-Knight]\n* link:https://github.com/jamesward[@jamesward]\n* link:https://github.com/shubhgng[@shubhgng]\n* link:https://github.com/hayashikun[@hayashikun]\n* link:https://github.com/lanzafame[@lanzafame]\n* link:https://github.com/igmrrf[@igmrrf]\n* link:https://github.com/kelvinelove[@kelvinelove]\n* link:https://github.com/lilyball[@lilyball]\n* link:https://github.com/maiph[@maiph]\n\n[[release-0.25.1]]\n== 0.25.1 (2024-02-01)\n\n=== Fixes\n\n* Fixes an issue where pkl-tools fat jar is empty.\n\n[[release-0.25.0]]\n== 0.25.0 (2024-02-01)\n\nxref:0.25.adoc[Release notes]\n" }, { "path": "docs/modules/release-notes/pages/index.adoc", "content": "= Release Notes\n\nThe Pkl team aims to release a new version of Pkl in February, June, and October of each year.\n\n* xref:0.32.adoc[0.32 Release Notes]\n* xref:0.31.adoc[0.31 Release Notes]\n* xref:0.30.adoc[0.30 Release Notes]\n* xref:0.29.adoc[0.29 Release Notes]\n* xref:0.28.adoc[0.28 Release Notes]\n* xref:0.27.adoc[0.27 Release Notes]\n* xref:0.26.adoc[0.26 Release Notes]\n* xref:0.25.adoc[0.25 Release Notes]\n* xref:changelog.adoc[Changelog]\n" }, { "path": "docs/modules/release-notes/partials/intro.adoc", "content": "include::ROOT:partial$component-attributes.adoc[]\n\nPkl {version} was released on {release-date}. +\n[.small]#The latest bugfix release is {version-minor}. (xref:changelog.adoc[All Versions])#\n\nThe next release ({version-next}) is scheduled for {version-next-date}.\nTo see what's coming in the future, follow the {uri-pkl-roadmap}[Pkl Roadmap].\n\nPlease 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]. +\n\n[small]#Pkl is hosted on https://github.com/apple/pkl[GitHub].\nTo get started, follow xref:pkl-cli:index.adoc#installation[Installation].#\n" }, { "path": "docs/modules/release-notes/template.adoc", "content": "= Pkl XXX Release Notes\n:version: XXX (e.g., 0.9)\n:version-minor: XXX (e.g., 0.9.0)\n:release-date: XXX (e.g., July 11, 2018)\n:version-next: XXX (e.g., 0.10)\n:version-next-date: XXX (e.g., July 2018)\n\ninclude::partial$intro.adoc[]\n\n== Highlights [small]#💖#\n\nNews you don't want to miss.\n\n.XXX\n[%collapsible]\n====\nXXX\n====\n\n== Noteworthy [small]#🎶#\n\nReady when you need them.\n\n.XXX\n[%collapsible]\n====\nXXX\n====\n\n== Breaking Changes [small]#💔#\n\nThings to watch out for when upgrading.\n\n.XXX\n[%collapsible]\n====\nXXX\n====\n\n== Work In Progress [small]#🚆#\n\nThey missed the train but deserve a mention.\n\n.XXX\n[%collapsible]\n====\nXXX\n====\n\n== Contributors [small]#🙏#\n\nWe would like to thank the contributors to this release (in alphabetical order):\n\n* XXX\n" }, { "path": "docs/modules/style-guide/pages/index.adoc", "content": "= Pkl Style Guide\n:icons: font\n:source-highlighter: highlight.js\n:pkl-expr: pkl expression\n:pkl: pkl\n:sectnums:\n\nThis document serves as the Pkl team's recommended coding standard for the Pkl configuration language.\n\n== Files\n\n=== Filename\n\nUse the `.pkl` extension for all files.\n\nFollow these rules for casing the file's name:\n\n[cols=\"1,3,1\"]\n|===\n| Casing | Description | Example\n| PascalCase\n| It is designed to be used as a template, or used as a class (i.e. imported and instantiated).\n| `K8sResource.pkl`\n| camelCase\n| It is designed to be used as a value.\n| `myDeployment.pkl`\n| kebab-case\n| It is designed to be used as a CLI tool.\n| `do-convert.pkl`\n|===\n\n*Exception*: If a file is meant to render into a static configuration file, the filename should match the target file's name without the extension.\nFor example, `config.pkl` turns into `config.yml`.\n\n*Exception*: The `PklProject` file cannot have any extension.\n\n=== File Encoding\n\nEncode all files using UTF-8.\n\n== Module Structure\n\n=== Header\n\nSeparate each section of the module header by one blank line.\n\nA module header consists of the following clauses, each of which is optional:\n\n- Module clause\n- `amends` or `extends` clause\n- Import clauses\n\n.module.pkl\n[source%parsed,{pkl}]\n----\nmodule com.example.Foo // <1>\n\nextends \"Bar.pkl\" // <2>\n\nimport \"baz.pkl\" // <3>\nimport \"Buz.pkl\" // <3>\n----\n<1> Module clause\n<2> `extends` clause\n<3> Import clause\n\n==== Module name\n\nMatch the name of the module with the name of the file.\n\n.MyModule.pkl\n[source%tested,{pkl}]\n----\nmodule MyModule\n\n----\n\nIf a module is meant to be published, add a module clause, `@ModuleInfo` annotation, and doc comments.\n\nModules that do not get published anywhere may omit a module clause.\n\n.MyModule.pkl\n[source%tested,{pkl}]\n----\n/// Used for some type of purpose. <1>\n@ModuleInfo { minPklVersion = \"0.24.0\" } // <2>\nmodule MyModule // <3>\n\n----\n<1> Doc comments\n<2> `@ModuleInfo` annotation\n<3> Module clause\n\n==== `amends` vs. `extends` clause\n\nA module that doesn't add new properties shouldn't use the `extends` clause.\n\n==== Imports\n\nSort imports sections using https://en.wikipedia.org/wiki/Natural_sort_order[natural sorting] by their module URI.\nRelative path and package imports should be in their own section, separated by a newline.\nThere should be no unused imports.\n\n[source%parsed,{pkl}]\n----\nimport \"modulepath:/foo.pkl\"\nimport \"package://example.com/mypackage@1.0.0#/foo.pkl\"\n\nimport \"@mypackage/baz.pkl\"\n\nimport \".../my/file/bar2.pkl\"\nimport \".../my/file/bar11.pkl\"\n----\n\n=== Module body\n\nWithin a module body, define members in this order:\n\n1. Properties\n2. Methods\n3. Classes and type aliases\n4. The amended xref:language-reference:index.adoc#in-language[output] property.\n\n*Exception*: local members can be close to their usage.\n\n*Exception*: functions meant to be a class constructor can be next to the class declaration.\n\n.constructor.pkl\n[source%tested,{pkl}]\n----\nfunction MyClass(_name: String): MyClass = new { name = _name }\n\nclass MyClass {\n name: String\n}\n----\n\n=== Module URIs\n\nIf possible, use xref:language-reference:index.adoc#triple-dot-module-uris[triple-dot Module URIs] to reference ancestor modules\ninstead of multiple `../`.\n\n.good.pkl\n[source%parsed,{pkl}]\n----\namends \".../ancestor.pkl\"\n\nimport \".../ancestor2.pkl\"\n----\n\n.bad.pkl\n[source%parsed,{pkl}]\n----\namends \"../../../ancestor.pkl\"\n\nimport \"../../../ancestor2.pkl\"\n----\n\n== Objects\n\n=== Member spacing\n\nObject members (properties, elements, and entries) should be separated by at most one blank line.\n\n.good.pkl\n[source%tested,{pkl}]\n----\nfoo = \"bar\"\n\nbaz = \"buz\"\n----\n\n.good.pkl\n[source%tested,{pkl}]\n----\nfoo = \"bar\"\nbaz = \"buz\"\n----\n\n.bad.pkl\n[source%tested,{pkl}]\n----\nfoo = \"bar\"\n\n\nbaz = \"buz\"\n----\n\nToo many lines separate `foo` and `baz`.\n\n=== Overridden properties\n\nProperties that override an existing property shouldn't have doc comments nor type annotations,\nunless the type is intentionally overridden via `extends`.\n\n[source%tested,{pkl}]\n----\namends \"myOtherModule.pkl\"\n\nfoo = \"bar\"\n----\n\n=== New property definitions\n\nEach property definition should have a type annotation and <>.\nSuccessive definitions should be separated by a blank line.\n\n.good.pkl\n[source%parsed,{pkl}]\n----\n/// Denotes something.\nmyFoo: String\n\n/// Something else\nmyOtherFoo: String\n----\n\n.bad.pkl\n[source%parsed,{pkl}]\n----\n/// Denotes something.\nmyFoo: String\n/// Something else\nmyOtherFoo: String\n----\n\n=== Objects with `new`\n\nWhen initializing a `Typed` object using `new`, omit the type.\nFor example, use `new {}` instead of `new Foo {}`.\n\nThis rule does not apply when initializing a property to a subtype of the property's declared type.\n\n.good.pkl\n[source%parsed,{pkl}]\n----\nmyFoo: Foo = new { foo = \"bar\" }\n----\n\n.good.pkl\n[source%parsed,{pkl}]\n----\nopen class Foo {}\nclass Bar extends Foo {}\n\nfoo: Foo = new Bar {}\n----\n\nThis is okay because this is meaning to initialize `Bar` instead of `Foo`.\n\n.bad.pkl\n[source%parsed,{pkl}]\n----\nmyFoo1: Foo = new Foo { foo = \"bar\" } // <1>\n\nmyFoo2 = new Foo { foo = \"bar\" } // <2>\n----\n<1> Unnecessary `new Foo { ... }`\n<2> Unless amending/extending a module where `myFoo2` is already defined, `myFoo2` is effectively the `unknown` type, i.e. `myFoo2: unknown`.\n\n== Comments\n\nUse doc comments to convey information to users of a module.\nUse line comments or block comments to convey implementation concerns to authors of a module, or to comment out code.\n\n[[doc-comment]]\n=== Doc comments\n\nDoc comments should start with a one sentence summary paragraph, followed by additional paragraphs if necessary.\nStart new sentences on their own line.\n\n[source%parsed,{pkl}]\n----\n/// The time allotted for eating lunch.\n///\n/// Note:\n/// * Hamburgers typically take longer to eat than salad.\n/// * Pizza gets prepared per-order.\n///\n/// Orders must be placed on-prem.\n/// See for more details.\nlunchHours: Duration\n----\n\n=== Line comments\n\nIf a comment relates to a property definition, place it after the property's doc comments.\nAdd a single space after `//`.\n\n.good.pkl\n[source%parsed,{pkl}]\n----\n/// Designates whether it is zebra party time.\n// TODO: Add constraints here?\npartyTime: Boolean\n----\n\nA line comment may also be placed at the end of a line, as long as the line doesn't exceed 100 characters.\n\n.good.pkl\n[source%tested,{pkl}]\n----\n/// Designates whether it is zebra party time.\npartyTime: Boolean // TODO: Add constraints here?\n----\n\n=== Block comments\n\nA single-line block comment should have a single space after `+++/*+++` and before `+++*/+++`.\n\n.good.pkl\n[source%tested,{pkl}]\n----\n/* Let's have a zebra party */\n----\n\n.bad.pkl\n[source%tested,{pkl}]\n----\n/*Let's have a zebra party*/\n----\n\n== Classes\n\n=== Class names\n\nName classes in PascalCase.\n\n.good.pkl\n[source%tested,{pkl}]\n----\nclass ZebraParty {}\n----\n\n.bad.pkl\n[source%tested,{pkl}]\n----\nclass zebraParty {}\n----\n\n== Strings\n\n=== Custom String Delimiters\n\nUse xref:language-reference:index.adoc#custom-string-delimiters[custom string delimiters] to avoid the need for string escaping.\n\n.good.pkl\n[source%tested,{pkl}]\n----\nmyString = #\"foo \\ bar \\ baz\"#\n----\n\n.bad.pkl\n[source%tested,{pkl}]\n----\nmyString = \"foo \\\\ bar \\\\ baz\"\n----\n\nNOTE: Sometimes, using custom string delimiters makes source code harder to read. For example, the `+\\#+` literal reads better using escapes (`\"\\\\#\"`) than using custom string delimiters (`+##\"\\#\"##+`).\n\n=== Interpolation\n\nPrefer interpolation to string concatenation.\n\n.good.pkl\n[source%parsed,{pkl}]\n----\ngreeting = \"Hello, \\(name)\"\n----\n\n.bad.pkl\n[source%parsed,{pkl}]\n----\ngreeting = \"Hello, \" + name\n----\n\n== Formatting\n\n=== Line width\n\nLines shouldn't exceed 100 characters.\n\n*Exceptions:*\n\n1. String literals\n2. Code snippets within doc comments\n\n=== Indentation\n\nUse two spaces per indentation level.\n\n==== Members within braces\n\nMembers within braces should be indented one level deeper than their parents.\n\n[source%tested,{pkl}]\n----\nfoo {\n bar {\n baz = \"hi\"\n }\n}\n----\n\n==== Assignment operator (`=`)\n\nAn assignee that starts after a newline should be indented.\n\n.good.pkl\n[source%tested,{pkl}]\n----\nfoo =\n \"foo\"\n\nbar =\n new {\n baz = \"baz\"\n biz = \"biz\"\n }\n----\n\n.bad.pkl\n[source%tested,{pkl}]\n----\nfoo =\n\"foo\"\n\nbar =\nnew {\n baz = \"baz\"\n biz = \"biz\"\n}\n----\n\nAn assignee that starts on the same line should not be indented.\n\n.good.pkl\n[source%tested,{pkl}]\n----\nfoo = new {\n baz = \"baz\"\n biz = \"biz\"\n}\n----\n\n.bad.pkl\n[source%tested,{pkl}]\n----\nfoo = new {\n baz = \"baz\"\n biz = \"biz\"\n }\n----\n\n==== `if` and `let` expressions\n\n`if` and `let` bodies that start on their own line should be indented.\nChild bodies may also be inline, and the `else` branch of `if` expressions may be inline of `if`.\n\n.good.pkl\n[source%parsed,{pkl-expr}]\n----\nif (bar)\n bar\nelse\n foo\n----\n\n.good.pkl\n[source%parsed,{pkl-expr}]\n----\nif (bar) bar else foo\n----\n\n.good.pkl\n[source%parsed,{pkl-expr}]\n----\nlet (foo = \"bar\")\n foo.toUpperCase()\n----\n\n.good.pkl\n[source%parsed,{pkl-expr}]\n----\nlet (foo = \"bar\") foo.toUpperCase()\n----\n\n.bad.pkl\n[source%parsed,{pkl-expr}]\n----\nif (bar)\nbar\nelse\nfoo\n----\n\n.bad.pkl\n[source%parsed,{pkl-expr}]\n----\nlet (foo = \"bar\")\nfoo.toUpperCase()\n----\n\n*Exception*: A nested `if` expression within the `else` branch should have the same indentation level as its parent, and start on the same line as the parent `else` keyword.\n\n.good.pkl\n[source%parsed,{pkl-expr}]\n----\nif (bar)\n bar\nelse if (baz)\n baz\nelse\n foo\n----\n\n.bad.pkl\n[source%parsed,{pkl-expr}]\n----\nif (bar)\n bar\nelse\n if (baz)\n baz\n else\n foo\n----\n\n==== Multiline chained method calls\n\nIndent successive multiline chained method calls.\n\n[source%parsed,{pkl-expr}]\n----\nfoo()\n .bar()\n .baz()\n .biz()\n----\n\n==== Multiline binary operators\n\nPlace operators after the newline, and indent successive lines to the same level.\n\n.good.pkl\n[source%parsed,{pkl}]\n----\nfoo = bar\n |> baz\n |> biz\n\nmyNum = 1\n + 2\n + 3\n + 4\n----\n\n.bad.pkl\n[source%parsed,{pkl}]\n----\nfoo = bar |>\n baz |>\n biz\n\nmyNum = 1 +\n 2 +\n 3 +\n 4\n----\n\n.bad.pkl\n[source%tested,{pkl}]\n----\nfoo = bar\n|> baz\n|> biz\n----\n\n.bad.pkl\n[source%tested,{pkl}]\n----\nfoo = bar\n |> baz\n |> biz\n----\n\n*Exception*: the minus operator must come before the newline, because otherwise it is parsed as a unary minus.\n\n.good.pkl\n[source%tested,{pkl}]\n----\nmyNum = 1 -\n 2 -\n 3 -\n 4\n----\n\n.bad.pkl\n[source%tested,{pkl}]\n----\nmyNum = 1\n - 2\n - 3\n - 4\n----\n\n=== Spaces\n\nAdd a space:\n\n[source%parsed,{pkl}]\n----\namends \"Foo.pkl\" // <1>\n\nres1 { \"foo\" } // <2>\nres2 = 1 + 2 // <3>\nres3 = res2 as Number // <3>\nres4 = List(1, 2, 3) // <4>\nres5 = if (foo) bar else baz // <5>\n\ntypealias Foo = \"foo\" | \"bar\" | \"baz\" // <6>\n----\n<1> After keywords\n<2> Before and after braces\n<3> Around infix operators\n<4> After a comma\n<5> Before opening parentheses in control operators (`if`, `for`, `when` are control operators)\n<6> Before and after the pipe symbol (`|`)\n\n=== Object bodies\n\n==== Single line\n\nAn object body may be a single line if it only consists of primitive elements, or if it contains two or fewer members.\nOtherwise, split them into multiple lines.\n\nSeparate each member of a single line object with a semicolon and a space.\n\n.good.pkl\n[source%tested,{pkl}]\n----\nres1 = new { bar = \"bar\"; baz = \"baz\" }\nres2 = new { 1; 2; 3; 4; 5; 6 }\n----\n\n.bad.pkl\n[source%parsed,{pkl}]\n----\nres1 = new { bar = \"bar\"; baz = \"baz\"; biz = \"biz\"; } // <1>\n\nres2 = new { 1 2 3 4 5 6 } // <2>\n----\n\n<1> Too many members and trailing `;`\n<2> No semicolon\n\n==== Multiline\n\nMultiline objects should have their members separated by at least one line break and at most one blank line.\n\n.good.pkl\n[source%tested,{pkl}]\n----\nres {\n foo = \"foo\"\n bar = \"bar\"\n}\n\nres2 {\n [\"foo\"] = \"foo\"\n [\"bar\"] = \"bar\"\n}\n\nres3 {\n \"foo\"\n \"bar\"\n}\n----\n\n.good.pkl\n[source%tested,{pkl}]\n----\nres {\n foo = \"foo\"\n\n bar = \"bar\"\n}\n\nres2 {\n [\"foo\"] = \"foo\"\n\n [\"bar\"] = \"bar\"\n}\n\nres3 {\n \"foo\"\n\n \"bar\"\n}\n----\n\n.bad.pkl\n[source%tested,{pkl}]\n----\nres {\n foo = \"foo\"\n\n\n bar = \"bar\" // <1>\n}\n\nres2 {\n [\"foo\"] = \"foo\"\n\n\n [\"bar\"] = \"bar\" // <1>\n}\n\nres3 {\n \"foo\"\n\n\n \"bar\" // <1>\n}\n\nres4 {\n foo = \"foo\"; bar = \"bar\" // <2>\n}\n----\n<1> Too many blank lines between members\n<2> No line break separating members\n\nPut the opening brace on the same line.\n\n.good.pkl\n\n[source%tested,{pkl}]\n----\nres {\n foo = \"foo\"\n bar = \"bar\"\n}\n----\n\n.bad.pkl\n[source%tested,{pkl}]\n----\nres\n{\n foo = \"foo\"\n bar = \"bar\"\n}\n----\n\n== Programming Practices\n\n=== Prefer `for` generators\n\nWhen programmatically creating elements and entries, prefer\nxref:language-reference:index.adoc#for-generators[for generators] over using the collection API.\nUsing for generators preserves xref:language-reference:index.adoc#late-binding[late binding].\n\n.good.pkl\n[source%tested,{pkl}]\n----\nnumbers {\n 1\n 2\n 3\n 4\n}\n\nsquares {\n for (num in numbers) {\n num ** 2\n }\n}\n----\n\n.bad.pkl\n[source%tested,{pkl}]\n----\nnumbers {\n 1\n 2\n 3\n 4\n}\n\nsquares = numbers.toList().map((num) -> num ** 2).toListing()\n----\n" }, { "path": "docs/nav.adoc", "content": "* xref:introduction:index.adoc[Introduction]\n** xref:introduction:use-cases.adoc[Use Cases]\n** xref:introduction:concepts.adoc[Concepts]\n** xref:introduction:comparison.adoc[Comparison]\n\n* xref:pkl-cli:index.adoc#installation[Installation]\n\n* xref:language-tutorial:index.adoc[Tutorial]\n** xref:language-tutorial:01_basic_config.adoc[Basic Configuration]\n** xref:language-tutorial:02_filling_out_a_template.adoc[Filling out a Template]\n** xref:language-tutorial:03_writing_a_template.adoc[Writing a Template]\n\n* xref:ROOT:language.adoc[Language]\n** xref:language-reference:index.adoc[Language Reference]\n** xref:ROOT:standard-library.adoc[Standard Library]\n** xref:ROOT:language-bindings.adoc[Language Bindings]\n*** xref:java-binding:index.adoc[Java]\n**** xref:java-binding:codegen.adoc[Code Generator]\n**** xref:pkl-core:index.adoc[pkl-core Library]\n**** xref:java-binding:pkl-config-java.adoc[pkl-config-java Library]\n*** xref:kotlin-binding:index.adoc[Kotlin]\n**** xref:kotlin-binding:codegen.adoc[Code Generator]\n**** xref:kotlin-binding:pkl-config-kotlin.adoc[pkl-config-kotlin Library]\n*** xref:swift:ROOT:index.adoc[Swift]\n*** xref:go:ROOT:index.adoc[Go]\n*** xref:bindings-specification:index.adoc[Specification]\n**** xref:bindings-specification:message-passing-api.adoc[Message Passing API]\n**** xref:bindings-specification:binary-encoding.adoc[Pkl Binary Encoding]\n\n* xref:ROOT:tools.adoc[Tools]\n** xref:pkl-cli:index.adoc[CLI]\n** xref:pkl-doc:index.adoc[Pkldoc]\n** xref:pkl-gradle:index.adoc[Gradle Plugin]\n** Editor support\n*** xref:intellij:ROOT:index.adoc[IntelliJ]\n*** xref:vscode:ROOT:index.adoc[VSCode]\n*** xref:neovim:ROOT:index.adoc[Neovim]\n\n* xref:ROOT:examples.adoc[Examples]\n\n* xref:ROOT:evolution-and-roadmap.adoc[Evolution and Roadmap]\n\n* xref:release-notes:index.adoc[Release Notes]\n** xref:release-notes:0.32.adoc[0.32 Release Notes]\n** xref:release-notes:0.31.adoc[0.31 Release Notes]\n** xref:release-notes:0.30.adoc[0.30 Release Notes]\n** xref:release-notes:0.29.adoc[0.29 Release Notes]\n** xref:release-notes:0.28.adoc[0.28 Release Notes]\n** xref:release-notes:0.27.adoc[0.27 Release Notes]\n** xref:release-notes:0.26.adoc[0.26 Release Notes]\n** xref:release-notes:0.25.adoc[0.25 Release Notes]\n** xref:release-notes:changelog.adoc[Changelog]\n\n" }, { "path": "docs/src/test/kotlin/DocSnippetTests.kt", "content": "import org.junit.platform.commons.annotation.Testable\nimport org.junit.platform.engine.*\nimport org.junit.platform.engine.TestDescriptor.Type\nimport org.junit.platform.engine.discovery.ClassSelector\nimport org.junit.platform.engine.discovery.MethodSelector\nimport org.junit.platform.engine.discovery.PackageSelector\nimport org.junit.platform.engine.discovery.UniqueIdSelector\nimport org.junit.platform.engine.support.descriptor.*\nimport org.junit.platform.engine.support.hierarchical.EngineExecutionContext\nimport org.junit.platform.engine.support.hierarchical.HierarchicalTestEngine\nimport org.junit.platform.engine.support.hierarchical.Node\nimport org.junit.platform.engine.support.hierarchical.Node.DynamicTestExecutor\nimport org.opentest4j.MultipleFailuresError\nimport org.pkl.commons.test.FileTestUtils.rootProjectDir\nimport org.pkl.core.Loggers\nimport org.pkl.core.SecurityManagers\nimport org.pkl.core.StackFrameTransformers\nimport org.pkl.core.evaluatorSettings.TraceMode\nimport org.pkl.core.module.ModuleKeyFactories\nimport org.pkl.core.repl.ReplRequest\nimport org.pkl.core.repl.ReplResponse\nimport org.pkl.core.repl.ReplServer\nimport org.pkl.core.util.IoUtils\nimport org.pkl.core.http.HttpClient\nimport org.pkl.parser.Parser\nimport org.pkl.parser.ParserError\nimport org.pkl.parser.syntax.ClassProperty\nimport org.pkl.core.resource.ResourceReaders\nimport java.nio.file.Files\nimport kotlin.io.path.isDirectory\nimport kotlin.io.path.isRegularFile\nimport kotlin.io.path.useDirectoryEntries\n\n@Testable\nclass DocSnippetTests\n\nclass DocSnippetTestsEngine : HierarchicalTestEngine() {\n private val projectDir = rootProjectDir.resolve(\"docs\")\n private val docsDir = projectDir.resolve(\"modules\")\n\n private companion object {\n val headingRegex = Regex(\"\"\"(?u)^\\s*(=++)\\s*(.+)\"\"\")\n val collapsibleBlockRegex = Regex(\"\"\"(?u)^\\s*\\[%collapsible\"\"\")\n val codeBlockRegex = Regex(\"\"\"(?u)^\\s*\\[source(?:%(tested|parsed)(%error)?)?(?:,\\{?([a-zA-Z-_]+)}?)?\"\"\")\n val codeBlockNameRegex = Regex(\"\"\"(?u)^\\s*\\.(.+)\"\"\")\n val codeBlockDelimiterRegex = Regex(\"\"\"(?u)^\\s*----\"\"\")\n val graphicsRegex = Regex(\"\\\\[small]#.+#\")\n }\n\n override fun getId() = \"pkl-doc-tests\"\n\n override fun discover(\n discoveryRequest: EngineDiscoveryRequest,\n uniqueId: UniqueId\n ): TestDescriptor {\n val packageSelectors = discoveryRequest.getSelectorsByType(PackageSelector::class.java)\n val classSelectors = discoveryRequest.getSelectorsByType(ClassSelector::class.java)\n val methodSelectors = discoveryRequest.getSelectorsByType(MethodSelector::class.java)\n val uniqueIdSelectors = discoveryRequest.getSelectorsByType(UniqueIdSelector::class.java)\n\n val testClass = DocSnippetTests::class.java\n val packageName = testClass.`package`.name\n val className = testClass.name\n\n if (methodSelectors.isEmpty()\n && (packageSelectors.isEmpty() || packageSelectors.any { it.packageName == packageName })\n && (classSelectors.isEmpty() || classSelectors.any { it.className == className })\n ) {\n\n val rootDescriptor = Descriptor.Path(uniqueId, docsDir.fileName.toString(), ClassSource.from(testClass), docsDir)\n doDiscover(rootDescriptor, uniqueIdSelectors)\n return rootDescriptor\n }\n\n // return empty descriptor w/o children\n return EngineDescriptor(uniqueId, javaClass.simpleName)\n }\n\n override fun createExecutionContext(request: ExecutionRequest): ExecutionContext {\n val replServer = ReplServer(\n SecurityManagers.defaultManager,\n HttpClient.dummyClient(),\n Loggers.stdErr(),\n listOf(\n ModuleKeyFactories.standardLibrary,\n ModuleKeyFactories.classPath(DocSnippetTests::class.java.classLoader),\n ModuleKeyFactories.file\n ),\n listOf(\n ResourceReaders.environmentVariable(),\n ResourceReaders.externalProperty()\n ),\n System.getenv(),\n emptyMap(),\n null,\n null,\n null,\n IoUtils.getCurrentWorkingDir(),\n StackFrameTransformers.defaultTransformer,\n false,\n TraceMode.COMPACT,\n )\n return ExecutionContext(replServer)\n }\n\n private fun doDiscover(rootDescriptor: TestDescriptor, selectors: List) {\n fun isMatch(other: UniqueId) = selectors.isEmpty() || selectors.any {\n it.uniqueId.hasPrefix(other) || other.hasPrefix(it.uniqueId)\n }\n\n docsDir.useDirectoryEntries { docsDirEntries ->\n for (docsDirEntry in docsDirEntries) {\n if (!docsDirEntry.isDirectory()) continue\n\n val docsDirEntryName = docsDirEntry.fileName.toString()\n val docsDirEntryId = rootDescriptor.uniqueId.append(\"dir\", docsDirEntryName)\n if (!isMatch(docsDirEntryId)) continue\n\n val docsDirEntryDescriptor = Descriptor.Path(\n docsDirEntryId,\n docsDirEntryName,\n DirectorySource.from(docsDirEntry.toFile()),\n docsDirEntry\n )\n rootDescriptor.addChild(docsDirEntryDescriptor)\n\n val pagesDir = docsDirEntry.resolve(\"pages\")\n if (!pagesDir.isDirectory()) continue\n\n pagesDir.useDirectoryEntries { pagesDirEntries ->\n for (pagesDirEntry in pagesDirEntries) {\n val pagesDirEntryName = pagesDirEntry.fileName.toString()\n val pagesDirEntryId = docsDirEntryId.append(\"file\", pagesDirEntryName)\n if (!pagesDirEntry.isRegularFile() ||\n !pagesDirEntryName.endsWith(\".adoc\") ||\n !isMatch(pagesDirEntryId)\n ) continue\n\n val pagesDirEntryDescriptor = Descriptor.Path(\n pagesDirEntryId,\n pagesDirEntryName,\n FileSource.from(pagesDirEntry.toFile()),\n pagesDirEntry\n )\n docsDirEntryDescriptor.addChild(pagesDirEntryDescriptor)\n\n parseAsciidoc(pagesDirEntryDescriptor, selectors)\n }\n }\n }\n }\n }\n\n @Suppress(\"DEPRECATION\")\n private fun parseAsciidoc(docDescriptor: Descriptor.Path, selectors: List) {\n var line = \"\"\n var prevLine = \"\"\n var lineNum = 0\n var codeBlockNum = 0\n val sections = ArrayDeque()\n\n Files.lines(docDescriptor.path).use { linesStream ->\n val linesIterator = linesStream.iterator()\n\n fun advance() {\n prevLine = line\n line = linesIterator.next()\n lineNum += 1\n }\n\n fun addSection(title: String, newLevel: Int) {\n while (sections.isNotEmpty() && sections.first().level >= newLevel) {\n sections.removeFirst()\n }\n\n val parent = sections.firstOrNull() ?: docDescriptor\n val normalizedTitle = title\n .replace(\"\", \"\")\n .replace(\"\", \"\")\n .replace(graphicsRegex, \"\")\n .trim()\n val childSection = Descriptor.Section(\n parent.uniqueId.append(\"section\", normalizedTitle),\n normalizedTitle,\n FileSource.from(docDescriptor.path.toFile(), FilePosition.from(lineNum)),\n newLevel\n )\n\n sections.addFirst(childSection)\n parent.addChild(childSection)\n codeBlockNum = 0\n }\n\n nextLine@ while (linesIterator.hasNext()) {\n advance()\n\n val headingMatch = headingRegex.find(line)\n if (headingMatch != null) {\n val (markup, title) = headingMatch.destructured\n val newLevel = markup.length\n // ignore level 1 heading (we already have a test node for the file)\n if (newLevel == 1) continue\n addSection(title, newLevel)\n continue\n }\n\n val collapsibleBlockMatch = collapsibleBlockRegex.find(line)\n if (collapsibleBlockMatch != null) {\n val blockName = codeBlockNameRegex.find(prevLine)?.groupValues?.get(1) ?: \"Details\"\n val newLevel = 999\n addSection(blockName, newLevel)\n continue\n }\n\n val codeBlockMatch = codeBlockRegex.find(line)\n if (codeBlockMatch != null) {\n codeBlockNum += 1\n val (testMode, error, language) = codeBlockMatch.destructured\n if (testMode.isNotEmpty()) {\n val blockName = codeBlockNameRegex.find(prevLine)?.groupValues?.get(1) ?: \"snippet$codeBlockNum\"\n while (linesIterator.hasNext()) {\n advance()\n val startDelimiterMatch = codeBlockDelimiterRegex.find(line)\n if (startDelimiterMatch != null) {\n val jumpToLineNum = lineNum + 1\n val builder = StringBuilder()\n while (linesIterator.hasNext()) {\n advance()\n val endDelimiterMatch = codeBlockDelimiterRegex.find(line)\n if (endDelimiterMatch != null) {\n val section = sections.first()\n val snippetId = section.uniqueId.append(\"snippet\", blockName)\n if (selectors.isEmpty() || selectors.any { snippetId.hasPrefix(it.uniqueId) }) {\n section.addChild(\n Descriptor.Snippet(\n snippetId,\n blockName,\n language,\n FileSource.from(docDescriptor.path.toFile(), FilePosition.from(jumpToLineNum)),\n builder.toString(),\n testMode == \"parsed\",\n error.isNotEmpty()\n )\n )\n }\n continue@nextLine\n }\n builder.appendLine(line)\n }\n }\n }\n }\n }\n }\n }\n }\n\n class ExecutionContext(val replServer: ReplServer) : EngineExecutionContext, AutoCloseable {\n override fun close() {\n replServer.close()\n }\n }\n\n private sealed class Descriptor(\n uniqueId: UniqueId,\n displayName: String,\n source: TestSource\n ) : AbstractTestDescriptor(uniqueId, displayName, source), Node {\n\n class Path(\n uniqueId: UniqueId,\n displayName: String,\n source: TestSource,\n val path: java.nio.file.Path\n ) : Descriptor(uniqueId, displayName, source) {\n\n override fun getType() = Type.CONTAINER\n }\n\n class Section(\n uniqueId: UniqueId,\n displayName: String,\n source: TestSource,\n val level: Int\n ) : Descriptor(uniqueId, displayName, source) {\n\n override fun getType() = Type.CONTAINER\n\n override fun before(context: ExecutionContext): ExecutionContext {\n context.replServer.handleRequest(ReplRequest.Reset(\"reset\"))\n return context\n }\n }\n\n class Snippet(\n uniqueId: UniqueId,\n displayName: String,\n private val language: String,\n source: TestSource,\n private val code: String,\n private val parseOnly: Boolean,\n private val expectError: Boolean\n ) : Descriptor(uniqueId, displayName, source) {\n\n override fun getType() = Type.TEST\n\n private val parsed: org.pkl.parser.syntax.Node by lazy {\n when (language) {\n \"pkl\" -> Parser().parseModule(code)\n \"pkl-expr\" -> Parser().parseExpressionInput(code)\n else -> throw(Exception(\"Unrecognized language: $language\"))\n }\n }\n\n override fun execute(context: ExecutionContext, executor: DynamicTestExecutor): ExecutionContext {\n if (parseOnly) {\n try {\n parsed\n if (expectError) {\n throw AssertionError(\"Expected a parse error, but got none.\")\n }\n } catch (e: ParserError) {\n if (!expectError) {\n throw AssertionError(e.message)\n }\n }\n return context\n }\n\n context.replServer.handleRequest(\n ReplRequest.Eval(\n \"snippet\",\n code,\n !expectError,\n !expectError\n )\n )\n\n val properties = parsed.children()?.filterIsInstance() ?: emptyList()\n\n val responses = mutableListOf()\n\n // force each property\n for (prop in properties) {\n responses.addAll(context.replServer.handleRequest(\n ReplRequest.Eval(\n \"snippet\",\n prop.name.value,\n false,\n true\n )\n ))\n }\n if (expectError) {\n if (responses.dropLast(1).any { it !is ReplResponse.EvalSuccess } ||\n responses.last() !is ReplResponse.EvalError) {\n throw AssertionError(\n \"Expected %error snippet to fail at the end, but got the following REPL responses:\\n\\n\" +\n responses.joinToString(\"\\n\\n\") { it.message })\n }\n\n return context\n }\n\n val badResponses = responses.filter { it !is ReplResponse.EvalSuccess }\n if (badResponses.isNotEmpty()) {\n throw MultipleFailuresError(null, badResponses.map { AssertionError(it.message) })\n }\n\n return context\n }\n }\n }\n}\n" }, { "path": "docs/src/test/resources/META-INF/services/org.junit.platform.engine.TestEngine", "content": "DocSnippetTestsEngine" }, { "path": "gradle/libs.versions.toml", "content": "[versions] # ordered alphabetically\nassertj = \"3.+\"\nchecksumPlugin = \"1.4.0\"\nclikt = \"5.+\"\ncommonMark = \"0.+\"\ndownloadTaskPlugin = \"5.6.0\"\ngeantyref = \"1.+\"\ngoogleJavaFormat = \"1.25.2\"\n# must not use `+` because used in download URL\n# 23.1.x requires JDK 20+\ngraalVm = \"25.0.0\"\n#noinspection UnusedVersionCatalogEntry\ngraalVmJdkVersion = \"25.0.0\"\n# slightly hacky but convenient place so we remember to update the checksum\n#noinspection UnusedVersionCatalogEntry\ngraalVmSha256-macos-x64 = \"04278cf867d040e29dc71dd7727793f0ea67eb72adce8a35d04b87b57906778d\"\n#noinspection UnusedVersionCatalogEntry\ngraalVmSha256-macos-aarch64 = \"c446d5aaeda98660a4c14049d299e9fba72105a007df89f19d27cf3979d37158\"\n#noinspection UnusedVersionCatalogEntry\ngraalVmSha256-linux-x64 = \"1862f2ce97387a303cae4c512cb21baf36fafd2457c3cbbc10d87db94b89d3dd\"\n#noinspection UnusedVersionCatalogEntry\ngraalVmSha256-linux-aarch64 = \"6c3c8b7617006c5d174d9cf7d357ccfb4bae77a4df1294ee28084fcb6eea8921\"\n#noinspection UnusedVersionCatalogEntry\ngraalVmSha256-windows-x64 = \"33ef1d186b5c1e95465fcc97e637bc26e72d5f2250a8615b9c5d667ed5c17fd0\"\nideaExtPlugin = \"1.1.9\"\nintellijPlugin = \"2.10.1\"\nintellij = \"2025.2.3\"\njavaPoet = \"0.+\"\njavaxInject = \"1\"\njansi = \"2.+\"\njimfs = \"1.+\"\n# later versions don't work with native image\n# (at least not without additional configuration; tested with 3.25.1 and 3.27.1)\njline = \"3.23.0\"\njmh = \"1.+\"\njmhPlugin = \"0.7.2\"\njsr305 = \"3.+\"\njunit = \"5.+\"\njunitPlatform = \"1.+\"\nkotlin = \"2.2.20\"\n# 1.7+ generates much more verbose code\nkotlinPoet = \"1.6.+\"\nkotlinxHtml = \"0.11.0\"\nkotlinxSerialization = \"1.8.0\"\nkotlinxCoroutines = \"1.+\"\nktfmt = \"0.53\"\n# replaces nuValidator's log4j dependency\n# something related to log4j-1.2-api is apparently broken in 2.17.2\nlog4j = \"2.17.1\"\nmsgpack = \"0.9.8\"\nnexusPublishPlugin = \"2.0.0\"\nnuValidator = \"20.+\"\npaguro = \"3.+\"\nshadowPlugin = \"9.+\"\nslf4j = \"1.+\"\nsnakeYaml = \"2.+\"\nspotlessPlugin = \"6.25.0\"\nwiremock = \"3.+\"\n\n[libraries] # ordered alphabetically\nassertj = { group = \"org.assertj\", name = \"assertj-core\", version.ref = \"assertj\" }\nclikt = { group = \"com.github.ajalt.clikt\", name = \"clikt\", version.ref = \"clikt\" }\ncliktMarkdown = { group = \"com.github.ajalt.clikt\", name = \"clikt-markdown\", version.ref = \"clikt\" }\ncommonMark = { group = \"org.commonmark\", name = \"commonmark\", version.ref = \"commonMark\" }\ncommonMarkTables = { group = \"org.commonmark\", name = \"commonmark-ext-gfm-tables\", version.ref = \"commonMark\" }\ndownloadTaskPlugin = { group = \"de.undercouch\", name = \"gradle-download-task\", version.ref = \"downloadTaskPlugin\" }\ngeantyref = { group = \"io.leangen.geantyref\", name = \"geantyref\", version.ref = \"geantyref\" }\ngraalCompiler = { group = \"org.graalvm.compiler\", name = \"compiler\", version.ref = \"graalVm\" }\ngraalSdk = { group = \"org.graalvm.sdk\", name = \"graal-sdk\", version.ref = \"graalVm\" }\ngraalJs = { group = \"org.graalvm.js\", name = \"js\", version.ref = \"graalVm\" }\n#noinspection UnusedVersionCatalogEntry\nintellij = { group = \"com.jetbrains.intellij.idea\", name = \"ideaIC\", version.ref = \"intellij\" }\njavaPoet = { group = \"com.palantir.javapoet\", name = \"javapoet\", version.ref = \"javaPoet\" }\njavaxInject = { group = \"javax.inject\", name = \"javax.inject\", version.ref = \"javaxInject\" }\njansi = { group = \"org.fusesource.jansi\", name = \"jansi\", version.ref = \"jansi\" }\njimfs = { group = \"com.google.jimfs\", name = \"jimfs\", version.ref = \"jimfs\" }\njlineReader = { group = \"org.jline\", name = \"jline-reader\", version.ref = \"jline\" }\njlineTerminal = { group = \"org.jline\", name = \"jline-terminal\", version.ref = \"jline\" }\njlineTerminalJansi = { group = \"org.jline\", name = \"jline-terminal-jansi\", version.ref = \"jline\" }\njsr305 = { group = \"com.google.code.findbugs\", name = \"jsr305\", version.ref = \"jsr305\" }\njunitApi = { group = \"org.junit.jupiter\", name = \"junit-jupiter-api\", version.ref = \"junit\" }\njunitEngine = { group = \"org.junit.jupiter\", name = \"junit-jupiter-engine\", version.ref = \"junit\" }\njunitParams = { group = \"org.junit.jupiter\", name = \"junit-jupiter-params\", version.ref = \"junit\" }\njunitLauncher = { group = \"org.junit.platform\", name = \"junit-platform-launcher\", version.ref = \"junitPlatform\" }\nkotlinPlugin = { group = \"org.jetbrains.kotlin\", name = \"kotlin-gradle-plugin\", version.ref = \"kotlin\" }\nkotlinPoet = { group = \"com.squareup\", name = \"kotlinpoet\", version.ref = \"kotlinPoet\" }\nkotlinReflect = { group = \"org.jetbrains.kotlin\", name = \"kotlin-reflect\", version.ref = \"kotlin\" }\nkotlinScripting = { group = \"org.jetbrains.kotlin\", name = \"kotlin-scripting-jsr223\", version.ref = \"kotlin\" }\nkotlinStdLib = { group = \"org.jetbrains.kotlin\", name = \"kotlin-stdlib-jdk8\", version.ref = \"kotlin\" }\nkotlinxHtml = { group = \"org.jetbrains.kotlinx\", name = \"kotlinx-html-jvm\", version.ref = \"kotlinxHtml\" }\nkotlinxSerializationJson = { group = \"org.jetbrains.kotlinx\", name = \"kotlinx-serialization-json\", version.ref = \"kotlinxSerialization\" }\nkotlinxCoroutinesCore = { group = \"org.jetbrains.kotlinx\", name = \"kotlinx-coroutines-core\", version.ref = \"kotlinxCoroutines\" }\n#noinspection UnusedVersionCatalogEntry\nlog4j12Api = { group = \"org.apache.logging.log4j\", name = \"log4j-1.2-api\", version.ref = \"log4j\" }\nmsgpack = { group = \"org.msgpack\", name = \"msgpack-core\", version.ref = \"msgpack\" }\n#noinspection UnusedVersionCatalogEntry\nnuValidator = { group = \"nu.validator\", name = \"validator\", version.ref = \"nuValidator\" }\n# to be replaced with https://github.com/usethesource/capsule or https://github.com/lacuna/bifurcan\npaguro = { group = \"org.organicdesign\", name = \"Paguro\", version.ref = \"paguro\" }\npklConfigJavaAll025 = { group = \"org.pkl-lang\", name = \"pkl-config-java-all\", version = \"0.25.0\" }\nshadowPlugin = { group = \"com.gradleup.shadow\", name = \"com.gradleup.shadow.gradle.plugin\", version.ref = \"shadowPlugin\" }\nslf4jApi = { group = \"org.slf4j\", name = \"slf4j-api\", version.ref = \"slf4j\" }\nslf4jSimple = { group = \"org.slf4j\", name = \"slf4j-simple\", version.ref = \"slf4j\" }\nsnakeYaml = { group = \"org.snakeyaml\", name = \"snakeyaml-engine\", version.ref = \"snakeYaml\" }\nspotlessPlugin = { group = \"com.diffplug.spotless\", name = \"spotless-plugin-gradle\", version.ref = \"spotlessPlugin\"}\nsvm = { group = \"org.graalvm.nativeimage\", name = \"svm\", version.ref = \"graalVm\" }\ntruffleApi = { group = \"org.graalvm.truffle\", name = \"truffle-api\", version.ref = \"graalVm\" }\ntruffleDslProcessor = { group = \"org.graalvm.truffle\", name = \"truffle-dsl-processor\", version.ref = \"graalVm\" }\ntruffleSvm = { group = \"org.graalvm.nativeimage\", name = \"truffle-runtime-svm\", version.ref = \"graalVm\" }\ntruffleRuntime = { group = \"org.graalvm.truffle\", name = \"truffle-runtime\", version.ref = \"graalVm\" }\nwiremock = { group = \"org.wiremock\", name = \"wiremock\", version.ref = \"wiremock\" }\n\n[plugins] # ordered alphabetically\nchecksum = { id = \"org.gradle.crypto.checksum\", version.ref = \"checksumPlugin\" }\nideaExt = { id = \"org.jetbrains.gradle.plugin.idea-ext\", version.ref = \"ideaExtPlugin\" }\njmh = { id = \"me.champeau.jmh\", version.ref = \"jmhPlugin\" }\nkotlinxSerialization = { id = \"org.jetbrains.kotlin.plugin.serialization\", version.ref = \"kotlin\" }\nnexusPublish = { id = \"io.github.gradle-nexus.publish-plugin\", version.ref = \"nexusPublishPlugin\" }\nshadow = { id = \"com.gradleup.shadow\", version.ref = \"shadowPlugin\" }\nintellij = { id = \"org.jetbrains.intellij.platform\", version.ref = \"intellijPlugin\" }\n" }, { "path": "gradle/wrapper/gradle-wrapper.properties", "content": "distributionBase=GRADLE_USER_HOME\ndistributionPath=wrapper/dists\ndistributionSha256Sum=a17ddd85a26b6a7f5ddb71ff8b05fc5104c0202c6e64782429790c933686c806\ndistributionUrl=https\\://services.gradle.org/distributions/gradle-9.1.0-bin.zip\nnetworkTimeout=10000\nvalidateDistributionUrl=true\nzipStoreBase=GRADLE_USER_HOME\nzipStorePath=wrapper/dists\n" }, { "path": "gradle.properties", "content": "# suppress inspection \"UnusedProperty\" for whole file\n\ngroup=org.pkl-lang\nversion=0.32.0\n\n# google-java-format requires jdk.compiler exports\norg.gradle.jvmargs= \\\n -XX:+UseParallelGC \\\n -Dfile.encoding=UTF-8 \\\n --add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED \\\n --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED \\\n --add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED \\\n --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \\\n --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED\n\norg.gradle.parallel=true\norg.gradle.caching=true\nkotlin.stdlib.default.dependency=false\nkotlin.daemon.jvmargs=-XX:+UseParallelGC\n#org.gradle.workers.max=1\n" }, { "path": "gradlew", "content": "#!/bin/sh\n\n#\n# Copyright © 2015-2021 the original authors.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# https://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n#\n# SPDX-License-Identifier: Apache-2.0\n#\n\n##############################################################################\n#\n# Gradle start up script for POSIX generated by Gradle.\n#\n# Important for running:\n#\n# (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is\n# noncompliant, but you have some other compliant shell such as ksh or\n# bash, then to run this script, type that shell name before the whole\n# command line, like:\n#\n# ksh Gradle\n#\n# Busybox and similar reduced shells will NOT work, because this script\n# requires all of these POSIX shell features:\n# * functions;\n# * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,\n# «${var#prefix}», «${var%suffix}», and «$( cmd )»;\n# * compound commands having a testable exit status, especially «case»;\n# * various built-in commands including «command», «set», and «ulimit».\n#\n# Important for patching:\n#\n# (2) This script targets any POSIX shell, so it avoids extensions provided\n# by Bash, Ksh, etc; in particular arrays are avoided.\n#\n# The \"traditional\" practice of packing multiple parameters into a\n# space-separated string is a well documented source of bugs and security\n# problems, so this is (mostly) avoided, by progressively accumulating\n# options in \"$@\", and eventually passing that to Java.\n#\n# Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,\n# and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;\n# see the in-line comments for details.\n#\n# There are tweaks for specific operating systems such as AIX, CygWin,\n# Darwin, MinGW, and NonStop.\n#\n# (3) This script is generated from the Groovy template\n# https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt\n# within the Gradle project.\n#\n# You can find Gradle at https://github.com/gradle/gradle/.\n#\n##############################################################################\n\n# Attempt to set APP_HOME\n\n# Resolve links: $0 may be a link\napp_path=$0\n\n# Need this for daisy-chained symlinks.\nwhile\n APP_HOME=${app_path%\"${app_path##*/}\"} # leaves a trailing /; empty if no leading path\n [ -h \"$app_path\" ]\ndo\n ls=$( ls -ld \"$app_path\" )\n link=${ls#*' -> '}\n case $link in #(\n /*) app_path=$link ;; #(\n *) app_path=$APP_HOME$link ;;\n esac\ndone\n\n# This is normally unused\n# shellcheck disable=SC2034\nAPP_BASE_NAME=${0##*/}\n# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)\nAPP_HOME=$( cd -P \"${APP_HOME:-./}\" > /dev/null && printf '%s\\n' \"$PWD\" ) || exit\n\n# Use the maximum available, or set MAX_FD != -1 to use that value.\nMAX_FD=maximum\n\nwarn () {\n echo \"$*\"\n} >&2\n\ndie () {\n echo\n echo \"$*\"\n echo\n exit 1\n} >&2\n\n# OS specific support (must be 'true' or 'false').\ncygwin=false\nmsys=false\ndarwin=false\nnonstop=false\ncase \"$( uname )\" in #(\n CYGWIN* ) cygwin=true ;; #(\n Darwin* ) darwin=true ;; #(\n MSYS* | MINGW* ) msys=true ;; #(\n NONSTOP* ) nonstop=true ;;\nesac\n\nCLASSPATH=\"\\\\\\\"\\\\\\\"\"\n\n\n# Determine the Java command to use to start the JVM.\nif [ -n \"$JAVA_HOME\" ] ; then\n if [ -x \"$JAVA_HOME/jre/sh/java\" ] ; then\n # IBM's JDK on AIX uses strange locations for the executables\n JAVACMD=$JAVA_HOME/jre/sh/java\n else\n JAVACMD=$JAVA_HOME/bin/java\n fi\n if [ ! -x \"$JAVACMD\" ] ; then\n die \"ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME\n\nPlease set the JAVA_HOME variable in your environment to match the\nlocation of your Java installation.\"\n fi\nelse\n JAVACMD=java\n if ! command -v java >/dev/null 2>&1\n then\n die \"ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.\n\nPlease set the JAVA_HOME variable in your environment to match the\nlocation of your Java installation.\"\n fi\nfi\n\n# Increase the maximum file descriptors if we can.\nif ! \"$cygwin\" && ! \"$darwin\" && ! \"$nonstop\" ; then\n case $MAX_FD in #(\n max*)\n # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.\n # shellcheck disable=SC2039,SC3045\n MAX_FD=$( ulimit -H -n ) ||\n warn \"Could not query maximum file descriptor limit\"\n esac\n case $MAX_FD in #(\n '' | soft) :;; #(\n *)\n # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.\n # shellcheck disable=SC2039,SC3045\n ulimit -n \"$MAX_FD\" ||\n warn \"Could not set maximum file descriptor limit to $MAX_FD\"\n esac\nfi\n\n# Collect all arguments for the java command, stacking in reverse order:\n# * args from the command line\n# * the main class name\n# * -classpath\n# * -D...appname settings\n# * --module-path (only if needed)\n# * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.\n\n# For Cygwin or MSYS, switch paths to Windows format before running java\nif \"$cygwin\" || \"$msys\" ; then\n APP_HOME=$( cygpath --path --mixed \"$APP_HOME\" )\n CLASSPATH=$( cygpath --path --mixed \"$CLASSPATH\" )\n\n JAVACMD=$( cygpath --unix \"$JAVACMD\" )\n\n # Now convert the arguments - kludge to limit ourselves to /bin/sh\n for arg do\n if\n case $arg in #(\n -*) false ;; # don't mess with options #(\n /?*) t=${arg#/} t=/${t%%/*} # looks like a POSIX filepath\n [ -e \"$t\" ] ;; #(\n *) false ;;\n esac\n then\n arg=$( cygpath --path --ignore --mixed \"$arg\" )\n fi\n # Roll the args list around exactly as many times as the number of\n # args, so each arg winds up back in the position where it started, but\n # possibly modified.\n #\n # NB: a `for` loop captures its iteration list before it begins, so\n # changing the positional parameters here affects neither the number of\n # iterations, nor the values presented in `arg`.\n shift # remove old arg\n set -- \"$@\" \"$arg\" # push replacement arg\n done\nfi\n\n\n# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.\nDEFAULT_JVM_OPTS='\"-Xmx64m\" \"-Xms64m\"'\n\n# Collect all arguments for the java command:\n# * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,\n# and any embedded shellness will be escaped.\n# * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be\n# treated as '${Hostname}' itself on the command line.\n\nset -- \\\n \"-Dorg.gradle.appname=$APP_BASE_NAME\" \\\n -classpath \"$CLASSPATH\" \\\n -jar \"$APP_HOME/gradle/wrapper/gradle-wrapper.jar\" \\\n \"$@\"\n\n# Stop when \"xargs\" is not available.\nif ! command -v xargs >/dev/null 2>&1\nthen\n die \"xargs is not available\"\nfi\n\n# Use \"xargs\" to parse quoted args.\n#\n# With -n1 it outputs one arg per line, with the quotes and backslashes removed.\n#\n# In Bash we could simply go:\n#\n# readarray ARGS < <( xargs -n1 <<<\"$var\" ) &&\n# set -- \"${ARGS[@]}\" \"$@\"\n#\n# but POSIX shell has neither arrays nor command substitution, so instead we\n# post-process each arg (as a line of input to sed) to backslash-escape any\n# character that might be a shell metacharacter, then use eval to reverse\n# that process (while maintaining the separation between arguments), and wrap\n# the whole thing up as a single \"set\" statement.\n#\n# This will of course break if any of these variables contains a newline or\n# an unmatched quote.\n#\n\neval \"set -- $(\n printf '%s\\n' \"$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS\" |\n xargs -n1 |\n sed ' s~[^-[:alnum:]+,./:=@_]~\\\\&~g; ' |\n tr '\\n' ' '\n )\" '\"$@\"'\n\nexec \"$JAVACMD\" \"$@\"\n" }, { "path": "gradlew.bat", "content": "@rem\r\n@rem Copyright 2015 the original author or authors.\r\n@rem\r\n@rem Licensed under the Apache License, Version 2.0 (the \"License\");\r\n@rem you may not use this file except in compliance with the License.\r\n@rem You may obtain a copy of the License at\r\n@rem\r\n@rem https://www.apache.org/licenses/LICENSE-2.0\r\n@rem\r\n@rem Unless required by applicable law or agreed to in writing, software\r\n@rem distributed under the License is distributed on an \"AS IS\" BASIS,\r\n@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r\n@rem See the License for the specific language governing permissions and\r\n@rem limitations under the License.\r\n@rem\r\n@rem SPDX-License-Identifier: Apache-2.0\r\n@rem\r\n\r\n@if \"%DEBUG%\"==\"\" @echo off\r\n@rem ##########################################################################\r\n@rem\r\n@rem Gradle startup script for Windows\r\n@rem\r\n@rem ##########################################################################\r\n\r\n@rem Set local scope for the variables with windows NT shell\r\nif \"%OS%\"==\"Windows_NT\" setlocal\r\n\r\nset DIRNAME=%~dp0\r\nif \"%DIRNAME%\"==\"\" set DIRNAME=.\r\n@rem This is normally unused\r\nset APP_BASE_NAME=%~n0\r\nset APP_HOME=%DIRNAME%\r\n\r\n@rem Resolve any \".\" and \"..\" in APP_HOME to make it shorter.\r\nfor %%i in (\"%APP_HOME%\") do set APP_HOME=%%~fi\r\n\r\n@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.\r\nset DEFAULT_JVM_OPTS=\"-Xmx64m\" \"-Xms64m\"\r\n\r\n@rem Find java.exe\r\nif defined JAVA_HOME goto findJavaFromJavaHome\r\n\r\nset JAVA_EXE=java.exe\r\n%JAVA_EXE% -version >NUL 2>&1\r\nif %ERRORLEVEL% equ 0 goto execute\r\n\r\necho. 1>&2\r\necho ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2\r\necho. 1>&2\r\necho Please set the JAVA_HOME variable in your environment to match the 1>&2\r\necho location of your Java installation. 1>&2\r\n\r\ngoto fail\r\n\r\n:findJavaFromJavaHome\r\nset JAVA_HOME=%JAVA_HOME:\"=%\r\nset JAVA_EXE=%JAVA_HOME%/bin/java.exe\r\n\r\nif exist \"%JAVA_EXE%\" goto execute\r\n\r\necho. 1>&2\r\necho ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2\r\necho. 1>&2\r\necho Please set the JAVA_HOME variable in your environment to match the 1>&2\r\necho location of your Java installation. 1>&2\r\n\r\ngoto fail\r\n\r\n:execute\r\n@rem Setup the command line\r\n\r\nset CLASSPATH=\r\n\r\n\r\n@rem Execute Gradle\r\n\"%JAVA_EXE%\" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% \"-Dorg.gradle.appname=%APP_BASE_NAME%\" -classpath \"%CLASSPATH%\" -jar \"%APP_HOME%\\gradle\\wrapper\\gradle-wrapper.jar\" %*\r\n\r\n:end\r\n@rem End local scope for the variables with windows NT shell\r\nif %ERRORLEVEL% equ 0 goto mainEnd\r\n\r\n:fail\r\nrem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of\r\nrem the _cmd.exe /c_ return code!\r\nset EXIT_CODE=%ERRORLEVEL%\r\nif %EXIT_CODE% equ 0 set EXIT_CODE=1\r\nif not \"\"==\"%GRADLE_EXIT_CONSOLE%\" exit %EXIT_CODE%\r\nexit /b %EXIT_CODE%\r\n\r\n:mainEnd\r\nif \"%OS%\"==\"Windows_NT\" endlocal\r\n\r\n:omega\r\n" }, { "path": "jbang-catalog.json", "content": "{\n \"catalogs\": {},\n \"aliases\": {\n \"pkl\": {\n \"script-ref\": \"org.pkl-lang:pkl-cli-java:0.31.0\",\n \"java-agents\": []\n },\n \"pkl-codegen-java\": {\n \"script-ref\": \"org.pkl-lang:pkl-codegen-java:0.31.0\",\n \"java-agents\": []\n },\n \"pkl-codegen-kotlin\": {\n \"script-ref\": \"org.pkl-lang:pkl-codegen-kotlin:0.31.0\",\n \"java-agents\": []\n }\n },\n \"templates\": {}\n}\n" }, { "path": "pkl-bom/pkl-bom.gradle.kts", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nplugins {\n pklAllProjects\n `java-platform`\n `maven-publish`\n signing\n}\n\ndescription = \"Pkl BOM that includes all modules\"\n\ndependencies {\n constraints {\n api(projects.pklCli)\n api(projects.pklCodegenJava)\n api(projects.pklCodegenKotlin)\n // Use explicit coordinates for pkl-config-java to avoid ambiguity with fatJar publication\n api(\"${project.group}:pkl-config-java:${project.version}\")\n api(\"${project.group}:pkl-config-java-all:${project.version}\")\n api(projects.pklConfigKotlin)\n api(projects.pklCore)\n api(projects.pklDoc)\n api(projects.pklExecutor)\n api(projects.pklFormatter)\n api(projects.pklGradle)\n api(projects.pklParser)\n api(projects.pklTools)\n }\n}\n\npublishing {\n publications {\n create(\"library\") {\n from(components[\"javaPlatform\"])\n pom {\n url.set(\"https://github.com/apple/pkl/tree/main/pkl-bom\")\n description.set(\"Bill of Materials for managing Pkl dependency versions\")\n }\n }\n }\n}\n\nconfigurePklPomMetadata()\n\nconfigurePomValidation()\n\nconfigurePklSigning()\n" }, { "path": "pkl-cli/README.adoc", "content": "Command-line interface for Pkl.\n\nThe CLI provides the following tools:\n\n* Batch evaluator\n* REPL\n" }, { "path": "pkl-cli/gradle.lockfile", "content": "# This is a Gradle generated file for dependency locking.\n# Manual edits can break the build and are not advised.\n# This file is expected to be part of source control.\ncom.ethlo.time:itu:1.10.3=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.fasterxml.jackson.core:jackson-annotations:2.19.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.fasterxml.jackson.core:jackson-core:2.19.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.fasterxml.jackson.core:jackson-databind:2.19.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.19.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.19.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.fasterxml.jackson:jackson-bom:2.19.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-core-jvm:5.0.3=compileClasspath,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-core:5.0.3=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-jvm:5.0.3=compileClasspath,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-markdown-jvm:5.0.3=nativeImageClasspath,runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-markdown:5.0.3=nativeImageClasspath,runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt:5.0.3=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.colormath:colormath-jvm:3.6.0=compileClasspath,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.colormath:colormath:3.6.0=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-core-jvm:3.0.1=compileClasspath,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-core:3.0.1=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-ffm-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-ffm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-graal-ffi-jvm:3.0.1=nativeImageClasspath,runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-graal-ffi:3.0.1=nativeImageClasspath,runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-jna-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-jna:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm:3.0.1=compileClasspath,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-markdown-jvm:3.0.1=nativeImageClasspath,runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-markdown:3.0.1=nativeImageClasspath,runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant:3.0.1=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ben-manes.caffeine:caffeine:2.9.3=swiftExportClasspathResolvable\ncom.github.jknack:handlebars-helpers:4.3.1=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.jknack:handlebars:4.3.1=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.google.errorprone:error_prone_annotations:2.28.0=swiftExportClasspathResolvable\ncom.google.errorprone:error_prone_annotations:2.36.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.google.guava:failureaccess:1.0.3=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.google.guava:guava:33.4.8-jre=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.google.j2objc:j2objc-annotations:3.0.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.jayway.jsonpath:json-path:2.9.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.networknt:json-schema-validator:1.5.7=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncommons-fileupload:commons-fileupload:1.6.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncommons-io:commons-io:2.19.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\nio.github.java-diff-utils:java-diff-utils:4.12=kotlinInternalAbiValidation\nio.opentelemetry:opentelemetry-api:1.41.0=swiftExportClasspathResolvable\nio.opentelemetry:opentelemetry-context:1.41.0=swiftExportClasspathResolvable\nnet.bytebuddy:byte-buddy:1.17.7=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\nnet.java.dev.jna:jna:5.14.0=runtimeClasspath,testRuntimeClasspath\nnet.javacrumbs.json-unit:json-unit-core:2.40.1=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\nnet.minidev:accessors-smart:2.5.0=testRuntimeClasspath\nnet.minidev:json-smart:2.5.0=testRuntimeClasspath\nnet.sf.jopt-simple:jopt-simple:5.0.4=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.apache.httpcomponents.client5:httpclient5:5.5=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.apache.httpcomponents.core5:httpcore5-h2:5.3.4=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.apache.httpcomponents.core5:httpcore5:5.3.4=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.apiguardian:apiguardian-api:1.1.2=testCompileClasspath,testImplementationDependenciesMetadata\norg.assertj:assertj-core:3.27.6=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.bouncycastle:bcpg-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcpkix-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcprov-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcutil-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.checkerframework:checker-qual:3.43.0=swiftExportClasspathResolvable\norg.eclipse.jetty.http2:http2-common:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty.http2:http2-hpack:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty.http2:http2-server:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty.toolchain:jetty-jakarta-servlet-api:5.0.2=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-alpn-client:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-alpn-java-client:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-alpn-java-server:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-alpn-server:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-bom:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-client:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-http:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-io:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-proxy:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-security:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-server:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-servlet:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-servlets:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-util:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-webapp:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.eclipse.jetty:jetty-xml:11.0.24=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.fusesource.jansi:jansi:2.4.2=compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.graalvm.polyglot:polyglot:25.0.0=compileClasspath,compileOnlyDependenciesMetadata,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.graalvm.sdk:collections:25.0.0=compileClasspath,compileOnlyDependenciesMetadata,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.graalvm.sdk:graal-sdk:25.0.0=compileClasspath,compileOnlyDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testRuntimeClasspath\norg.graalvm.sdk:jniutils:25.0.0=compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.graalvm.sdk:nativeimage:25.0.0=compileClasspath,compileOnlyDependenciesMetadata,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.graalvm.sdk:word:25.0.0=compileClasspath,compileOnlyDependenciesMetadata,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.graalvm.truffle:truffle-api:25.0.0=compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.graalvm.truffle:truffle-compiler:25.0.0=compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.graalvm.truffle:truffle-runtime:25.0.0=compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.hamcrest:hamcrest-core:2.2=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.hamcrest:hamcrest:2.2=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:abi-tools-api:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:abi-tools:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-build-tools-api:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-build-tools-impl:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-compiler-runner:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-client:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-klib-commonizer-embeddable:2.2.20=kotlinKlibCommonizerClasspath\norg.jetbrains.kotlin:kotlin-metadata-jvm:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-native-prebuilt:2.0.21=kotlinNativeBundleConfiguration\norg.jetbrains.kotlin:kotlin-reflect:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-script-runtime:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-scripting-common:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-compiler-impl-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-jvm:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-stdlib-jdk7:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib-jdk8:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,nativeImageClasspath,runtimeClasspath,swiftExportClasspathResolvable,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:swift-export-embeddable:2.2.20=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.8.0=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-bom:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core-jvm:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3=swiftExportClasspathResolvable\norg.jetbrains:annotations:13.0=compileClasspath,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,nativeImageClasspath,runtimeClasspath,swiftExportClasspathResolvable,testCompileClasspath,testRuntimeClasspath\norg.jetbrains:markdown-jvm:0.7.3=nativeImageClasspath,runtimeClasspath,testRuntimeClasspath\norg.jetbrains:markdown:0.7.3=nativeImageClasspath,runtimeClasspath,testRuntimeClasspath\norg.jline:jline-native:3.23.0=compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jline:jline-reader:3.23.0=compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jline:jline-terminal-jansi:3.23.0=compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jline:jline-terminal:3.23.0=compileClasspath,implementationDependenciesMetadata,nativeImageClasspath,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jspecify:jspecify:1.0.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-api:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-engine:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-params:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-commons:1.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-engine:1.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-launcher:1.14.0=testRuntimeClasspath\norg.junit:junit-bom:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.msgpack:msgpack-core:0.9.8=nativeImageClasspath,runtimeClasspath,testRuntimeClasspath\norg.opentest4j:opentest4j:1.3.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.organicdesign:Paguro:3.10.3=nativeImageClasspath,runtimeClasspath,testRuntimeClasspath\norg.slf4j:slf4j-api:2.0.17=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.snakeyaml:snakeyaml-engine:2.10=nativeImageClasspath,runtimeClasspath,testRuntimeClasspath\norg.wiremock:wiremock:3.13.1=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.xmlunit:xmlunit-core:2.10.2=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.xmlunit:xmlunit-legacy:2.10.2=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.xmlunit:xmlunit-placeholders:2.10.2=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.yaml:snakeyaml:2.4=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\nempty=annotationProcessor,intransitiveDependenciesMetadata,javaExecutable,kotlinCompilerPluginClasspath,kotlinNativeCompilerPluginClasspath,kotlinScriptDefExtensions,shadow,signatures,sourcesJar,stagedAlpineLinuxAmd64Executable,stagedLinuxAarch64Executable,stagedLinuxAmd64Executable,stagedMacAarch64Executable,stagedMacAmd64Executable,stagedWindowsAmd64Executable,testAnnotationProcessor,testApiDependenciesMetadata,testCompileOnlyDependenciesMetadata,testIntransitiveDependenciesMetadata,testKotlinScriptDefExtensions\n" }, { "path": "pkl-cli/pkl-cli.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nimport java.io.ByteArrayOutputStream\nimport java.io.OutputStream\nimport org.gradle.kotlin.dsl.support.serviceOf\n\nplugins {\n pklAllProjects\n pklKotlinLibrary\n pklPublishLibrary\n pklJavaExecutable\n pklNativeExecutable\n `maven-publish`\n\n // already on build script class path (see buildSrc/build.gradle.kts),\n // hence must only specify plugin ID here\n id(libs.plugins.shadow.get().pluginId)\n\n alias(libs.plugins.checksum)\n}\n\n// make Java executable available to other subprojects\nval javaExecutableConfiguration: Configuration = configurations.create(\"javaExecutable\")\n\npublishing {\n publications {\n named(\"library\") {\n pom {\n url.set(\"https://github.com/apple/pkl/tree/main/pkl-cli\")\n description.set(\"Pkl CLI Java library.\")\n }\n }\n }\n}\n\ndependencies {\n implementation(libs.truffleRuntime)\n compileOnly(libs.graalSdk)\n\n // CliEvaluator exposes PClass\n api(projects.pklCore)\n // CliEvaluatorOptions exposes CliBaseOptions\n api(projects.pklCommonsCli)\n\n implementation(projects.pklCommons)\n implementation(libs.jansi)\n implementation(libs.jlineReader)\n implementation(libs.jlineTerminal)\n implementation(libs.jlineTerminalJansi)\n implementation(projects.pklServer)\n implementation(projects.pklFormatter)\n implementation(libs.clikt)\n\n testImplementation(projects.pklCommonsTest)\n testImplementation(libs.wiremock)\n}\n\ntasks.jar {\n manifest.attributes +=\n mapOf(\"Main-Class\" to \"org.pkl.cli.Main\", \"Add-Exports\" to buildInfo.jpmsExportsForJarManifest)\n}\n\ntasks.javadoc { enabled = false }\n\ntasks.shadowJar {\n archiveFileName.set(\"jpkl\")\n\n exclude(\"META-INF/maven/**\")\n exclude(\"META-INF/upgrade/**\")\n\n exclude(\"module-info.*\")\n}\n\nval testJavaExecutable by\n tasks.registering(Test::class) {\n testClassesDirs = tasks.test.get().testClassesDirs\n classpath =\n // compiled test classes\n sourceSets.test.get().output +\n // java executable\n tasks.javaExecutable.get().outputs.files +\n // test-only dependencies\n // (test dependencies that are also main dependencies must already be contained in java\n // executable;\n // to verify that, we don't want to include them here)\n (configurations.testRuntimeClasspath.get() - configurations.runtimeClasspath.get())\n }\n\n// Setup `testJavaExecutable` tasks for multi-JDK testing.\nval testJavaExecutableOnOtherJdks = buildInfo.multiJdkTestingWith(testJavaExecutable)\n\n// Prepare a run of the fat JAR, optionally with a specific Java launcher.\nprivate fun setupJavaExecutableRun(\n name: String,\n args: Array,\n launcher: Provider? = null,\n configurator: Exec.() -> Unit = {},\n) =\n tasks.register(name, Exec::class) {\n dependsOn(tasks.javaExecutable)\n val outputFile = layout.buildDirectory.file(name) // dummy output to satisfy up-to-date check\n outputs.file(outputFile)\n\n executable =\n when (launcher) {\n null -> \"java\"\n else -> launcher.get().executablePath.asFile.absolutePath\n }\n standardOutput = OutputStream.nullOutputStream()\n\n args(\"-jar\", tasks.javaExecutable.get().outputs.files.singleFile.toString(), *args)\n\n doFirst { outputFile.get().asFile.delete() }\n\n doLast { outputFile.get().asFile.writeText(\"OK\") }\n\n configurator()\n }\n\nval evalTestFlags = arrayOf(\"eval\", \"-x\", \"1 + 1\", \"pkl:base\")\n\nfun Exec.useRootDirAndSuppressOutput() {\n workingDir = rootProject.layout.projectDirectory.asFile\n standardOutput = ByteArrayOutputStream() // we only care that this exec doesn't fail\n}\n\n// 0.28 Preparing for JDK21 toolchains revealed that `testStartJavaExecutable` may pass, even though\n// the evaluator fails. To catch this, we eval a simple expression using the fat jar.\nval testEvalJavaExecutable by\n setupJavaExecutableRun(\"testEvalJavaExecutable\", evalTestFlags) { useRootDirAndSuppressOutput() }\n\n// Run the same evaluator tests on all configured JDK test versions.\nval testEvalJavaExecutableOnOtherJdks =\n buildInfo.jdkTestRange.map { jdkTarget ->\n setupJavaExecutableRun(\n \"testEvalJavaExecutableJdk${jdkTarget.asInt()}\",\n evalTestFlags,\n serviceOf().launcherFor { languageVersion = jdkTarget },\n ) {\n useRootDirAndSuppressOutput()\n }\n }\n\ntasks.check {\n dependsOn(\n testJavaExecutable,\n testJavaExecutableOnOtherJdks,\n testEvalJavaExecutable,\n testEvalJavaExecutableOnOtherJdks,\n )\n}\n\ntasks.checkNative {\n dependsOn(\":pkl-core:checkNative\")\n dependsOn(\":pkl-server:checkNative\")\n}\n\nexecutable {\n name = \"pkl\"\n javaName = \"jpkl\"\n documentationName = \"Pkl CLI\"\n publicationName = \"pkl-cli\"\n javaPublicationName = \"pkl-cli-java\"\n mainClass = \"org.pkl.cli.Main\"\n website = \"https://pkl-lang.org/main/current/pkl-cli/index.html\"\n}\n\n// make Java executable available to other subprojects\n// (we don't do the same for native executables because we don't want tasks assemble/build to build\n// them)\nartifacts {\n add(\"javaExecutable\", tasks.javaExecutable.map { it.outputs.files.singleFile }) {\n name = \"pkl-cli-java\"\n classifier = null\n extension = \"jar\"\n builtBy(tasks.javaExecutable)\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliCommandRunner.kt", "content": "/*\n * Copyright © 2025-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport com.github.ajalt.clikt.completion.CompletionCandidates\nimport com.github.ajalt.clikt.completion.CompletionCommand\nimport com.github.ajalt.clikt.core.*\nimport com.github.ajalt.clikt.parameters.arguments.*\nimport com.github.ajalt.clikt.parameters.options.*\nimport com.github.ajalt.clikt.parameters.types.int\nimport java.io.OutputStream\nimport java.net.URI\nimport java.nio.file.Path\nimport kotlin.io.path.createParentDirectories\nimport kotlin.io.path.exists\nimport kotlin.io.path.isDirectory\nimport kotlin.io.path.writeBytes\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.CliCommand\nimport org.pkl.commons.cli.CliException\nimport org.pkl.commons.cli.commands.installCommonOptions\nimport org.pkl.commons.currentWorkingDir\nimport org.pkl.core.Closeables\nimport org.pkl.core.CommandSpec\nimport org.pkl.core.EvaluatorBuilder\nimport org.pkl.core.FileOutput\nimport org.pkl.core.ModuleSource.uri\nimport org.pkl.core.PklBugException\nimport org.pkl.core.PklException\nimport org.pkl.core.util.IoUtils\n\nclass CliCommandRunner\n@JvmOverloads\nconstructor(\n private val options: CliBaseOptions,\n private val reservedFlagNames: Set,\n private val reservedFlagShortNames: Set,\n private val args: List,\n private val outputStream: OutputStream = System.out,\n private val errStream: OutputStream = System.err,\n) : CliCommand(options) {\n\n override fun doRun() {\n val builder = evaluatorBuilder()\n try {\n evalCmd(builder)\n } finally {\n Closeables.closeQuietly(builder.moduleKeyFactories)\n Closeables.closeQuietly(builder.resourceReaders)\n }\n }\n\n private fun evalCmd(builder: EvaluatorBuilder) {\n val evaluator = builder.build()\n evaluator.use {\n evaluator.evaluateCommand(\n uri(resolvedSourceModules.first()),\n reservedFlagNames,\n reservedFlagShortNames,\n ) { spec ->\n try {\n val root = SynthesizedRunCommand(spec, this, options.sourceModules.first().toString())\n root.installCommonOptions(includeVersion = false)\n root.subcommands(\n CompletionCommand(\n name = \"shell-completion\",\n help = \"Generate a completion script for the given shell\",\n )\n )\n root.parse(args)\n } catch (e: PklException) {\n throw e\n } catch (e: Exception) {\n throw e.message?.let { PklException(it, e) } ?: PklException(e)\n }\n }\n }\n }\n\n /** Renders the comand's `output.bytes`, writing it to the standard output stream. */\n fun writeOutput(outputBytes: ByteArray) {\n if (outputBytes.isEmpty()) return\n outputStream.write(outputBytes)\n outputStream.flush()\n }\n\n /**\n * Renders the command's `output.files`, writing each entry as a file.\n *\n * File paths are written to the standard error stream.\n *\n * Unlike CliEvaluator, command outputs write relative to --working-dir and may write files\n * anywhere in the filesystem. This is intentionally less sandboxed than `pkl eval` and directly\n * targets the capabilities of CLI tools written in general purpose languages. Pkl commands should\n * therefore be treated as untrusted code the way that any other CLI tool would be.\n */\n fun writeMultipleFileOutput(outputFiles: Map) {\n if (outputFiles.isEmpty()) return\n\n val writtenFiles = mutableMapOf()\n val outputDir = options.normalizedWorkingDir\n if (outputDir.exists() && !outputDir.isDirectory()) {\n throw CliException(\"Output path `$outputDir` exists and is not a directory.\")\n }\n for ((pathSpec, fileOutput) in outputFiles) {\n checkPathSpec(pathSpec)\n val resolvedPath = outputDir.resolve(pathSpec).normalize()\n val realPath = if (resolvedPath.exists()) resolvedPath.toRealPath() else resolvedPath\n val previousOutput = writtenFiles[realPath]\n if (previousOutput != null) {\n throw CliException(\n \"Output file conflict: `output.files` entries `\\\"${previousOutput}\\\"` and `\\\"$pathSpec\\\"` resolve to the same file path `$realPath`.\"\n )\n }\n if (realPath.isDirectory()) {\n throw CliException(\n \"Output file conflict: `output.files` entry `\\\"$pathSpec\\\"` resolves to file path `$realPath`, which is a directory.\"\n )\n }\n writtenFiles[realPath] = pathSpec\n realPath.createParentDirectories()\n realPath.writeBytes(fileOutput.bytes)\n val displayPath =\n if (Path.of(pathSpec).isAbsolute) pathSpec\n else IoUtils.relativize(resolvedPath, currentWorkingDir).toString()\n errStream.writeText(displayPath + IoUtils.getLineSeparator())\n errStream.flush()\n }\n }\n\n class SynthesizedRunCommand(\n private val spec: CommandSpec,\n private val runner: CliCommandRunner,\n name: String? = null,\n ) : CliktCommand(name = name ?: spec.name) {\n init {\n spec.options.forEach { opt ->\n when (opt) {\n is CommandSpec.Flag ->\n registerOption(\n option(\n names = opt.names,\n help = opt.helpText ?: \"\",\n metavar = opt.metavar,\n hidden = opt.hidden,\n completionCandidates = opt.completionCandidates?.toClikt(),\n )\n .convert {\n try {\n opt.transformEach.apply(it, workingDirUri)\n } catch (e: CommandSpec.Option.BadValue) {\n fail(e.message!!)\n } catch (_: CommandSpec.Option.MissingOption) {\n throw MissingOption(option)\n }\n }\n .transformAll(opt.defaultValue, opt.showAsRequired) {\n try {\n opt.transformAll.apply(it, workingDirUri)\n } catch (e: CommandSpec.Option.BadValue) {\n fail(e.message!!)\n } catch (_: CommandSpec.Option.MissingOption) {\n throw MissingOption(option)\n }\n }\n )\n is CommandSpec.BooleanFlag ->\n registerOption(\n if (opt.defaultValue != null)\n option(names = opt.names, help = opt.helpText ?: \"\", hidden = opt.hidden)\n .flag(\"--no-${opt.name}\", default = opt.defaultValue!!)\n else\n option(names = opt.names, help = opt.helpText ?: \"\", hidden = opt.hidden)\n .nullableFlag(\"--no-${opt.name}\")\n )\n is CommandSpec.CountedFlag ->\n registerOption(\n option(names = opt.names, help = opt.helpText ?: \"\", hidden = opt.hidden)\n .int()\n .transformValues(0..0) { it.lastOrNull() ?: 1 }\n .transformAll { it.sum().toLong() }\n )\n is CommandSpec.Argument ->\n registerArgument(\n argument(\n opt.name,\n opt.helpText ?: \"\",\n completionCandidates = opt.completionCandidates?.toClikt(),\n )\n .convert {\n try {\n opt.transformEach.apply(it, workingDirUri)\n } catch (e: CommandSpec.Option.BadValue) {\n fail(e.message!!)\n } catch (_: CommandSpec.Option.MissingOption) {\n throw MissingArgument(argument)\n }\n }\n .transformAll(if (opt.repeated) -1 else 1, !opt.repeated) {\n try {\n opt.transformAll.apply(it, workingDirUri)\n } catch (e: CommandSpec.Option.BadValue) {\n fail(e.message!!)\n } catch (_: CommandSpec.Option.MissingOption) {\n throw MissingArgument(argument)\n }\n }\n )\n }\n }\n spec.subcommands.forEach { subcommands(SynthesizedRunCommand(it, runner)) }\n }\n\n val workingDirUri: URI by lazy { runner.options.normalizedWorkingDir.toUri() }\n\n override val invokeWithoutSubcommand = true\n\n override val hiddenFromHelp: Boolean = spec.hidden\n\n override fun help(context: Context): String = spec.helpText ?: \"\"\n\n override fun run() {\n if (currentContext.invokedSubcommand is CompletionCommand) return\n\n val opts =\n registeredOptions()\n .mapNotNull {\n val opt = it as? OptionWithValues<*, *, *> ?: return@mapNotNull null\n return@mapNotNull if (it.names.contains(\"--help\")) null\n else it.names.last().trimStart('-') to opt.value\n }\n .toMap() +\n registeredArguments()\n .mapNotNull { it as? ArgumentDelegate<*> }\n .associateBy({ it.name }, { it.value })\n\n val state = spec.apply.apply(opts, currentContext.obj as CommandSpec.State?)\n currentContext.obj = state\n\n if (currentContext.invokedSubcommand != null) return\n if (spec.subcommands.isNotEmpty() && spec.noOp) {\n throw PrintHelpMessage(currentContext, true, 1)\n }\n\n val result = state.evaluate()\n runner.writeOutput(result.outputBytes)\n runner.writeMultipleFileOutput(result.outputFiles)\n }\n }\n}\n\nfun CommandSpec.CompletionCandidates.toClikt(): CompletionCandidates =\n when (this) {\n CommandSpec.CompletionCandidates.PATH -> CompletionCandidates.Path\n is CommandSpec.CompletionCandidates.Fixed -> CompletionCandidates.Fixed(values)\n else -> throw PklBugException.unreachableCode()\n }\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliEvaluator.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.io.File\nimport java.io.InputStream\nimport java.io.OutputStream\nimport java.net.URI\nimport java.nio.charset.StandardCharsets\nimport java.nio.file.Files\nimport java.nio.file.Path\nimport java.nio.file.StandardOpenOption\nimport kotlin.io.path.createParentDirectories\nimport kotlin.io.path.exists\nimport kotlin.io.path.isDirectory\nimport kotlin.io.path.writeBytes\nimport org.pkl.commons.cli.CliCommand\nimport org.pkl.commons.cli.CliException\nimport org.pkl.commons.currentWorkingDir\nimport org.pkl.commons.writeString\nimport org.pkl.core.Closeables\nimport org.pkl.core.Evaluator\nimport org.pkl.core.EvaluatorBuilder\nimport org.pkl.core.ModuleSource\nimport org.pkl.core.PklException\nimport org.pkl.core.module.ModulePathResolver\nimport org.pkl.core.runtime.ModuleResolver\nimport org.pkl.core.runtime.VmException\nimport org.pkl.core.runtime.VmUtils\nimport org.pkl.core.util.IoUtils\n\nprivate data class OutputFile(val pathSpec: String, val moduleUri: URI)\n\n/** API equivalent of the Pkl command-line evaluator. */\nclass CliEvaluator\n@JvmOverloads\nconstructor(\n private val options: CliEvaluatorOptions,\n // use System.{in,out}() rather than System.console()\n // because the latter returns null when output is sent through a unix pipe\n private val inputStream: InputStream = System.`in`,\n private val outputStream: OutputStream = System.out,\n) : CliCommand(options.base) {\n /**\n * Output files for the modules to be evaluated. Returns `null` if `options.outputPath` is `null`\n * or if `options.multipleFileOutputPath` is not `null`. Multiple modules may be mapped to the\n * same output file, in which case their outputs are concatenated with\n * [CliEvaluatorOptions.moduleOutputSeparator].\n */\n @Suppress(\"MemberVisibilityCanBePrivate\")\n val outputFiles: Set? by lazy {\n fileOutputPaths?.values?.mapTo(mutableSetOf(), Path::toFile)\n }\n\n /**\n * Output directories for the modules to be evaluated. Returns `null` if\n * `options.multipleFileOutputPath` is `null`.\n */\n @Suppress(\"MemberVisibilityCanBePrivate\")\n val outputDirectories: Set? by lazy {\n directoryOutputPaths?.values?.mapTo(mutableSetOf(), Path::toFile)\n }\n\n /** The file output path */\n val fileOutputPaths: Map? by lazy {\n if (options.multipleFileOutputPath != null) return@lazy null\n options.outputPath?.let { resolveOutputPaths(it) }\n }\n\n private val directoryOutputPaths: Map? by lazy {\n options.multipleFileOutputPath?.let { resolveOutputPaths(it) }\n }\n\n /**\n * Evaluates source modules according to [options].\n *\n * If [CliEvaluatorOptions.outputPath] is set, each module's `output.bytes` is written to the\n * module's [output file][outputFiles].\n *\n * If [CliEvaluatorOptions.multipleFileOutputPath] is set, each module's `output.files` are\n * written to the module's [output directory][outputDirectories]. Otherwise, each module's\n * `output.bytes` is written to [outputStream] (which defaults to standard out).\n *\n * Throws [CliException] in case of an error.\n */\n override fun doRun() {\n val builder = evaluatorBuilder()\n try {\n if (options.multipleFileOutputPath != null) {\n writeMultipleFileOutput(builder)\n } else {\n writeOutput(builder)\n }\n } finally {\n Closeables.closeQuietly(builder.moduleKeyFactories)\n Closeables.closeQuietly(builder.resourceReaders)\n }\n }\n\n private fun resolveOutputPaths(pathStr: String): Map {\n val workingDir = options.base.normalizedWorkingDir\n // used just to resolve the `%{moduleName}` placeholder\n val moduleResolver = ModuleResolver(moduleKeyFactories(ModulePathResolver.empty()))\n\n return resolvedSourceModules.associateWith { uri ->\n val moduleDir: String? =\n IoUtils.toPath(uri)?.let {\n IoUtils.relativize(it.parent, workingDir).toString().ifEmpty { \".\" }\n }\n val moduleKey =\n try {\n moduleResolver.resolve(uri)\n } catch (e: VmException) {\n throw e.toPklException(stackFrameTransformer, options.base.color?.hasColor() ?: false)\n }\n val substituted =\n pathStr\n .replace(\"%{moduleName}\", IoUtils.inferModuleName(moduleKey))\n .replace(\"%{outputFormat}\", options.outputFormat ?: \"%{outputFormat}\")\n .replace(\"%{moduleDir}\", moduleDir ?: \"%{moduleDir}\")\n if (substituted.contains(\"%{moduleDir}\")) {\n throw PklException(\n \"Cannot substitute output path placeholder `%{moduleDir}` \" +\n \"because module `$uri` does not have a file system path.\"\n )\n }\n val absolutePath = workingDir.resolve(substituted).normalize()\n absolutePath\n }\n }\n\n private fun Evaluator.evalOutput(moduleSource: ModuleSource): ByteArray {\n if (options.expression == null) {\n return evaluateOutputBytes(moduleSource)\n }\n return evaluateExpressionString(moduleSource, options.expression)\n .toByteArray(StandardCharsets.UTF_8)\n }\n\n /** Renders each module's `output.bytes`, writing it to the specified output file. */\n private fun writeOutput(builder: EvaluatorBuilder) {\n val evaluator = builder.setOutputFormat(options.outputFormat).build()\n evaluator.use { ev ->\n val outputFiles = fileOutputPaths\n if (outputFiles != null) {\n // files that we've written non-empty output to\n // YamlRenderer produces empty output if `isStream` is true and `output.value` is empty\n // collection\n val writtenFiles = mutableSetOf()\n\n for ((moduleUri, outputFile) in outputFiles) {\n val moduleSource = toModuleSource(moduleUri, inputStream)\n if (Files.isDirectory(outputFile)) {\n throw CliException(\n \"Output file `$outputFile` is a directory. \" +\n \"Did you mean `--multiple-file-output-path`?\"\n )\n }\n val output = ev.evalOutput(moduleSource)\n outputFile.createParentDirectories()\n if (!writtenFiles.contains(outputFile)) {\n // write file even if output is empty to overwrite output from previous runs\n outputFile.writeBytes(output)\n if (output.isNotEmpty()) {\n writtenFiles.add(outputFile)\n }\n } else {\n if (output.isNotEmpty()) {\n outputFile.writeString(\n options.moduleOutputSeparator + '\\n',\n Charsets.UTF_8,\n StandardOpenOption.WRITE,\n StandardOpenOption.APPEND,\n )\n outputFile.writeBytes(output, StandardOpenOption.WRITE, StandardOpenOption.APPEND)\n }\n }\n }\n } else {\n var outputWritten = false\n for (moduleUri in resolvedSourceModules) {\n val moduleSource = toModuleSource(moduleUri, inputStream)\n if (options.expression != null) {\n val output = evaluator.evaluateExpressionString(moduleSource, options.expression)\n if (output.isNotEmpty()) {\n if (outputWritten) outputStream.writeLine(options.moduleOutputSeparator)\n outputStream.writeText(output)\n outputStream.flush()\n outputWritten = true\n }\n } else {\n val outputBytes = evaluator.evaluateOutputBytes(moduleSource)\n if (outputBytes.isNotEmpty()) {\n if (outputWritten) outputStream.writeLine(options.moduleOutputSeparator)\n outputStream.write(outputBytes)\n outputStream.flush()\n outputWritten = true\n }\n }\n }\n }\n }\n }\n\n private fun toModuleSource(uri: URI, reader: InputStream) =\n if (uri == VmUtils.REPL_TEXT_URI) {\n ModuleSource.create(uri, reader.readAllBytes().toString(StandardCharsets.UTF_8))\n } else {\n ModuleSource.uri(uri)\n }\n\n /**\n * Renders each module's `output.files`, writing each entry as a file into the specified output\n * directory.\n */\n private fun writeMultipleFileOutput(builder: EvaluatorBuilder) {\n val outputDirs = directoryOutputPaths!!\n val writtenFiles = mutableMapOf()\n for ((moduleUri, outputDir) in outputDirs) {\n val evaluator = builder.setOutputFormat(options.outputFormat).build()\n if (outputDir.exists() && !outputDir.isDirectory()) {\n throw CliException(\"Output path `$outputDir` exists and is not a directory.\")\n }\n val moduleSource = toModuleSource(moduleUri, inputStream)\n val output = evaluator.evaluateOutputFiles(moduleSource)\n val realOutputDir = if (outputDir.exists()) outputDir.toRealPath() else outputDir\n\n for ((pathSpec, fileOutput) in output) {\n checkPathSpec(pathSpec)\n val resolvedPath = realOutputDir.resolve(pathSpec).normalize()\n val realPath = if (resolvedPath.exists()) resolvedPath.toRealPath() else resolvedPath\n if (!realPath.startsWith(realOutputDir)) {\n throw CliException(\n \"Output file conflict: `output.files` entry `\\\"$pathSpec\\\"` in module `$moduleUri` resolves to file path `$realPath`, which is outside output directory `$realOutputDir`.\"\n )\n }\n val previousOutput = writtenFiles[realPath]\n if (previousOutput != null) {\n throw CliException(\n \"Output file conflict: `output.files` entries `\\\"${previousOutput.pathSpec}\\\"` in module `${previousOutput.moduleUri}` and `\\\"$pathSpec\\\"` in module `$moduleUri` resolve to the same file path `$realPath`.\"\n )\n }\n if (realPath.isDirectory()) {\n throw CliException(\n \"Output file conflict: `output.files` entry `\\\"$pathSpec\\\"` in module `$moduleUri` resolves to file path `$realPath`, which is a directory.\"\n )\n }\n writtenFiles[realPath] = OutputFile(pathSpec, moduleUri)\n realPath.createParentDirectories()\n realPath.writeBytes(fileOutput.bytes)\n outputStream.writeText(\n IoUtils.relativize(resolvedPath, currentWorkingDir).toString() +\n IoUtils.getLineSeparator()\n )\n outputStream.flush()\n }\n }\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliEvaluatorOptions.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport org.pkl.commons.cli.CliBaseOptions\n\n/** Configuration options for [CliEvaluator]. */\ndata class CliEvaluatorOptions(\n /** Base options shared between CLI commands. */\n val base: CliBaseOptions,\n\n /**\n * The file path where the output file is placed. If multiple source modules are given,\n * placeholders can be used to map them to different output files. If multiple modules are mapped\n * to the same output file, their outputs are concatenated. Currently, the only available\n * concatenation strategy is to separate outputs with `---`, as in a YAML stream.\n *\n * The following placeholders are supported:\n * - `%{moduleDir}` The directory path of the module, relative to the working directory. Only\n * available when evaluating file-based modules.\n * - `%{moduleName}` The simple module name as inferred from the module URI. For hierarchical\n * URIs, this is the last path segment without file extension.\n * - `%{outputFormat}` The requested output format. Only available if `outputFormat` is non-null.\n *\n * If [CliBaseOptions.workingDir] corresponds to a file system path, relative output paths are\n * resolved against that path. Otherwise, relative output paths are not allowed.\n *\n * If `null`, output is written to the console.\n */\n val outputPath: String? = null,\n\n /**\n * The output format to generate.\n *\n * The default output renderer for a module supports the following formats:\n * - `\"json\"`\n * - `\"jsonnet\"`\n * - `\"pcf\"` (default)\n * - `\"plist\"`\n * - `\"properties\"`\n * - `\"textproto\"`\n * - `\"xml\"`\n * - `\"yaml\"`\n */\n val outputFormat: String? = null,\n\n /** The separator to use when multiple module outputs are written to the same location. */\n val moduleOutputSeparator: String = \"---\",\n\n /**\n * The directory where a module's output files are placed.\n *\n * Setting this option causes Pkl to evaluate `output.files` instead of `output.text`, and write\n * files using each entry's key as the file path relative to [multipleFileOutputPath], and each\n * value's `text` property as the file's contents.\n */\n val multipleFileOutputPath: String? = null,\n\n /**\n * The expression to evaluate within the module.\n *\n * If set, the said expression is evaluated under the context of the enclosing module.\n *\n * If unset, the module's `output.bytes` property is evaluated.\n */\n val expression: String? = null,\n) {\n\n companion object {\n val defaults: CliEvaluatorOptions = CliEvaluatorOptions(CliBaseOptions())\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliFormatterCommand.kt", "content": "/*\n * Copyright © 2025-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.io.IOException\nimport java.io.Writer\nimport java.nio.file.Files\nimport java.nio.file.Path\nimport java.util.stream.Stream\nimport kotlin.io.path.extension\nimport kotlin.io.path.isDirectory\nimport kotlin.io.path.name\nimport kotlin.io.path.writeText\nimport kotlin.math.max\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.CliCommand\nimport org.pkl.commons.cli.CliException\nimport org.pkl.commons.cli.CliTestException\nimport org.pkl.core.util.IoUtils\nimport org.pkl.formatter.Formatter\nimport org.pkl.formatter.GrammarVersion\nimport org.pkl.parser.GenericParserError\nimport org.pkl.parser.ParserError\n\nclass CliFormatterCommand\n@JvmOverloads\nconstructor(\n private val paths: List,\n private val grammarVersion: GrammarVersion,\n private val overwrite: Boolean,\n private val diffNameOnly: Boolean,\n private val silent: Boolean,\n private val consoleWriter: Writer = System.out.writer(),\n private val errWriter: Writer = System.err.writer(),\n) : CliCommand(CliBaseOptions()) {\n private fun format(contents: String): String {\n return Formatter().format(contents, grammarVersion)\n }\n\n private fun writeErrLine(error: String) {\n errWriter.write(error)\n errWriter.appendLine()\n errWriter.flush()\n }\n\n private fun writeLine(message: String) {\n if (silent) return\n consoleWriter.write(message)\n consoleWriter.appendLine()\n consoleWriter.flush()\n }\n\n private fun allPaths(): Stream {\n return paths.distinct().stream().flatMap { path ->\n when {\n path.toString() == \"-\" -> Stream.of(path)\n path.isDirectory() ->\n Files.walk(path)\n .filter { it.extension == \"pkl\" || it.name == \"PklProject\" }\n .map { it.normalize() }\n else -> Stream.of(path.normalize())\n }\n }\n }\n\n override fun doRun() {\n val status = Status(SUCCESS)\n\n handlePaths(status)\n\n when (status.status) {\n FORMATTING_VIOLATION -> {\n // using CliTestException instead of CliException because we want full control on how to\n // print errors\n throw CliTestException(\"\", status.status)\n }\n ERROR -> {\n if (!silent) {\n writeErrLine(\"An error occurred during formatting.\")\n }\n throw CliTestException(\"\", status.status)\n }\n }\n }\n\n private fun handlePaths(status: Status) {\n for (path in allPaths()) {\n val pathStr = path.toString()\n try {\n val contents =\n when {\n pathStr == \"-\" -> IoUtils.readString(System.`in`)\n else -> Files.readString(path)\n }\n if (pathStr == \"-\" && overwrite) {\n throw CliException(\"Cannot write to stdin\", ERROR)\n }\n\n val formatted = format(contents)\n if (contents != formatted) {\n if (diffNameOnly || overwrite) {\n // if `--diff-name-only` or `-w` is specified, only write file names\n writeLine(pathStr)\n }\n\n if (overwrite) {\n path.writeText(formatted, Charsets.UTF_8)\n } else {\n // only exit on violation for \"check\" operations, not when overwriting\n status.update(FORMATTING_VIOLATION)\n }\n }\n\n if (!diffNameOnly && !overwrite) {\n consoleWriter.write(formatted)\n consoleWriter.flush()\n }\n } catch (pe: ParserError) { // thrown by the lexer\n writeErrLine(\"Could not format `$pathStr`: $pe\")\n status.update(ERROR)\n } catch (pe: GenericParserError) { // thrown by the generic parser\n writeErrLine(\"Could not format `$pathStr`: $pe\")\n status.update(ERROR)\n } catch (e: IOException) {\n writeErrLine(\"IO error while reading `$pathStr`: ${e.message}\")\n status.update(ERROR)\n }\n }\n }\n\n companion object {\n private const val SUCCESS = 0\n private const val FORMATTING_VIOLATION = 11\n private const val ERROR = 1\n\n private class Status(var status: Int) {\n fun update(newStatus: Int) {\n status =\n when {\n status == ERROR -> status\n newStatus == ERROR -> newStatus\n else -> max(status, newStatus)\n }\n }\n }\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliImportAnalyzer.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.io.Writer\nimport kotlin.io.path.createParentDirectories\nimport org.pkl.commons.cli.CliCommand\nimport org.pkl.commons.writeString\nimport org.pkl.core.Closeables\nimport org.pkl.core.ModuleSource\n\nclass CliImportAnalyzer\n@JvmOverloads\nconstructor(\n private val options: CliImportAnalyzerOptions,\n private val consoleWriter: Writer = System.out.writer(),\n) : CliCommand(options.base) {\n\n override fun doRun() {\n val rendered = render()\n if (options.outputPath != null) {\n options.outputPath.createParentDirectories()\n options.outputPath.writeString(rendered)\n } else {\n consoleWriter.write(rendered)\n consoleWriter.flush()\n }\n }\n\n // language=pkl\n private val sourceModule =\n ModuleSource.text(\n \"\"\"\n import \"pkl:analyze\"\n\n local importStrings = read*(\"prop:pkl.analyzeImports.**\").toMap().values.toSet()\n\n output {\n value = analyze.importGraph(importStrings)\n renderer {\n converters {\n [Map] = (it) -> it.toMapping()\n [Set] = (it) -> it.toListing()\n }\n }\n }\n \"\"\"\n .trimIndent()\n )\n\n private fun render(): String {\n val builder = evaluatorBuilder().setOutputFormat(options.outputFormat)\n try {\n return builder\n .apply {\n for ((idx, sourceModule) in resolvedSourceModules.withIndex()) {\n addExternalProperty(\"pkl.analyzeImports.$idx\", sourceModule.toString())\n }\n }\n .build()\n .use { it.evaluateOutputText(sourceModule) }\n } finally {\n Closeables.closeQuietly(builder.moduleKeyFactories)\n Closeables.closeQuietly(builder.resourceReaders)\n }\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliImportAnalyzerOptions.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.nio.file.Path\nimport org.pkl.commons.cli.CliBaseOptions\n\ndata class CliImportAnalyzerOptions(\n /** Base options shared between CLI commands. */\n val base: CliBaseOptions,\n\n /** The file path where the output file is placed. */\n val outputPath: Path? = null,\n\n /**\n * The output format to generate.\n *\n * These accept the same options as [CliEvaluatorOptions.outputFormat].\n */\n val outputFormat: String? = null,\n)\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliPackageDownloader.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.CliCommand\nimport org.pkl.commons.cli.CliException\nimport org.pkl.core.packages.PackageResolver\nimport org.pkl.core.packages.PackageUri\n\nclass CliPackageDownloader(\n baseOptions: CliBaseOptions,\n private val packageUris: List,\n private val noTransitive: Boolean,\n) : CliCommand(baseOptions) {\n\n override fun doRun() {\n if (moduleCacheDir == null) {\n throw CliException(\"Cannot download packages because no cache directory is specified.\")\n }\n val packageResolver = PackageResolver.getInstance(securityManager, httpClient, moduleCacheDir)\n val errors = mutableMapOf()\n for (pkg in packageUris) {\n try {\n packageResolver.downloadPackage(pkg, pkg.checksums, noTransitive)\n } catch (e: Throwable) {\n errors[pkg] = e\n }\n }\n when (errors.size) {\n 0 -> return\n 1 ->\n throw CliException(\n errors.values.single().message\n ?: (\"An unexpected error occurred: \" + errors.values.single())\n )\n else ->\n throw CliException(\n buildString {\n appendLine(\"Failed to download some packages.\")\n for ((uri, error) in errors) {\n appendLine()\n appendLine(\"Failed to download $uri because:\")\n appendLine(\"${error.message}\")\n }\n }\n )\n }\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliProjectCommand.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.nio.file.Files\nimport java.nio.file.Path\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.CliBaseOptions.Companion.getProjectFile\nimport org.pkl.commons.cli.CliCommand\nimport org.pkl.commons.cli.CliException\nimport org.pkl.core.module.ProjectDependenciesManager.PKL_PROJECT_FILENAME\n\nabstract class CliProjectCommand(cliOptions: CliBaseOptions, private val projectDirs: List) :\n CliCommand(cliOptions) {\n\n protected val normalizedProjectFiles: List by lazy {\n if (projectDirs.isEmpty()) {\n val projectFile =\n cliOptions.normalizedWorkingDir.getProjectFile(cliOptions.normalizedRootDir)\n ?: throw CliException(\n \"No project visible to the working directory. Ensure there is a PklProject file in the workspace, or provide an explicit project directory as an argument.\"\n )\n return@lazy listOf(projectFile.normalize())\n }\n projectDirs.map(cliOptions.normalizedWorkingDir::resolve).map { dir ->\n val projectFile = dir.resolve(PKL_PROJECT_FILENAME)\n if (!Files.exists(projectFile)) {\n throw CliException(\"Directory $dir does not contain a PklProject file.\")\n }\n projectFile.normalize()\n }\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliProjectPackager.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.io.Writer\nimport java.nio.file.Path\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.CliException\nimport org.pkl.commons.cli.CliTestException\nimport org.pkl.commons.cli.CliTestOptions\nimport org.pkl.core.project.Project\nimport org.pkl.core.project.ProjectPackager\nimport org.pkl.core.util.ErrorMessages\n\nclass CliProjectPackager(\n baseOptions: CliBaseOptions,\n projectDirs: List,\n private val testOptions: CliTestOptions,\n private val outputPath: String,\n private val skipPublishCheck: Boolean,\n private val consoleWriter: Writer = System.out.writer(),\n private val errWriter: Writer = System.err.writer(),\n) : CliProjectCommand(baseOptions, projectDirs) {\n\n private fun runApiTests(project: Project) {\n val apiTests = project.`package`!!.apiTests()\n if (apiTests.isEmpty()) return\n val normalizeApiTests = apiTests.map { project.projectDir.resolve(it).toUri() }\n val testRunner =\n CliTestRunner(\n cliOptions.copy(sourceModules = normalizeApiTests, projectDir = project.projectDir),\n testOptions = testOptions,\n consoleWriter = consoleWriter,\n errWriter = errWriter,\n )\n try {\n testRunner.run()\n } catch (e: CliTestException) {\n throw CliException(ErrorMessages.create(\"packageTestsFailed\", project.`package`!!.uri()))\n }\n }\n\n override fun doRun() {\n val projects = buildList {\n for (projectFile in normalizedProjectFiles) {\n val project = loadProject(projectFile)\n project.`package`\n ?: throw CliException(\n ErrorMessages.create(\"noPackageDefinedByProject\", project.projectFileUri)\n )\n runApiTests(project)\n add(project)\n }\n }\n // Require that all local projects are included\n projects.forEach { proj ->\n proj.dependencies.localDependencies().values.forEach { localDep ->\n val projectDir = Path.of(localDep.projectFileUri()).parent\n if (projects.none { it.projectDir == projectDir }) {\n throw CliException(\n ErrorMessages.create(\"missingProjectInPackageCommand\", proj.projectDir, projectDir)\n )\n }\n }\n }\n ProjectPackager(\n projects,\n cliOptions.normalizedWorkingDir,\n outputPath,\n stackFrameTransformer,\n cliOptions.color?.hasColor() ?: false,\n securityManager,\n httpClient,\n skipPublishCheck,\n consoleWriter,\n )\n .createPackages()\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliProjectResolver.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.io.IOException\nimport java.io.Writer\nimport java.nio.file.Path\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.core.PklException\nimport org.pkl.core.SecurityManagers\nimport org.pkl.core.module.ProjectDependenciesManager\nimport org.pkl.core.packages.PackageResolver\nimport org.pkl.core.project.ProjectDependenciesResolver\n\nclass CliProjectResolver(\n baseOptions: CliBaseOptions,\n projectDirs: List,\n private val consoleWriter: Writer = System.out.writer(),\n private val errWriter: Writer = System.err.writer(),\n) : CliProjectCommand(baseOptions, projectDirs) {\n override fun doRun() {\n for (projectFile in normalizedProjectFiles) {\n val project = loadProject(projectFile)\n val packageResolver =\n PackageResolver.getInstance(\n SecurityManagers.standard(\n allowedModules,\n allowedResources,\n SecurityManagers.defaultTrustLevels,\n rootDir,\n ),\n httpClient,\n moduleCacheDir,\n )\n val dependencies = ProjectDependenciesResolver(project, packageResolver, errWriter).resolve()\n val depsFile =\n projectFile.parent.resolve(ProjectDependenciesManager.PKL_PROJECT_DEPS_FILENAME).toFile()\n try {\n depsFile.outputStream().use { dependencies.writeTo(it) }\n consoleWriter.appendLine(depsFile.toString())\n consoleWriter.flush()\n } catch (e: IOException) {\n throw PklException(\"Failed to write to $depsFile: ${e.message}\", e)\n }\n }\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliRepl.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport org.pkl.cli.repl.Repl\nimport org.pkl.commons.cli.CliCommand\nimport org.pkl.core.Loggers\nimport org.pkl.core.SecurityManagers\nimport org.pkl.core.evaluatorSettings.TraceMode\nimport org.pkl.core.module.ModuleKeyFactories\nimport org.pkl.core.module.ModulePathResolver\nimport org.pkl.core.repl.ReplServer\nimport org.pkl.core.resource.ResourceReaders\n\ninternal class CliRepl(private val options: CliEvaluatorOptions) : CliCommand(options.base) {\n override fun doRun() {\n ModulePathResolver(modulePath).use { modulePathResolver ->\n // TODO: send options as command\n val server =\n ReplServer(\n SecurityManagers.standard(\n allowedModules,\n allowedResources,\n SecurityManagers.defaultTrustLevels,\n rootDir,\n ),\n httpClient,\n Loggers.stdErr(),\n listOf(\n ModuleKeyFactories.standardLibrary,\n ModuleKeyFactories.modulePath(modulePathResolver),\n ) +\n ModuleKeyFactories.fromServiceProviders() +\n listOf(\n ModuleKeyFactories.file,\n ModuleKeyFactories.http,\n ModuleKeyFactories.pkg,\n ModuleKeyFactories.projectpackage,\n ModuleKeyFactories.genericUrl,\n ),\n listOf(\n ResourceReaders.environmentVariable(),\n ResourceReaders.externalProperty(),\n ResourceReaders.modulePath(modulePathResolver),\n ResourceReaders.file(),\n ResourceReaders.http(),\n ResourceReaders.https(),\n ResourceReaders.pkg(),\n ResourceReaders.projectpackage(),\n ),\n environmentVariables,\n externalProperties,\n moduleCacheDir,\n project?.dependencies,\n options.outputFormat,\n options.base.normalizedWorkingDir,\n stackFrameTransformer,\n options.base.color?.hasColor() ?: false,\n options.base.traceMode ?: TraceMode.COMPACT,\n )\n Repl(options.base.normalizedWorkingDir, server, options.base.color?.hasColor() ?: false).run()\n }\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliServer.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.CliCommand\nimport org.pkl.commons.cli.CliException\nimport org.pkl.core.messaging.ProtocolException\nimport org.pkl.server.Server\n\nclass CliServer(options: CliBaseOptions) : CliCommand(options) {\n override fun doRun(): Unit =\n try {\n val server = Server.stream(System.`in`, System.out)\n server.use { it.start() }\n } catch (e: ProtocolException) {\n throw CliException(e.message!!)\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/CliTestRunner.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.io.Writer\nimport org.pkl.commons.cli.*\nimport org.pkl.core.Closeables\nimport org.pkl.core.EvaluatorBuilder\nimport org.pkl.core.ModuleSource.uri\nimport org.pkl.core.PklException\nimport org.pkl.core.TestResults\nimport org.pkl.core.stdlib.test.report.JUnitReport\nimport org.pkl.core.stdlib.test.report.SimpleReport\nimport org.pkl.core.util.ErrorMessages\n\nclass CliTestRunner\n@JvmOverloads\nconstructor(\n private val options: CliBaseOptions,\n private val testOptions: CliTestOptions,\n private val consoleWriter: Writer = System.out.writer(),\n private val errWriter: Writer = System.err.writer(),\n) : CliCommand(options) {\n\n override fun doRun() {\n val builder = evaluatorBuilder()\n try {\n evalTest(builder)\n } finally {\n Closeables.closeQuietly(builder.moduleKeyFactories)\n Closeables.closeQuietly(builder.resourceReaders)\n }\n }\n\n private fun evalTest(builder: EvaluatorBuilder) {\n val sources =\n resolvedSourceModules.ifEmpty { project?.tests?.map { it.toUri() } }\n ?:\n // keep in sync with error message thrown by clikt\n throw CliException(\n \"\"\"\n Usage: pkl test [] ...\n \n Error: missing argument \n \"\"\"\n .trimIndent()\n )\n\n val evaluator = builder.build()\n evaluator.use {\n var failed = false\n var isExampleWrittenFailure = true\n val moduleNames = mutableSetOf()\n val reporter = SimpleReport(useColor)\n val allTestResults = mutableListOf()\n\n val junitDir = testOptions.junitDir\n if (junitDir != null) {\n junitDir.toFile().mkdirs()\n }\n\n for ((idx, moduleUri) in sources.withIndex()) {\n try {\n val results = evaluator.evaluateTest(uri(moduleUri), testOptions.overwrite)\n allTestResults.add(results)\n if (!failed) {\n failed = results.failed()\n isExampleWrittenFailure = results.isExampleWrittenFailure.and(isExampleWrittenFailure)\n }\n reporter.report(results, consoleWriter)\n if (sources.size > 1 && idx != sources.size - 1) {\n consoleWriter.append('\\n')\n }\n consoleWriter.flush()\n if (junitDir != null) {\n val moduleName = \"${results.moduleName}.xml\"\n if (moduleName in moduleNames) {\n throw RuntimeException(\n \"\"\"\n Cannot generate JUnit report for $moduleUri.\n A report with the same name was already generated.\n \n To fix, provide a different name for this module by adding a module header.\n \"\"\"\n .trimIndent()\n )\n }\n moduleNames += moduleName\n\n if (!testOptions.junitAggregateReports) {\n JUnitReport().reportToPath(results, junitDir.resolve(moduleName))\n }\n }\n } catch (ex: Exception) {\n errWriter.appendLine(\"Error evaluating module ${moduleUri.path}:\")\n errWriter.write(ex.message ?: \"\")\n if (ex !is PklException) {\n errWriter.write(ex.stackTraceToString())\n }\n if (moduleUri != sources.last()) {\n errWriter.appendLine()\n }\n errWriter.flush()\n failed = true\n }\n }\n if (testOptions.junitAggregateReports && junitDir != null) {\n val fileName = \"${testOptions.junitAggregateSuiteName}.xml\"\n JUnitReport(testOptions.junitAggregateSuiteName)\n .summarizeToPath(allTestResults, junitDir.resolve(fileName))\n }\n consoleWriter.append('\\n')\n reporter.summarize(allTestResults, consoleWriter)\n consoleWriter.flush()\n if (failed) {\n val exitCode = if (isExampleWrittenFailure) 10 else 1\n throw CliTestException(ErrorMessages.create(\"testsFailed\"), exitCode)\n }\n }\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/Main.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n@file:JvmName(\"Main\")\n\npackage org.pkl.cli\n\nimport com.github.ajalt.clikt.core.main\nimport org.pkl.cli.commands.*\nimport org.pkl.commons.cli.cliMain\n\n/** Main method of the Pkl CLI (command-line evaluator and REPL). */\ninternal fun main(args: Array) {\n cliMain { RootCommand().main(args) }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/OutputUtils.kt", "content": "/*\n * Copyright © 2025-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.io.OutputStream\nimport org.pkl.commons.cli.CliException\nimport org.pkl.core.util.IoUtils\n\nfun checkPathSpec(pathSpec: String) {\n val illegal = pathSpec.indexOfFirst { IoUtils.isReservedFilenameChar(it) && it != '/' }\n if (illegal == -1) {\n return\n }\n throw CliException(\"Path spec `$pathSpec` contains illegal character `${pathSpec[illegal]}`.\")\n}\n\nfun OutputStream.writeText(text: String) = write(text.toByteArray())\n\nfun OutputStream.writeLine(text: String) {\n writeText(text)\n writeText(\"\\n\")\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/commands/AnalyzeCommand.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.commands\n\nimport com.github.ajalt.clikt.core.Context\nimport com.github.ajalt.clikt.core.subcommands\nimport com.github.ajalt.clikt.parameters.options.option\nimport com.github.ajalt.clikt.parameters.types.path\nimport java.nio.file.Path\nimport org.pkl.cli.CliImportAnalyzer\nimport org.pkl.cli.CliImportAnalyzerOptions\nimport org.pkl.commons.cli.commands.ModulesCommand\nimport org.pkl.commons.cli.commands.NoOpCommand\nimport org.pkl.commons.cli.commands.single\n\nclass AnalyzeCommand : NoOpCommand(name = \"analyze\") {\n override fun help(context: Context) = \"Commands related to static analysis\"\n\n override fun helpEpilog(context: Context) = \"For more information, visit $helpLink\"\n\n init {\n subcommands(AnalyzeImportsCommand())\n }\n}\n\nclass AnalyzeImportsCommand : ModulesCommand(name = \"imports\", helpLink = helpLink) {\n override val helpString = \"Prints the graph of modules imported by the input module(s).\"\n\n private val outputPath: Path? by\n option(\n names = arrayOf(\"-o\", \"--output-path\"),\n metavar = \"path\",\n help = \"File path where the output file is placed.\",\n )\n .path()\n .single()\n\n override fun run() {\n val options =\n CliImportAnalyzerOptions(\n base = baseOptions.baseOptions(modules, projectOptions),\n outputFormat = baseOptions.format,\n outputPath = outputPath,\n )\n CliImportAnalyzer(options).run()\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/commands/DownloadPackageCommand.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.commands\n\nimport com.github.ajalt.clikt.parameters.arguments.argument\nimport com.github.ajalt.clikt.parameters.arguments.convert\nimport com.github.ajalt.clikt.parameters.arguments.multiple\nimport com.github.ajalt.clikt.parameters.groups.provideDelegate\nimport com.github.ajalt.clikt.parameters.options.flag\nimport com.github.ajalt.clikt.parameters.options.option\nimport org.pkl.cli.CliPackageDownloader\nimport org.pkl.commons.cli.commands.BaseCommand\nimport org.pkl.commons.cli.commands.ProjectOptions\nimport org.pkl.commons.cli.commands.single\nimport org.pkl.core.packages.PackageUri\n\nclass DownloadPackageCommand : BaseCommand(name = \"download-package\", helpLink = helpLink) {\n override val helpString =\n \"\"\"\n Download package(s)\n \n This command downloads the specified packages to the cache directory.\n If the package already exists in the cache directory, this command is a no-op.\n \n Examples:\n \n ```\n # Download two packages\n $ pkl download-package package://example.com/package1@1.0.0 package://example.com/package2@1.0.0 \n ```\n \"\"\"\n .trimIndent()\n\n private val projectOptions by ProjectOptions()\n\n private val packageUris: List by\n argument(\"package\", \"The package URIs to download\")\n .convert { PackageUri(it) }\n .multiple(required = true)\n\n private val noTransitive: Boolean by\n option(\n names = arrayOf(\"--no-transitive\"),\n help = \"Skip downloading transitive dependencies of a package\",\n )\n .single()\n .flag()\n\n override fun run() {\n CliPackageDownloader(\n baseOptions.baseOptions(emptyList(), projectOptions),\n packageUris,\n noTransitive,\n )\n .run()\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/commands/EvalCommand.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.commands\n\nimport com.github.ajalt.clikt.completion.CompletionCandidates\nimport com.github.ajalt.clikt.parameters.options.default\nimport com.github.ajalt.clikt.parameters.options.flag\nimport com.github.ajalt.clikt.parameters.options.option\nimport com.github.ajalt.clikt.parameters.options.validate\nimport org.pkl.cli.CliEvaluator\nimport org.pkl.cli.CliEvaluatorOptions\nimport org.pkl.commons.cli.commands.ModulesCommand\nimport org.pkl.commons.cli.commands.single\n\nclass EvalCommand : ModulesCommand(name = \"eval\", helpLink = helpLink) {\n\n override val helpString = \"Render pkl module(s)\"\n\n private val outputPath: String? by\n option(\n names = arrayOf(\"-o\", \"--output-path\"),\n metavar = \"path\",\n help = \"File path where the output file is placed.\",\n completionCandidates = CompletionCandidates.Path,\n )\n .single()\n\n private val moduleOutputSeparator: String by\n option(\n names = arrayOf(\"--module-output-separator\"),\n metavar = \"string\",\n help =\n \"Separator to use when multiple module outputs are written to the same file. (default: ---)\",\n )\n .single()\n .default(\"---\")\n\n private val expression: String? by\n option(\n names = arrayOf(\"-x\", \"--expression\"),\n metavar = \"expression\",\n help = \"Expression to be evaluated within the module.\",\n )\n .single()\n\n private val multipleFileOutputPath: String? by\n option(\n names = arrayOf(\"-m\", \"--multiple-file-output-path\"),\n metavar = \"path\",\n help = \"Directory where a module's multiple file output is placed.\",\n completionCandidates = CompletionCandidates.Path,\n )\n .single()\n .validate {\n if (outputPath != null || expression != null) {\n fail(\"Option is mutually exclusive with -o, --output-path and -x, --expression.\")\n }\n }\n\n // hidden option used by the native tests\n private val testMode: Boolean by\n option(names = arrayOf(\"--test-mode\"), help = \"Internal test mode\", hidden = true).flag()\n\n private val powerAssertionsEnabled: Boolean by\n option(\n names = arrayOf(\"--power-assertions\"),\n help = \"Enable power assertions for detailed assertion failure messages.\",\n )\n .flag(\"--no-power-assertions\", default = true, defaultForHelp = \"enabled\")\n\n override fun run() {\n val options =\n CliEvaluatorOptions(\n base =\n baseOptions.baseOptions(\n modules,\n projectOptions,\n testMode = testMode,\n powerAssertionsEnabled = powerAssertionsEnabled,\n ),\n outputPath = outputPath,\n outputFormat = baseOptions.format,\n moduleOutputSeparator = moduleOutputSeparator,\n multipleFileOutputPath = multipleFileOutputPath,\n expression = expression ?: CliEvaluatorOptions.defaults.expression,\n )\n CliEvaluator(options).run()\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/commands/FormatterCommand.kt", "content": "/*\n * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.commands\n\nimport com.github.ajalt.clikt.core.CliktCommand\nimport com.github.ajalt.clikt.core.Context\nimport com.github.ajalt.clikt.parameters.arguments.argument\nimport com.github.ajalt.clikt.parameters.arguments.multiple\nimport com.github.ajalt.clikt.parameters.options.default\nimport com.github.ajalt.clikt.parameters.options.flag\nimport com.github.ajalt.clikt.parameters.options.option\nimport com.github.ajalt.clikt.parameters.types.enum\nimport com.github.ajalt.clikt.parameters.types.path\nimport java.nio.file.Path\nimport org.pkl.cli.CliFormatterCommand\nimport org.pkl.formatter.GrammarVersion\n\nclass FormatterCommand : CliktCommand(name = \"format\") {\n override fun help(context: Context) =\n \"\"\"\n Format or check formatting of Pkl files.\n \n Examples:\n \n ```\n # Overwrite all Pkl files inside `my/folder/`, recursively.\n $ pkl format -w my/folder/\n \n # Check formatting of all files, printing filenames with formatting violations to stdout.\n # Exit with exit code `11` if formatting violations were found.\n $ pkl format --diff-name-only my/folder/\n \n # Format Pkl code from stdin.\n $ echo \"foo = 1\" | pkl format -\n ```\n \"\"\"\n .trimIndent()\n\n override fun helpEpilog(context: Context) = \"For more information, visit $helpLink\"\n\n val paths: List by\n argument(name = \"paths\", help = \"Files or directory to check. Use `-` to read from stdin.\")\n .path(mustExist = false, canBeDir = true)\n .multiple()\n\n val grammarVersion: GrammarVersion by\n option(\n names = arrayOf(\"--grammar-version\"),\n help =\n \"\"\"\n The grammar compatibility version to use.$NEWLINE\n ${GrammarVersion.entries.joinToString(\"$NEWLINE\", prefix = \" \") {\n val default = if (it == GrammarVersion.latest()) \" `(default)`\" else \"\"\n \"`${it.version}`: ${it.versionSpan}$default\"\n }}\n \"\"\"\n .trimIndent(),\n )\n .enum { \"${it.version}\" }\n .default(GrammarVersion.latest())\n\n val overwrite: Boolean by\n option(\n names = arrayOf(\"-w\", \"--write\"),\n help = \"Format files in place, overwriting them. Implies `---diff-name-only`.\",\n )\n .flag(default = false)\n\n val diffNameOnly: Boolean by\n option(\n names = arrayOf(\"--diff-name-only\"),\n help = \"Write the path of files with formatting violations to stdout.\",\n )\n .flag(default = false)\n\n val silent: Boolean by\n option(\n names = arrayOf(\"-s\", \"--silent\"),\n help = \"Don't write to stdout or stderr. Mutually exclusive with `--diff-name-only`.\",\n )\n .flag(default = false)\n\n override fun run() {\n CliFormatterCommand(paths, grammarVersion, overwrite, diffNameOnly, silent).run()\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/commands/ProjectCommand.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.commands\n\nimport com.github.ajalt.clikt.completion.CompletionCandidates\nimport com.github.ajalt.clikt.core.Context\nimport com.github.ajalt.clikt.core.subcommands\nimport com.github.ajalt.clikt.parameters.arguments.argument\nimport com.github.ajalt.clikt.parameters.arguments.multiple\nimport com.github.ajalt.clikt.parameters.groups.provideDelegate\nimport com.github.ajalt.clikt.parameters.options.default\nimport com.github.ajalt.clikt.parameters.options.flag\nimport com.github.ajalt.clikt.parameters.options.option\nimport com.github.ajalt.clikt.parameters.types.path\nimport java.nio.file.Path\nimport org.pkl.cli.CliProjectPackager\nimport org.pkl.cli.CliProjectResolver\nimport org.pkl.commons.cli.commands.BaseCommand\nimport org.pkl.commons.cli.commands.NoOpCommand\nimport org.pkl.commons.cli.commands.TestOptions\nimport org.pkl.commons.cli.commands.single\n\nclass ProjectCommand : NoOpCommand(name = \"project\") {\n override fun help(context: Context) = \"Run commands related to projects\"\n\n override fun helpEpilog(context: Context) = \"For more information, visit $helpLink\"\n\n init {\n subcommands(ResolveCommand(), PackageCommand())\n }\n}\n\nclass ResolveCommand : BaseCommand(name = \"resolve\", helpLink = helpLink) {\n override val helpString =\n \"\"\"\n Resolve dependencies for project(s)\n\n This command takes the `dependencies` of `PklProject`s, and writes the\n resolved versions to `PklProject.deps.json` files.\n\n Examples:\n\n ```\n # Search the current working directory for a project, and resolve its dependencies.\n $ pkl project resolve\n\n # Resolve dependencies for all projects within the `packages/` directory.\n $ pkl project resolve packages/*/\n ```\n \"\"\"\n\n private val projectDirs: List by\n argument(\"dir\", \"The project directories to resolve dependencies for\").path().multiple()\n\n override fun run() {\n CliProjectResolver(baseOptions.baseOptions(emptyList()), projectDirs).run()\n }\n}\n\nclass PackageCommand : BaseCommand(name = \"package\", helpLink = helpLink) {\n override val helpString =\n \"\"\"\n Verify package(s), and prepare package artifacts to be published.\n\n This command runs a project's api tests, as defined by `apiTests` in `PklProject`.\n Additionally, it verifies that all imports resolve to paths that are local to the project.\n\n Finally, this command writes the following artifacts into the output directory specified by the output path.\n\n - `name@version` - dependency metadata$NEWLINE\n - `name@version.sha256` - dependency metadata's SHA-256 checksum$NEWLINE\n - `name@version.zip` - package archive$NEWLINE\n - `name@version.zip.sha256` - package archive's SHA-256 checksum\n\n The output path option accepts the following placeholders:\n\n - %{name}: The display name of the package$NEWLINE\n - %{version}: The version of the package\n\n If a project has local project dependencies, the depended upon project directories must also\n be included as arguments to this command.\n\n Examples:\n\n ```\n # Search the current working directory for a project, and package it.\n $ pkl project package\n\n # Package all projects within the `packages/` directory.\n $ pkl project package packages/*/\n ```\n \"\"\"\n .trimIndent()\n\n private val testOptions by TestOptions()\n\n private val projectDirs: List by\n argument(\"dir\", \"The project directories to package\").path().multiple()\n\n private val outputPath: String by\n option(\n names = arrayOf(\"--output-path\"),\n help = \"The directory to write artifacts to\",\n metavar = \"path\",\n completionCandidates = CompletionCandidates.Path,\n )\n .single()\n .default(\".out/%{name}@%{version}\")\n\n private val skipPublishCheck: Boolean by\n option(\n names = arrayOf(\"--skip-publish-check\"),\n help = \"Skip checking if a package has already been published with different contents\",\n )\n .single()\n .flag()\n\n override fun run() {\n CliProjectPackager(\n baseOptions.baseOptions(emptyList()),\n projectDirs,\n testOptions.cliTestOptions,\n outputPath,\n skipPublishCheck,\n )\n .run()\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/commands/ReplCommand.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.commands\n\nimport com.github.ajalt.clikt.parameters.groups.provideDelegate\nimport org.pkl.cli.CliEvaluatorOptions\nimport org.pkl.cli.CliRepl\nimport org.pkl.commons.cli.commands.BaseCommand\nimport org.pkl.commons.cli.commands.ProjectOptions\n\nclass ReplCommand : BaseCommand(name = \"repl\", helpLink = helpLink) {\n override val helpString = \"Start a REPL session\"\n\n private val projectOptions by ProjectOptions()\n\n override fun run() {\n val options = CliEvaluatorOptions(base = baseOptions.baseOptions(emptyList(), projectOptions))\n CliRepl(options).run()\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/commands/RootCommand.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.commands\n\nimport com.github.ajalt.clikt.completion.CompletionCommand\nimport com.github.ajalt.clikt.core.Context\nimport com.github.ajalt.clikt.core.context\nimport com.github.ajalt.clikt.core.subcommands\nimport org.pkl.commons.cli.commands.NoOpCommand\nimport org.pkl.commons.cli.commands.installCommonOptions\nimport org.pkl.core.Release\n\ninternal val helpLink = \"${Release.current().documentation.homepage}pkl-cli/index.html#usage\"\n\nclass RootCommand : NoOpCommand(name = \"pkl\") {\n override val printHelpOnEmptyArgs = true\n\n override fun helpEpilog(context: Context) = \"For more information, visit $helpLink\"\n\n init {\n context {\n readArgumentFile = null\n suggestTypoCorrection = { given, possible ->\n if (!given.startsWith(\"-\")) {\n registeredSubcommands().map { it.commandName }\n } else possible\n }\n }\n\n installCommonOptions()\n\n subcommands(\n EvalCommand(),\n ReplCommand(),\n ServerCommand(),\n TestCommand(),\n ProjectCommand(),\n DownloadPackageCommand(),\n AnalyzeCommand(),\n FormatterCommand(),\n RunCommand(),\n CompletionCommand(\n name = \"shell-completion\",\n help = \"Generate a completion script for the given shell\",\n epilog = \"For more information, visit $helpLink\",\n ),\n )\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/commands/RunCommand.kt", "content": "/*\n * Copyright © 2025-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.commands\n\nimport com.github.ajalt.clikt.completion.CompletionCandidates\nimport com.github.ajalt.clikt.core.MissingArgument\nimport com.github.ajalt.clikt.core.PrintHelpMessage\nimport com.github.ajalt.clikt.core.context\nimport com.github.ajalt.clikt.parameters.arguments.argument\nimport com.github.ajalt.clikt.parameters.arguments.convert\nimport com.github.ajalt.clikt.parameters.arguments.multiple\nimport com.github.ajalt.clikt.parameters.arguments.optional\nimport com.github.ajalt.clikt.parameters.groups.provideDelegate\nimport com.github.ajalt.clikt.parameters.options.flag\nimport com.github.ajalt.clikt.parameters.options.option\nimport java.net.URI\nimport org.pkl.cli.CliCommandRunner\nimport org.pkl.commons.cli.commands.BaseCommand\nimport org.pkl.commons.cli.commands.BaseOptions\nimport org.pkl.commons.cli.commands.ProjectOptions\n\nclass RunCommand : BaseCommand(name = \"run\", helpLink = helpLink) {\n override val helpString = \"Run a Pkl pkl:Command CLI tool\"\n override val treatUnknownOptionsAsArgs = true\n\n init {\n context {\n // override clikt's built-in help behavior\n // the built-in --help is eager so any --help/-h would force printing of pkl run's help\n // which is not desired when a command module (or any of its subcommands) are present\n // since that would mean command-defined help is gated behind a non-obvious `-- --help`\n helpOptionNames = emptySet()\n }\n }\n\n private val showHelp by option(\"-h\", \"--help\", help = \"Show this message and exit\").flag()\n\n val module: URI? by\n argument(\n name = \"module\",\n help = \"Root pkl:Command module to invoke.\",\n completionCandidates = CompletionCandidates.Path,\n )\n .convert { BaseOptions.parseModuleName(it) }\n .optional()\n\n val args: List by argument(name = \"args\").multiple()\n\n private val projectOptions by ProjectOptions()\n\n override fun run() {\n // if no module is specified but --help is show help, otherwise error becuase module is missing\n if (module == null)\n if (showHelp) throw PrintHelpMessage(currentContext)\n else throw MissingArgument(registeredArguments().find { it.name == \"module\" }!!)\n\n val reservedFlagNames = mutableSetOf(\"help\")\n val reservedFlagShortNames = mutableSetOf(\"h\")\n registeredOptions().forEach { opt ->\n (opt.names + opt.secondaryNames).forEach {\n if (it.startsWith(\"--\")) reservedFlagNames.add(it.trimStart('-'))\n else reservedFlagShortNames.add(it.trimStart('-'))\n }\n }\n CliCommandRunner(\n baseOptions.baseOptions(listOf(module!!), projectOptions),\n reservedFlagNames,\n reservedFlagShortNames,\n if (showHelp) args + listOf(\"--help\") else args,\n )\n .run()\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/commands/ServerCommand.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.commands\n\nimport com.github.ajalt.clikt.core.CliktCommand\nimport com.github.ajalt.clikt.core.Context\nimport org.pkl.cli.CliServer\nimport org.pkl.commons.cli.CliBaseOptions\n\nclass ServerCommand : CliktCommand(name = \"server\") {\n override fun help(context: Context) =\n \"Run as a server that communicates over standard input/output\"\n\n override fun helpEpilog(context: Context) = \"For more information, visit $helpLink\"\n\n override fun run() {\n CliServer(CliBaseOptions()).run()\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/commands/TestCommand.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.commands\n\nimport com.github.ajalt.clikt.completion.CompletionCandidates\nimport com.github.ajalt.clikt.parameters.arguments.argument\nimport com.github.ajalt.clikt.parameters.arguments.convert\nimport com.github.ajalt.clikt.parameters.arguments.multiple\nimport com.github.ajalt.clikt.parameters.groups.provideDelegate\nimport com.github.ajalt.clikt.parameters.options.flag\nimport com.github.ajalt.clikt.parameters.options.option\nimport java.net.URI\nimport org.pkl.cli.CliTestRunner\nimport org.pkl.commons.cli.commands.BaseCommand\nimport org.pkl.commons.cli.commands.BaseOptions\nimport org.pkl.commons.cli.commands.ProjectOptions\nimport org.pkl.commons.cli.commands.TestOptions\n\nclass TestCommand : BaseCommand(name = \"test\", helpLink = helpLink) {\n override val helpString = \"Run tests within the given module(s)\"\n\n val modules: List by\n argument(\n name = \"modules\",\n help = \"Module paths or URIs to evaluate.\",\n completionCandidates = CompletionCandidates.Path,\n )\n .convert { BaseOptions.parseModuleName(it) }\n .multiple()\n\n private val projectOptions by ProjectOptions()\n\n private val testOptions by TestOptions()\n\n private val powerAssertionsEnabled: Boolean by\n option(\n names = arrayOf(\"--power-assertions\"),\n help = \"Enable power assertions for detailed assertion failure messages.\",\n )\n .flag(\"--no-power-assertions\", default = true, defaultForHelp = \"enabled\")\n\n override fun run() {\n CliTestRunner(\n options =\n baseOptions.baseOptions(\n modules,\n projectOptions,\n powerAssertionsEnabled = powerAssertionsEnabled,\n ),\n testOptions = testOptions.cliTestOptions,\n )\n .run()\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/commands/Utils.kt", "content": "/*\n * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.commands\n\ninternal const val NEWLINE = '\\u0085'\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/repl/Repl.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.repl\n\nimport java.io.IOException\nimport java.net.URI\nimport java.nio.file.Path\nimport java.util.regex.Pattern\nimport kotlin.io.path.deleteIfExists\nimport org.fusesource.jansi.Ansi\nimport org.jline.reader.EndOfFileException\nimport org.jline.reader.Highlighter\nimport org.jline.reader.LineReader\nimport org.jline.reader.LineReader.Option\nimport org.jline.reader.LineReaderBuilder\nimport org.jline.reader.UserInterruptException\nimport org.jline.reader.impl.completer.AggregateCompleter\nimport org.jline.reader.impl.history.DefaultHistory\nimport org.jline.terminal.TerminalBuilder\nimport org.jline.utils.AttributedString\nimport org.jline.utils.InfoCmp\nimport org.pkl.core.repl.ReplRequest\nimport org.pkl.core.repl.ReplResponse\nimport org.pkl.core.repl.ReplServer\nimport org.pkl.core.util.AnsiStringBuilder\nimport org.pkl.core.util.AnsiStringBuilder.AnsiCode\nimport org.pkl.core.util.IoUtils\nimport org.pkl.core.util.SyntaxHighlighter\n\nclass PklHighlighter : Highlighter {\n override fun highlight(reader: LineReader, buffer: String): AttributedString {\n val ansi = AnsiStringBuilder(true).apply { SyntaxHighlighter.writeTo(this, buffer) }.toString()\n return AttributedString.fromAnsi(ansi)\n }\n\n override fun setErrorPattern(pattern: Pattern) {}\n\n override fun setErrorIndex(idx: Int) {}\n}\n\ninternal class Repl(workingDir: Path, private val server: ReplServer, private val color: Boolean) {\n private val terminal = TerminalBuilder.builder().apply { jansi(true) }.build()\n private val history = DefaultHistory()\n private val reader =\n LineReaderBuilder.builder()\n .apply {\n history(history)\n terminal(terminal)\n if (color) {\n highlighter(PklHighlighter())\n }\n completer(AggregateCompleter(CommandCompleter, FileCompleter(workingDir)))\n option(Option.DISABLE_EVENT_EXPANSION, true)\n variable(LineReader.HISTORY_FILE, (IoUtils.getPklHomeDir().resolve(\"repl-history\")))\n }\n .build()\n\n private var continuation = false\n private var quit = false\n private var maybeQuit = false\n private var nextRequestId = 0\n\n private fun String.faint(): String {\n val sb = AnsiStringBuilder(color)\n sb.append(AnsiCode.FAINT, this)\n return sb.toString()\n }\n\n fun run() {\n // JLine 2 history file is incompatible with JLine 3\n IoUtils.getPklHomeDir().resolve(\"repl-history.bin\").deleteIfExists()\n\n println(ReplMessages.welcome)\n println()\n\n var inputBuffer = \"\"\n\n try {\n while (!quit) {\n val line =\n try {\n if (continuation) {\n nextRequestId -= 1\n reader.readLine(\" \".repeat(\"pkl$nextRequestId> \".length).faint())\n } else {\n reader.readLine(\"pkl$nextRequestId> \".faint())\n }\n } catch (_: UserInterruptException) {\n if (!continuation && reader.buffer.length() == 0) {\n if (maybeQuit) quit()\n else {\n maybeQuit = true\n println(\"(To exit, press ^C again or ^D or type :quit)\")\n }\n } else {\n maybeQuit = false\n }\n inputBuffer = \"\"\n continuation = false\n continue\n } catch (_: EndOfFileException) {\n \":quit\"\n }\n\n maybeQuit = false\n val input = line.trim()\n if (input.isEmpty()) continue\n\n if (continuation) {\n inputBuffer = (inputBuffer + \"\\n\" + input).trim()\n continuation = false\n } else {\n inputBuffer = input\n }\n\n if (inputBuffer.startsWith(\":\")) {\n executeCommand(inputBuffer)\n } else {\n evaluate(inputBuffer)\n }\n }\n } finally {\n try {\n history.save()\n } catch (_: IOException) {}\n try {\n terminal.close()\n } catch (_: IOException) {}\n }\n }\n\n private fun executeCommand(inputBuffer: String) {\n val candidates = getMatchingCommands(inputBuffer)\n when {\n candidates.isEmpty() -> {\n println(\"Unknown command: `${inputBuffer.drop(1)}`\")\n }\n\n candidates.size > 1 -> {\n print(\"Which of the following did you mean? \")\n println(candidates.joinToString(separator = \" \") { \"`:${it.type}`\" })\n }\n\n else -> {\n doExecuteCommand(candidates.single())\n }\n }\n }\n\n private fun doExecuteCommand(command: ParsedCommand) {\n when (command.type) {\n Command.Clear -> clear()\n Command.Examples -> examples()\n Command.Force -> force(command)\n Command.Help -> help()\n Command.Load -> load(command)\n Command.Quit -> quit()\n Command.Reset -> reset()\n }\n }\n\n private fun clear() {\n terminal.puts(InfoCmp.Capability.clear_screen)\n terminal.flush()\n }\n\n private fun examples() {\n println(ReplMessages.examples)\n }\n\n private fun help() {\n println(ReplMessages.help)\n }\n\n private fun quit() {\n quit = true\n }\n\n private fun reset() {\n server.handleRequest(ReplRequest.Reset(nextRequestId()))\n clear()\n nextRequestId = 0\n }\n\n private fun evaluate(inputBuffer: String) {\n handleEvalRequest(ReplRequest.Eval(nextRequestId(), inputBuffer, false, false))\n }\n\n private fun loadModule(uri: URI) {\n handleEvalRequest(ReplRequest.Load(nextRequestId(), uri))\n }\n\n private fun force(command: ParsedCommand) {\n handleEvalRequest(ReplRequest.Eval(nextRequestId(), command.arg, false, true))\n }\n\n private fun load(command: ParsedCommand) {\n loadModule(IoUtils.toUri(command.arg))\n }\n\n private fun handleEvalRequest(request: ReplRequest) {\n val responses = server.handleRequest(request)\n\n for (response in responses) {\n when (response) {\n is ReplResponse.EvalSuccess -> {\n println(response.result)\n }\n\n is ReplResponse.EvalError -> {\n println(response.message)\n }\n\n is ReplResponse.InternalError -> {\n throw response.cause\n }\n\n is ReplResponse.IncompleteInput -> {\n assert(responses.size == 1)\n continuation = true\n }\n\n else -> throw IllegalStateException(\"Unexpected response: $response\")\n }\n }\n }\n\n private fun nextRequestId(): String = \"pkl$nextRequestId\".apply { nextRequestId += 1 }\n\n private fun print(msg: String) {\n terminal.writer().print(highlight(msg))\n }\n\n private fun println(msg: String = \"\") {\n terminal.writer().println(highlight(msg))\n }\n\n private fun highlight(str: String): String {\n val ansi = Ansi.ansi()\n var normal = true\n for (part in str.split(\"`\", \"```\")) {\n ansi.a(part)\n normal = !normal\n if (!normal) ansi.bold() else ansi.boldOff()\n }\n ansi.reset()\n return ansi.toString()\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/repl/ReplCommands.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.repl\n\nprivate val cmdRegex = Regex(\":(\\\\p{Alpha}*)(\\\\p{Space}*)(.*)\", RegexOption.DOT_MATCHES_ALL)\n\ninternal fun getMatchingCommands(input: String): List {\n val match = cmdRegex.matchEntire(input) ?: return listOf()\n val (cmd, ws, arg) = match.destructured\n return Command.entries\n .filter { it.toString().lowercase().startsWith(cmd) }\n .map { ParsedCommand(it, cmd, ws, arg) }\n}\n\ninternal data class ParsedCommand(\n val type: Command,\n val cmd: String,\n val ws: String,\n val arg: String,\n)\n\ninternal enum class Command {\n Clear,\n Examples,\n Force,\n Help,\n Load,\n Quit,\n Reset;\n\n override fun toString() = name.lowercase()\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/repl/ReplCompleters.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.repl\n\nimport java.io.IOException\nimport java.nio.file.Files\nimport java.nio.file.Path\nimport org.jline.reader.Candidate\nimport org.jline.reader.Completer\nimport org.jline.reader.LineReader\nimport org.jline.reader.ParsedLine\nimport org.jline.terminal.Terminal\nimport org.jline.utils.AttributedStringBuilder\nimport org.jline.utils.OSUtils\nimport org.jline.utils.StyleResolver\n\n/**\n * Originally copied from:\n * https://github.com/jline/jline3/blob/jline-parent-3.21.0/builtins/src/main/java/org/jline/builtins/Completers.java\n *\n * Reasons for copying this class instead of adding jline-builtins dependency:\n * - Adding the dependency breaks native-image build (at least when using build-time initialization,\n * might work with some config).\n * - Completers.FileNameCompleter is the only class we currently use.\n */\ninternal abstract class JLineFileNameCompleter : Completer {\n override fun complete(\n reader: LineReader,\n commandLine: ParsedLine,\n candidates: MutableList,\n ) {\n val buffer = commandLine.word().substring(0, commandLine.wordCursor())\n val current: Path\n val curBuf: String\n val sep = getSeparator(reader.isSet(LineReader.Option.USE_FORWARD_SLASH))\n val lastSep = buffer.lastIndexOf(sep)\n try {\n if (lastSep >= 0) {\n curBuf = buffer.substring(0, lastSep + 1)\n current =\n if (curBuf.startsWith(\"~\")) {\n if (curBuf.startsWith(\"~$sep\")) {\n userHome.resolve(curBuf.substring(2))\n } else {\n userHome.parent.resolve(curBuf.substring(1))\n }\n } else {\n userDir.resolve(curBuf)\n }\n } else {\n curBuf = \"\"\n current = userDir\n }\n try {\n Files.newDirectoryStream(current) { accept(it) }\n .use { directory ->\n directory.forEach { path ->\n val value = curBuf + path.fileName.toString()\n if (Files.isDirectory(path)) {\n candidates.add(\n Candidate(\n value + if (reader.isSet(LineReader.Option.AUTO_PARAM_SLASH)) sep else \"\",\n getDisplay(reader.terminal, path, resolver, sep),\n null,\n null,\n if (reader.isSet(LineReader.Option.AUTO_REMOVE_SLASH)) sep else null,\n null,\n false,\n )\n )\n } else {\n candidates.add(\n Candidate(\n value,\n getDisplay(reader.terminal, path, resolver, sep),\n null,\n null,\n null,\n null,\n true,\n )\n )\n }\n }\n }\n } catch (ignored: IOException) {}\n } catch (ignored: Exception) {}\n }\n\n protected open fun accept(path: Path): Boolean {\n return try {\n !Files.isHidden(path)\n } catch (e: IOException) {\n false\n }\n }\n\n protected open val userDir: Path\n get() = Path.of(System.getProperty(\"user.dir\"))\n\n private val userHome: Path\n get() = Path.of(System.getProperty(\"user.home\"))\n\n private fun getSeparator(useForwardSlash: Boolean): String {\n return if (useForwardSlash) \"/\" else userDir.fileSystem.separator\n }\n\n private fun getDisplay(\n terminal: Terminal,\n path: Path,\n resolver: StyleResolver,\n separator: String,\n ): String {\n val builder = AttributedStringBuilder()\n val name = path.fileName.toString()\n val index = name.lastIndexOf(\".\")\n val type = if (index != -1) \".*\" + name.substring(index) else null\n if (Files.isSymbolicLink(path)) {\n builder.styled(resolver.resolve(\".ln\"), name).append(\"@\")\n } else if (Files.isDirectory(path)) {\n builder.styled(resolver.resolve(\".di\"), name).append(separator)\n } else if (Files.isExecutable(path) && !OSUtils.IS_WINDOWS) {\n builder.styled(resolver.resolve(\".ex\"), name).append(\"*\")\n } else if (type != null && resolver.resolve(type).style != 0L) {\n builder.styled(resolver.resolve(type), name)\n } else if (Files.isRegularFile(path)) {\n builder.styled(resolver.resolve(\".fi\"), name)\n } else {\n builder.append(name)\n }\n return builder.toAnsi(terminal)\n }\n\n companion object {\n private val resolver = StyleResolver { name ->\n when (name) {\n // imitate org.jline.builtins.Styles.DEFAULT_LS_COLORS\n \"di\" -> \"1;91\"\n \"ex\" -> \"1;92\"\n \"ln\" -> \"1;96\"\n \"fi\" -> null\n else -> null\n }\n }\n }\n}\n\ninternal class FileCompleter(override val userDir: Path) : JLineFileNameCompleter() {\n override fun complete(\n reader: LineReader,\n commandLine: ParsedLine,\n candidates: MutableList,\n ) {\n val loadCmd =\n getMatchingCommands(commandLine.line()).find { it.type == Command.Load && it.ws.isNotEmpty() }\n if (loadCmd != null) {\n super.complete(reader, commandLine, candidates)\n }\n }\n}\n\ninternal object CommandCompleter : Completer {\n private val commandCandidates: List =\n Command.entries.map { Candidate(\":\" + it.toString().lowercase()) }\n\n override fun complete(reader: LineReader, line: ParsedLine, candidates: MutableList) {\n if (line.wordIndex() == 0) candidates.addAll(commandCandidates)\n }\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/repl/ReplMessages.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.repl\n\nimport org.pkl.core.Release\n\ninternal object ReplMessages {\n val welcome =\n \"\"\"\n Welcome to Pkl ${Release.current().version()}.\n Type an expression to have it evaluated.\n Type `:help` or `:examples` for more information.\n \"\"\"\n .trimIndent()\n\n val help =\n \"\"\"\n `` Evaluate and print the result. `1 + 3`\n ` = ` Evaluate and assign the result to property . `msg = \"howdy\"`\n `:clear` Clear the screen.\n `:examples` Show code examples (use copy and paste to run them).\n `:force ` Force eager evaluation of a value.\n `:help` Show this help.\n `:load ` Load from local file system. `:load path/to/config.pkl`\n `:quit` Quit this program.\n `:reset` Reset the environment to its initial state.\n\n Tips:\n * Commands can be abbreviated. `:h`\n * Commands can be completed. `:`\n * File paths can be completed. `:load `\n * Expressions can be completed. `\"hello\".re`\n * Multiple declarations and expressions can be evaluated at once. `a = 1; b = a + 2`\n * Incomplete input will be continued on the next line.\n * Multi-line programs can be copy-pasted into the REPL.\n\n \"\"\"\n .trimIndent()\n\n val examples: String =\n \"\"\"\n Expressions:\n `2 + 3 * 4`\n\n Strings:\n `\"Hello, \" + \"World!\"`\n\n Properties:\n `timeout = 5.min; timeout`\n\n Objects:\n ```pigeon {\n name = \"Pigeon\"\n fullName = \"\\(name) Bird\"\n age = 42\n address {\n street = \"Landers St.\"\n }\n }\n pigeon.fullName\n \n hobbies {\n \"Swimming\"\n \"Dancing\"\n \"Surfing\"\n }\n hobbies[1]\n \n prices {\n [\"Apple\"] = 1.5\n [\"Orange\"] = 5\n [\"Banana\"] = 2\n }\n prices[\"Banana\"]```\n \n Inheritance:\n ```parrot = (pigeon) {\n name = \"Parrot\"\n age = 41\n }\n :force parrot```\n\n For more examples, see the Language Reference${if (isMacOs()) \" (Command+Double-click the link below)\" else \"\"}:\n\n ${Release.current().documentation().homepage()}language-reference/\n\n \"\"\"\n .trimIndent()\n\n private fun isMacOs() = System.getProperty(\"os.name\").equals(\"Mac OS X\", ignoreCase = true)\n}\n" }, { "path": "pkl-cli/src/main/kotlin/org/pkl/cli/repl/package-info.java", "content": "/**\n * This package contains source code from:\n *\n *

https://github.com/jline/jline3\n *\n *

Original license:\n *\n *

Copyright (c) 2002-2018, the original author or authors. All rights reserved.\n *\n *

https://opensource.org/licenses/BSD-3-Clause\n *\n *

Redistribution and use in source and binary forms, with or without modification, are permitted\n * provided that the following conditions are met:\n *\n *

Redistributions of source code must retain the above copyright notice, this list of conditions\n * and the following disclaimer.\n *\n *

Redistributions in binary form must reproduce the above copyright notice, this list of\n * conditions and the following disclaimer in the documentation and/or other materials provided with\n * the distribution.\n *\n *

Neither the name of JLine nor the names of its contributors may be used to endorse or promote\n * products derived from this software without specific prior written permission.\n *\n *

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR\n * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND\n * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR\n * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\n * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\n * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,\n * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY\n * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n */\npackage org.pkl.cli.repl;\n" }, { "path": "pkl-cli/src/test/files/projects/project1/PklProject", "content": "amends \"pkl:Project\"\n\ndependencies {\n [\"birds\"] {\n uri = \"package://localhost:0/birds@0.5.0\"\n }\n}\n" }, { "path": "pkl-cli/src/test/kotlin/org/pkl/cli/CliCommandRunnerTest.kt", "content": "/*\n * Copyright © 2025-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport com.github.ajalt.clikt.core.CliktError\nimport com.github.ajalt.clikt.core.MissingOption\nimport com.github.ajalt.clikt.core.PrintCompletionMessage\nimport com.github.tomakehurst.wiremock.junit5.WireMockTest\nimport java.io.ByteArrayOutputStream\nimport java.net.URI\nimport java.nio.charset.StandardCharsets\nimport java.nio.file.Files\nimport java.nio.file.Path\nimport kotlin.io.path.ExperimentalPathApi\nimport kotlin.io.path.createDirectories\nimport kotlin.io.path.createParentDirectories\nimport kotlin.io.path.deleteRecursively\nimport org.assertj.core.api.Assertions.assertThat\nimport org.junit.jupiter.api.AfterAll\nimport org.junit.jupiter.api.AfterEach\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertThrows\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.CliException\nimport org.pkl.commons.test.FileTestUtils\nimport org.pkl.commons.test.PackageServer\nimport org.pkl.commons.writeString\n\n@OptIn(ExperimentalPathApi::class)\n@WireMockTest(httpsEnabled = true, proxyMode = true)\nclass CliCommandRunnerTest {\n private val renderOptions =\n \"\"\"\n extends \"pkl:Command\"\n \n options: Options\n \n output {\n value = options\n }\n \n \"\"\"\n .trimIndent()\n\n companion object {\n private val packageServer = PackageServer()\n\n @AfterAll\n @JvmStatic\n fun afterAll() {\n packageServer.close()\n }\n }\n\n // use manually constructed temp dir instead of @TempDir to work around\n // https://forums.developer.apple.com/thread/118358\n private val tempDir: Path = run {\n val baseDir = FileTestUtils.rootProjectDir.resolve(\"pkl-cli/build/tmp/CliCommandRunnerTest\")\n baseDir.createDirectories()\n Files.createTempDirectory(baseDir, null)\n }\n\n @AfterEach\n fun afterEach() {\n tempDir.deleteRecursively()\n }\n\n private fun writePklFile(fileName: String, contents: String): URI {\n tempDir.resolve(fileName).createParentDirectories()\n return tempDir.resolve(fileName).writeString(contents).toUri()\n }\n\n private fun runToStdout(options: CliBaseOptions, args: List): String {\n val outWriter = ByteArrayOutputStream()\n CliCommandRunner(\n options,\n setOf(\"root-dir\"),\n emptySet(),\n args,\n outWriter,\n ByteArrayOutputStream(),\n )\n .run()\n return outWriter.toString(StandardCharsets.UTF_8)\n }\n\n @Test\n fun `missing required flag`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n foo: String\n }\n \"\"\"\n .trimIndent(),\n )\n\n val exc =\n assertThrows {\n runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri), testMode = true), listOf())\n }\n assertThat(exc.paramName).isEqualTo(\"--foo\")\n }\n\n @Test\n fun `primitive flags`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n `number-as-int`: Number\n `number-as-float`: Number\n `number-nullable`: Number?\n `number-default`: Number = 100.0\n `number-default-overridden`: Number = 100.0\n \n float: Float\n `float-without-decimals`: Float\n `float-nullable`: Float?\n `float-default`: Float = 100.0\n `float-default-overridden`: Float = 100.0\n \n int: Int\n `int-nullable`: Int?\n `int-default`: Int = 100\n `int-default-overridden`: Int = 100\n \n int8: Int8\n int16: Int16\n int32: Int32\n uint: UInt\n uint8: UInt8\n uint16: UInt16\n uint32: UInt32\n \n boolean: Boolean\n `boolean-nullable`: Boolean?\n `boolean-default`: Boolean = true\n `boolean-default-overridden`: Boolean = false\n \n string: String\n `string-nullable`: String?\n `string-default`: String = \"default\"\n `string-default-overridden`: String = \"default\"\n \n char: Char\n `char-nullable`: Char?\n `char-default`: Char = \"a\"\n `char-default-overridden`: Char = \"b\"\n }\n \"\"\"\n .trimIndent(),\n )\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\n \"--number-as-int=123\",\n \"--number-as-float=123.0\",\n \"--number-default-overridden=-200.0\",\n \"--float=123.456\",\n \"--float-without-decimals=789\",\n \"--float-default-overridden=-200\",\n \"--int=123\",\n \"--int-default-overridden=-200\",\n \"--int8=127\",\n \"--int16=32767\",\n \"--int32=2147483647\",\n \"--uint=0\",\n \"--uint8=255\",\n \"--uint16=65535\",\n \"--uint32=4294967295\",\n \"--boolean=n\",\n \"--boolean-default-overridden=1\",\n \"--string=foobar\",\n \"--string-default-overridden=non-default\",\n \"--char=X\",\n \"--char-default-overridden=c\",\n ),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n `number-as-int` = 123\n `number-as-float` = 123.0\n `number-nullable` = null\n `number-default` = 100.0\n `number-default-overridden` = -200.0\n float = 123.456\n `float-without-decimals` = 789.0\n `float-nullable` = null\n `float-default` = 100.0\n `float-default-overridden` = -200.0\n int = 123\n `int-nullable` = null\n `int-default` = 100\n `int-default-overridden` = -200\n int8 = 127\n int16 = 32767\n int32 = 2147483647\n uint = 0\n uint8 = 255\n uint16 = 65535\n uint32 = 4294967295\n boolean = false\n `boolean-nullable` = null\n `boolean-default` = true\n `boolean-default-overridden` = true\n string = \"foobar\"\n `string-nullable` = null\n `string-default` = \"default\"\n `string-default-overridden` = \"non-default\"\n char = \"X\"\n `char-nullable` = null\n `char-default` = \"a\"\n `char-default-overridden` = \"c\"\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `primitive arguments`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @Argument\n `number-as-int`: Number\n @Argument\n `number-as-float`: Number\n \n @Argument\n float: Float\n @Argument\n `float-without-decimals`: Float\n \n @Argument\n int: Int\n \n @Argument\n int8: Int8\n @Argument\n int16: Int16\n @Argument\n int32: Int32\n @Argument\n uint: UInt\n @Argument\n uint8: UInt8\n @Argument\n uint16: UInt16\n @Argument\n uint32: UInt32\n \n @Argument\n boolean: Boolean\n \n @Argument\n string: String\n \n @Argument\n char: Char\n }\n \"\"\"\n .trimIndent(),\n )\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\n \"123\",\n \"123.0\",\n \"123.456\",\n \"789\",\n \"123\",\n \"127\",\n \"32767\",\n \"2147483647\",\n \"0\",\n \"255\",\n \"65535\",\n \"4294967295\",\n \"n\",\n \"foobar\",\n \"X\",\n ),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n `number-as-int` = 123\n `number-as-float` = 123.0\n float = 123.456\n `float-without-decimals` = 789.0\n int = 123\n int8 = 127\n int16 = 32767\n int32 = 2147483647\n uint = 0\n uint8 = 255\n uint16 = 65535\n uint32 = 4294967295\n boolean = false\n string = \"foobar\"\n char = \"X\"\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `enum flags`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n typealias MyEnum = \"d\" | \"e\" | *\"f\"\n class Options {\n enum: \"a\" | \"b\" | \"c\"\n `enum-default`: \"a\" | *\"b\" | \"c\"\n `enum-explicit-default`: \"a\" | \"b\" | \"c\" = \"c\"\n `enum-alias-default`: MyEnum\n `enum-alias-explicit-default`: MyEnum = \"e\"\n `enum-alias-default-overridden`: MyEnum\n \n `enum-single`: \"x\"\n `enum-single-nullable`: \"x\"?\n `enum-single-explicit-default`: \"x\" = \"x\"\n `enum-single-overridden`: \"x\"\n }\n \"\"\"\n .trimIndent(),\n )\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\"--enum=a\", \"--enum-alias-default-overridden=d\", \"--enum-single-overridden=x\"),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n enum = \"a\"\n `enum-default` = \"b\"\n `enum-explicit-default` = \"c\"\n `enum-alias-default` = \"f\"\n `enum-alias-explicit-default` = \"e\"\n `enum-alias-default-overridden` = \"d\"\n `enum-single` = \"x\"\n `enum-single-nullable` = null\n `enum-single-explicit-default` = \"x\"\n `enum-single-overridden` = \"x\"\n\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `enum args`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n typealias MyEnum = \"d\" | \"e\" | *\"f\"\n class Options {\n @Argument\n enum: \"a\" | \"b\" | \"c\"\n @Argument\n `enum-default`: \"a\" | *\"b\" | \"c\"\n @Argument\n `enum-alias-default`: MyEnum\n }\n \"\"\"\n .trimIndent(),\n )\n val output =\n runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri)), listOf(\"a\", \"c\", \"d\"))\n assertThat(output)\n .isEqualTo(\n \"\"\"\n enum = \"a\"\n `enum-default` = \"c\"\n `enum-alias-default` = \"d\"\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `collection flags`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n list: List\n `list-nullable`: List?\n `list-default`: List = List(1, 2, 300.0)\n set: Set\n `set-nullable`: Set?\n `set-default`: Set = Set(1, 2, 300.0, 2)\n \n `enum-list`: List<\"a\" | \"b\" | *\"c\">\n `enum-set`: Set<\"a\" | \"b\" | *\"c\">\n }\n \"\"\"\n .trimIndent(),\n )\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\n \"--list=1\",\n \"--list=0\",\n \"--list=0.0\",\n \"--list=1\",\n \"--set=1\",\n \"--set=0\",\n \"--set=0.0\",\n \"--set=1\",\n \"--enum-list=a\",\n \"--enum-list=a\",\n \"--enum-list=b\",\n \"--enum-set=a\",\n \"--enum-set=a\",\n \"--enum-set=b\",\n ),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n list = List(1, 0, 0.0, 1)\n `list-nullable` = null\n `list-default` = List(1, 2, 300.0)\n set = Set(1, 0, 0.0)\n `set-nullable` = null\n `set-default` = Set(1, 2, 300.0)\n `enum-list` = List(\"a\", \"a\", \"b\")\n `enum-set` = Set(\"a\", \"b\")\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `sequence args`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @Argument\n list: List\n }\n \"\"\"\n .trimIndent(),\n )\n val output =\n runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri)), listOf(\"1\", \"0\", \"0.0\", \"1\"))\n assertThat(output)\n .isEqualTo(\n \"\"\"\n list = List(1, 0, 0.0, 1)\n \n \"\"\"\n .trimIndent()\n )\n\n val moduleUri2 =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @Argument\n set: Set\n }\n \"\"\"\n .trimIndent(),\n )\n val output2 =\n runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri2)), listOf(\"1\", \"0\", \"0.0\", \"1\"))\n assertThat(output2)\n .isEqualTo(\n \"\"\"\n set = Set(1, 0, 0.0)\n \n \"\"\"\n .trimIndent()\n )\n\n val moduleUri3 =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @Argument\n listing: Listing\n }\n \"\"\"\n .trimIndent(),\n )\n val output3 =\n runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri3)), listOf(\"1\", \"0\", \"0.0\", \"1\"))\n assertThat(output3)\n .isEqualTo(\n \"\"\"\n listing {\n 1\n 0\n 0.0\n 1\n }\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `keyval args`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @Argument\n map: Map\n }\n \"\"\"\n .trimIndent(),\n )\n val output =\n runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri)), listOf(\"1=0\", \"0.0=1\"))\n assertThat(output)\n .isEqualTo(\n \"\"\"\n map = Map(1, 0, 0.0, 1)\n \n \"\"\"\n .trimIndent()\n )\n\n val moduleUri2 =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @Argument\n mapping: Mapping\n }\n \"\"\"\n .trimIndent(),\n )\n val output2 =\n runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri2)), listOf(\"1=0\", \"0.0=1\"))\n assertThat(output2)\n .isEqualTo(\n \"\"\"\n mapping {\n [1] = 0\n [0.0] = 1\n }\n \n \"\"\"\n .trimIndent()\n )\n\n val moduleUri3 =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @Argument\n pair: Pair\n }\n \"\"\"\n .trimIndent(),\n )\n val output3 = runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri3)), listOf(\"1=0.0\"))\n assertThat(output3)\n .isEqualTo(\n \"\"\"\n pair = Pair(1, 0.0)\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `map flags`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n typealias MyEnum = \"a\" | \"b\" | *\"c\"\n class Options {\n map: Map\n `map-nullable`: Map?\n `map-default`: Map = Map(\"x\", 123, \"y\", 456.789)\n \n `enum-map`: Map\n }\n \"\"\"\n .trimIndent(),\n )\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\"--map=a=0.0\", \"--map=b=1\", \"--enum-map=a=b\", \"--enum-map=b=c\"),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n map = Map(\"a\", 0.0, \"b\", 1)\n `map-nullable` = null\n `map-default` = Map(\"x\", 123, \"y\", 456.789)\n `enum-map` = Map(\"a\", \"b\", \"b\", \"c\")\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `mapping flags`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n typealias MyEnum = \"a\" | \"b\" | *\"c\"\n class Options {\n mapping: Mapping\n `mapping-nullable`: Mapping?\n `mapping-default`: Mapping = new { [\"x\"] = 123; [\"y\"] = 456.789 }\n \n `enum-mapping`: Mapping\n }\n \"\"\"\n .trimIndent(),\n )\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\"--mapping=a=0.0\", \"--mapping=b=1\", \"--enum-mapping=a=b\", \"--enum-mapping=b=c\"),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n mapping {\n [\"a\"] = 0.0\n [\"b\"] = 1\n }\n `mapping-nullable` = null\n `mapping-default` {\n [\"x\"] = 123\n [\"y\"] = 456.789\n }\n `enum-mapping` {\n [\"a\"] = \"b\"\n [\"b\"] = \"c\"\n }\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `pair flags`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n typealias MyEnum = \"a\" | \"b\" | *\"c\"\n class Options {\n pair: Pair\n `pair-nullable`: Pair?\n `pair-default`: Pair = Pair(\"x\", 123)\n \n `enum-pair`: Pair\n }\n \"\"\"\n .trimIndent(),\n )\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\"--pair=a=0.0\", \"--enum-pair=a=b\"),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n pair = Pair(\"a\", 0.0)\n `pair-nullable` = null\n `pair-default` = Pair(\"x\", 123)\n `enum-pair` = Pair(\"a\", \"b\")\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `convert Duration`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @Argument { convert = module.convertDuration }\n a: Duration\n @Argument { convert = module.convertDuration }\n b: Duration\n @Argument { convert = module.convertDuration }\n c: Duration\n @Argument { convert = module.convertDuration }\n d: Duration\n }\n \"\"\"\n .trimIndent(),\n )\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\"10.h\", \"10H\", \"10.5.MS\", \"10.5d\"),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n a = 10.h\n b = 10.h\n c = 10.5.ms\n d = 10.5.d\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `convert DataSize`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @Argument { convert = module.convertDataSize }\n a: DataSize\n @Argument { convert = module.convertDataSize }\n b: DataSize\n @Argument { convert = module.convertDataSize }\n c: DataSize\n @Argument { convert = module.convertDataSize }\n d: DataSize\n }\n \"\"\"\n .trimIndent(),\n )\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\"10.gb\", \"10GB\", \"10.5.MB\", \"10.5tib\"),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n a = 10.gb\n b = 10.gb\n c = 10.5.mb\n d = 10.5.tib\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `convert import`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n \"\"\"\n extends \"pkl:Command\"\n \n options: Options\n \n output {\n value = (options) {\n fromImport {\n baz = true // assert that imported modules are not forced\n }\n }\n }\n \n class Options {\n @Argument { convert = (it) -> new Import{ uri = it } }\n fromImport: Module\n }\n \"\"\"\n .trimIndent(),\n )\n\n val importUri =\n writePklFile(\n \"import.pkl\",\n \"\"\"\n foo = 1\n bar = \"baz\"\n baz: Boolean\n \"\"\"\n .trimIndent(),\n )\n\n val output =\n runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri)), listOf(importUri.toString()))\n assertThat(output)\n .isEqualTo(\n \"\"\"\n fromImport {\n foo = 1\n bar = \"baz\"\n baz = true\n }\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `transformAll import`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n \"\"\"\n extends \"pkl:Command\"\n \n options: Options\n \n output {\n value = (options) {\n fromImport {\n baz = true // assert that imported modules are not forced\n }\n }\n }\n \n class Options {\n @Flag {\n convert = (it) -> new Import{ uri = it }\n transformAll = (values) -> values.firstOrNull ?? new Import { uri = \"./default.pkl\" }\n }\n fromImport: Module\n }\n \"\"\"\n .trimIndent(),\n )\n\n val importUri =\n writePklFile(\n \"default.pkl\",\n \"\"\"\n foo = 1\n bar = \"baz\"\n baz: Boolean\n \"\"\"\n .trimIndent(),\n )\n\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri), workingDir = tempDir),\n emptyList(),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n fromImport {\n foo = 1\n bar = \"baz\"\n baz = true\n }\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `convert glob import`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n \"\"\"\n extends \"pkl:Command\"\n import \"base.pkl\"\n \n options: Options\n \n output {\n value = (options) {\n fromGlobImport {\n [[true]] {\n baz = true // assert that imported modules are not forced\n }\n }\n }\n }\n \n class Options {\n @Argument { convert = (it) -> new Import { uri = it; glob = true }; multiple = false }\n fromGlobImport: Mapping\n }\n \"\"\"\n .trimIndent(),\n )\n\n val baseImport =\n writePklFile(\n \"base.pkl\",\n \"\"\"\n foo: Int\n bar: String\n baz: Boolean\n \"\"\"\n .trimIndent(),\n )\n writePklFile(\n \"glob1.pkl\",\n \"\"\"\n amends \"base.pkl\"\n foo = 1\n bar = \"baz\"\n \"\"\"\n .trimIndent(),\n )\n writePklFile(\n \"glob2.pkl\",\n \"\"\"\n amends \"base.pkl\"\n foo = 2\n bar = \"qux\"\n \"\"\"\n .trimIndent(),\n )\n\n val importDirUri = baseImport.resolve(\".\")\n\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(importDirUri.resolve(\"./glob*.pkl\").toString()),\n )\n assertThat(output.replace(importDirUri.toString(), \"file:/

/\"))\n .isEqualTo(\n \"\"\"\n fromGlobImport {\n [\"file://glob1.pkl\"] {\n foo = 1\n bar = \"baz\"\n baz = true\n }\n [\"file://glob2.pkl\"] {\n foo = 2\n bar = \"qux\"\n baz = true\n }\n }\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `convert that throws`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @Argument { convert = (it) -> throw(\"oops!\") }\n foo: String\n }\n \"\"\"\n .trimIndent(),\n )\n\n val exc =\n assertThrows {\n runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri)), listOf(\"hi\"))\n }\n assertThat(exc.message).contains(\"oops!\")\n }\n\n @Test\n fun `convert with eval error`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @Argument { convert = (it) -> it.noSuchMethod() }\n foo: String\n }\n \"\"\"\n .trimIndent(),\n )\n\n val exc =\n assertThrows {\n runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri)), listOf(\"hi\"))\n }\n assertThat(exc.message).contains(\"Cannot find method `noSuchMethod` in class `String`.\")\n }\n\n @Test\n fun `convert with stack overflow`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n const function overflow(it) = overflow(it)\n class Options {\n @Argument { convert = (it) -> overflow(it) }\n foo: String\n }\n \"\"\"\n .trimIndent(),\n )\n\n val exc =\n assertThrows {\n runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri)), listOf(\"hi\"))\n }\n assertThat(exc.message).contains(\"A stack overflow occurred.\")\n }\n\n @Test\n fun `boolean flag`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @BooleanFlag\n `bool-true`: Boolean\n @BooleanFlag\n `bool-false`: Boolean\n @BooleanFlag\n `bool-nullable`: Boolean?\n @BooleanFlag\n `bool-default-true`: Boolean = true\n @BooleanFlag\n `bool-default-false`: Boolean = false\n }\n \"\"\"\n .trimIndent(),\n )\n\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\"--bool-true\", \"--no-bool-false\"),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n `bool-true` = true\n `bool-false` = false\n `bool-nullable` = null\n `bool-default-true` = true\n `bool-default-false` = false\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `boolean flag with bad type`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @BooleanFlag\n foo: String\n }\n \"\"\"\n .trimIndent(),\n )\n\n val exc =\n assertThrows {\n runToStdout(CliBaseOptions(sourceModules = listOf(moduleUri)), listOf(\"hi\"))\n }\n assertThat(exc.message)\n .contains(\"Option `foo` with annotation `@BooleanFlag` has invalid type `String`.\")\n }\n\n @Test\n fun `counted flag`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @CountedFlag { shortName = \"a\" }\n int: Int\n @CountedFlag { shortName = \"b\" }\n int8: Int8\n @CountedFlag { shortName = \"c\" }\n int16: Int16\n @CountedFlag { shortName = \"d\" }\n int32: Int32\n @CountedFlag { shortName = \"x\" }\n uint: UInt\n @CountedFlag { shortName = \"y\" }\n uint8: UInt8\n @CountedFlag { shortName = \"g\" }\n uint16: UInt16\n @CountedFlag { shortName = \"i\" }\n uint32: UInt32\n }\n \"\"\"\n .trimIndent(),\n )\n\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\"-abbcccddddxxxxxyyyyyygggggggiiiiiiii\"),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n int = 1\n int8 = 2\n int16 = 3\n int32 = 4\n uint = 5\n uint8 = 6\n uint16 = 7\n uint32 = 8\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `test transformAll`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n @Flag {\n multiple = true\n transformAll = (values) -> values.fold(0, (res, acc) -> res + acc)\n }\n foo: Int\n }\n \"\"\"\n .trimIndent(),\n )\n\n val output =\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\"--foo=1\", \"--foo=5\", \"--foo=8\"),\n )\n assertThat(output)\n .isEqualTo(\n \"\"\"\n foo = 14\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `completion candidates`() {\n val moduleUri =\n writePklFile(\n \"cmd.pkl\",\n renderOptions +\n \"\"\"\n class Options {\n none: String?\n enum: *\"a\" | \"b\" | \"c\"\n @Flag { completionCandidates = \"paths\" }\n path: String?\n @Flag { completionCandidates { \"foo\"; \"bar\"; \"baz\" } }\n explicit: String?\n @Argument\n enumArg: *\"a\" | \"b\" | \"c\"\n @Argument { completionCandidates = \"paths\" }\n pathArg: String\n @Argument { completionCandidates { \"foo\"; \"bar\"; \"baz\" } }\n explicitArg: String\n }\n \"\"\"\n .trimIndent(),\n )\n val exc =\n assertThrows {\n runToStdout(\n CliBaseOptions(sourceModules = listOf(moduleUri)),\n listOf(\"a\", \"foo\", \"bar\", \"shell-completion\", \"bash\"),\n )\n }\n assertThat(exc.message)\n .contains(\n \"\"\"\n \"--none\")\n ;;\n \"--enum\")\n COMPREPLY=($(compgen -W 'a b c' -- \"${'$'}{word}\"))\n ;;\n \"--path\")\n __complete_files \"${'$'}{word}\"\n ;;\n \"--explicit\")\n COMPREPLY=($(compgen -W 'bar baz foo' -- \"${'$'}{word}\"))\n ;;\n \"--help\")\n ;;\n \"enumArg\")\n COMPREPLY=($(compgen -W '' -- \"${'$'}{word}\"))\n ;;\n \"pathArg\")\n __complete_files \"${'$'}{word}\"\n ;;\n \"explicitArg\")\n COMPREPLY=($(compgen -W 'bar baz foo' -- \"${'$'}{word}\"))\n ;;\"\"\"\n )\n }\n}\n" }, { "path": "pkl-cli/src/test/kotlin/org/pkl/cli/CliEvaluatorTest.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport com.github.tomakehurst.wiremock.client.WireMock.*\nimport com.github.tomakehurst.wiremock.junit5.WireMockRuntimeInfo\nimport com.github.tomakehurst.wiremock.junit5.WireMockTest\nimport java.io.ByteArrayInputStream\nimport java.io.ByteArrayOutputStream\nimport java.net.ServerSocket\nimport java.net.URI\nimport java.nio.charset.StandardCharsets\nimport java.nio.file.Files\nimport java.nio.file.Path\nimport java.time.Duration\nimport java.util.regex.Pattern\nimport kotlin.io.path.*\nimport org.assertj.core.api.Assertions.assertThat\nimport org.assertj.core.api.Assertions.assertThatCode\nimport org.junit.jupiter.api.*\nimport org.junit.jupiter.api.condition.DisabledOnOs\nimport org.junit.jupiter.api.condition.EnabledOnOs\nimport org.junit.jupiter.api.condition.OS\nimport org.junit.jupiter.api.io.TempDir\nimport org.junit.jupiter.params.ParameterizedTest\nimport org.junit.jupiter.params.provider.EnumSource\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.CliException\nimport org.pkl.commons.readString\nimport org.pkl.commons.test.FileTestUtils\nimport org.pkl.commons.test.PackageServer\nimport org.pkl.commons.toPath\nimport org.pkl.commons.writeString\nimport org.pkl.core.OutputFormat\nimport org.pkl.core.SecurityManagers\nimport org.pkl.core.util.IoUtils\n\n@OptIn(ExperimentalPathApi::class)\n@WireMockTest(httpsEnabled = true, proxyMode = true)\nclass CliEvaluatorTest {\n companion object {\n private val defaultContents =\n \"\"\"\n person {\n name = \"pigeon\"\n age = 20 + 10\n }\n \"\"\"\n .trimIndent()\n\n private val packageServer = PackageServer()\n\n @AfterAll\n @JvmStatic\n fun afterAll() {\n packageServer.close()\n }\n }\n\n // use manually constructed temp dir instead of @TempDir to work around\n // https://forums.developer.apple.com/thread/118358\n private val tempDir: Path = run {\n val baseDir = FileTestUtils.rootProjectDir.resolve(\"pkl-cli/build/tmp/CliEvaluatorTest\")\n baseDir.createDirectories()\n Files.createTempDirectory(baseDir, null)\n }\n\n @AfterEach\n fun afterEach() {\n tempDir.deleteRecursively()\n }\n\n @Test\n fun `generate Pcf`() {\n val sourceFiles = listOf(writePklFile(\"test.pkl\"))\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(CliBaseOptions(sourceModules = sourceFiles), outputFormat = \"pcf\")\n )\n\n assertThat(outputFiles).hasSize(1)\n checkOutputFile(\n outputFiles[0],\n \"test.pcf\",\n \"\"\"\nperson {\n name = \"pigeon\"\n age = 30\n}\n \"\"\",\n )\n }\n\n @Test\n fun `generate JSON`() {\n val sourceFiles = listOf(writePklFile(\"test.pkl\"))\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(CliBaseOptions(sourceModules = sourceFiles), outputFormat = \"json\")\n )\n\n assertThat(outputFiles).hasSize(1)\n checkOutputFile(\n outputFiles[0],\n \"test.json\",\n \"\"\"\n{\n \"person\": {\n \"name\": \"pigeon\",\n \"age\": 30\n }\n}\n \"\"\",\n )\n }\n\n @Test\n fun `generate YAML`() {\n val sourceFiles = listOf(writePklFile(\"test.pkl\"))\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(CliBaseOptions(sourceModules = sourceFiles), outputFormat = \"yaml\")\n )\n\n assertThat(outputFiles).hasSize(1)\n checkOutputFile(\n outputFiles[0],\n \"test.yaml\",\n \"\"\"\nperson:\n name: pigeon\n age: 30\n \"\"\",\n )\n }\n\n @Test\n fun `generate plist`() {\n val sourceFiles = listOf(writePklFile(\"test.pkl\"))\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(CliBaseOptions(sourceModules = sourceFiles), outputFormat = \"plist\")\n )\n\n assertThat(outputFiles).hasSize(1)\n checkOutputFile(\n outputFiles[0],\n \"test.plist\",\n \"\"\"\n\n\n\n\n person\n \n name\n pigeon\n age\n 30\n \n\n\n \"\"\",\n )\n }\n\n @Test\n fun `generate XML`() {\n val sourceFiles = listOf(writePklFile(\"test.pkl\"))\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(CliBaseOptions(sourceModules = sourceFiles), outputFormat = \"xml\")\n )\n\n assertThat(outputFiles).hasSize(1)\n checkOutputFile(\n outputFiles[0],\n \"test.xml\",\n \"\"\"\n\n\n \n pigeon\n 30\n \n\n \"\"\",\n )\n }\n\n @Test\n fun `unknown output format`() {\n val sourceFiles = listOf(writePklFile(\"test.pkl\"))\n\n val e =\n assertThrows {\n evalToFiles(\n CliEvaluatorOptions(CliBaseOptions(sourceModules = sourceFiles), outputFormat = \"unknown\")\n )\n }\n\n assertThat(e).hasMessageContaining(\"Unknown output format: `unknown`. \")\n }\n\n @Test\n fun `generate multiple files`() {\n val sourceFiles =\n listOf(\n writePklFile(\"file1.pkl\", \"x = 1 + 1\"),\n writePklFile(\"file2.pkl\", \"x = 2 + 2\"),\n writePklFile(\"file3.pkl\", \"x = 3 + 3\"),\n )\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(CliBaseOptions(sourceModules = sourceFiles), outputFormat = \"pcf\")\n )\n\n assertThat(outputFiles).hasSize(3)\n checkOutputFile(outputFiles[0], \"file1.pcf\", \"x = 2\")\n checkOutputFile(outputFiles[1], \"file2.pcf\", \"x = 4\")\n checkOutputFile(outputFiles[2], \"file3.pcf\", \"x = 6\")\n }\n\n @Test\n fun `module path module as source module`() {\n val dir = tempDir.resolve(\"foo\").resolve(\"bar\").createDirectories()\n dir.resolve(\"test.pkl\").writeString(defaultContents)\n // check relative imports too\n dir\n .resolve(\"test2.pkl\")\n .writeString(\n \"\"\"\n amends \"test.pkl\"\n \n person {\n name = \"barn owl\"\n }\n \"\"\"\n .trimIndent()\n )\n\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules =\n listOf(URI(\"modulepath:/foo/bar/test.pkl\"), URI(\"modulepath:/foo/bar/test2.pkl\")),\n modulePath = listOf(tempDir),\n ),\n outputFormat = \"pcf\",\n outputPath = \"$tempDir/%{moduleName}.%{outputFormat}\",\n )\n )\n\n assertThat(outputFiles).hasSize(2)\n checkOutputFile(\n outputFiles[0],\n \"test.pcf\",\n \"\"\"\nperson {\n name = \"pigeon\"\n age = 30\n}\n \"\"\",\n )\n checkOutputFile(\n outputFiles[1],\n \"test2.pcf\",\n \"\"\"\nperson {\n name = \"barn owl\"\n age = 30\n}\n \"\"\",\n )\n }\n\n @Test\n fun `external properties`() {\n val sourceFiles =\n listOf(\n writePklFile(\n \"test.pkl\",\n \"\"\"\nperson {\n name = read(\"prop:name\")\n age = read(\"prop:age\").toInt()\n}\n \"\"\",\n )\n )\n\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules = sourceFiles,\n externalProperties = mapOf(\"name\" to \"pigeon\", \"age\" to \"30\"),\n ),\n outputFormat = \"pcf\",\n )\n )\n\n assertThat(outputFiles).hasSize(1)\n checkOutputFile(\n outputFiles[0],\n \"test.pcf\",\n \"\"\"\nperson {\n name = \"pigeon\"\n age = 30\n}\n \"\"\",\n )\n }\n\n @Test\n fun `custom working directory given as absolute path`() {\n customWorkingDirectory(relativePath = false)\n }\n\n @Test\n fun `custom working directory given as relative path (the norm when using cli)`() {\n customWorkingDirectory(relativePath = true)\n }\n\n private fun customWorkingDirectory(relativePath: Boolean) {\n val dir = tempDir.resolve(\"foo\").resolve(\"bar\").createDirectories()\n val file = dir.resolve(\"test.pkl\").writeString(defaultContents)\n\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules = listOf(file.toUri()),\n workingDir =\n if (relativePath) IoUtils.getCurrentWorkingDir().relativize(dir.parent)\n else dir.parent,\n ),\n outputFormat = \"pcf\",\n outputPath = \"baz/%{moduleName}.pcf\",\n )\n )\n\n assertThat(outputFiles).hasSize(1)\n assertThat(outputFiles[0].normalize()).isEqualTo(dir.parent.resolve(\"baz/test.pcf\"))\n checkOutputFile(\n outputFiles[0],\n \"test.pcf\",\n \"\"\"\nperson {\n name = \"pigeon\"\n age = 30\n}\n \"\"\",\n )\n }\n\n @Test\n fun `source module with relative path`() {\n val dir = tempDir.resolve(\"foo\").createDirectories()\n dir.resolve(\"test.pkl\").writeString(defaultContents)\n\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(URI(\"foo/test.pkl\")), workingDir = tempDir),\n outputFormat = \"pcf\",\n )\n )\n\n assertThat(outputFiles).hasSize(1)\n checkOutputFile(\n outputFiles[0],\n \"test.pcf\",\n \"\"\"\nperson {\n name = \"pigeon\"\n age = 30\n}\n \"\"\",\n )\n }\n\n @Test\n fun `module path element with relative path`() {\n val libDir = tempDir.resolve(\"lib\").resolve(\"foo\").createDirectories()\n libDir.resolve(\"someLib.pkl\").writeString(\"x = 1\")\n\n val pklScript =\n writePklFile(\n \"test.pkl\",\n \"\"\"\nimport \"modulepath:/foo/someLib.pkl\"\nresult = someLib.x\n \"\"\",\n )\n\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules = listOf(pklScript),\n workingDir = tempDir,\n modulePath = listOf(\"lib\".toPath()),\n ),\n outputFormat = \"pcf\",\n )\n )\n\n assertThat(outputFiles).hasSize(1)\n checkOutputFile(outputFiles[0], \"test.pcf\", \"result = 1\")\n }\n\n @Test\n fun `moduleDir is relative to workingDir even if not descendant`() {\n val contents = \"foo = 42\"\n val file = writePklFile(\"some/nested/structure.pkl\", contents)\n val workingDir = tempDir.resolve(\"another/structure\").createDirectories()\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(file), workingDir = workingDir),\n outputPath = \"%{moduleDir}/result.pcf\",\n outputFormat = \"pcf\",\n )\n )\n assertThat(outputFiles).hasSize(1)\n assertThat(outputFiles[0]).isEqualTo(tempDir.resolve(\"some/nested/result.pcf\"))\n checkOutputFile(outputFiles[0], \"result.pcf\", contents)\n }\n\n // Can't reliably create symlinks on Windows.\n // Might get errors like \"A required privilege is not held by the client\".\n @Test\n @DisabledOnOs(OS.WINDOWS)\n fun `moduleDir is relative to workingDir even through symlinks`() {\n val contents = \"foo = 42\"\n val realWorkingDir = tempDir.resolve(\"workingDir\").createDirectories()\n val symlinkToTempDir = Files.createSymbolicLink(tempDir.resolve(\"symlinkToTempDir\"), tempDir)\n val workingDir = symlinkToTempDir.resolve(\"workingDir\")\n val file = realWorkingDir.resolve(\"test.pkl\").writeString(contents).toUri()\n val outputFiles =\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(file), workingDir = workingDir),\n outputFormat = \"pcf\",\n )\n )\n assertThat(outputFiles).hasSize(1)\n assertThat(outputFiles[0].toString()).doesNotContain(\"symlinkToTempDir\")\n checkOutputFile(outputFiles[0], \"test.pcf\", contents)\n }\n\n @Test\n fun `take input from stdin`() {\n val stdin = ByteArrayInputStream(defaultContents.toByteArray(StandardCharsets.UTF_8))\n val stdout = ByteArrayOutputStream()\n val evaluator =\n CliEvaluator(\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(URI(\"repl:text\"))),\n outputFormat = \"pcf\",\n ),\n stdin,\n stdout,\n )\n evaluator.run()\n assertThat(stdout.toString(StandardCharsets.UTF_8).trim())\n .isEqualTo(defaultContents.replace(\"20 + 10\", \"30\").trim())\n }\n\n @Test\n fun `write output to console`() {\n val module1 = writePklFile(\"mod1.pkl\", \"x = 21 + 21\")\n val module2 = writePklFile(\"mod2.pkl\", \"y = 11 + 11\")\n\n val output =\n evalToConsole(CliEvaluatorOptions(CliBaseOptions(sourceModules = listOf(module1, module2))))\n\n assertThat(output).isEqualTo(\"x = 42\\n---\\ny = 22\\n\")\n }\n\n @Test\n fun `evaluation timeout`() {\n val sourceFiles =\n listOf(\n writePklFile(\n \"test.pkl\",\n \"\"\"\n function fib(n) = if (n < 2) 0 else fib(n - 1) + fib(n - 2)\n x = fib(100)\n \"\"\",\n )\n )\n\n val e =\n assertThrows {\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = sourceFiles, timeout = Duration.ofMillis(100)),\n outputFormat = \"pcf\",\n )\n )\n }\n assertThat(e.message).contains(\"timed out\")\n }\n\n @Test\n fun `cannot import module located outside root dir`() {\n val sourceFiles =\n listOf(\n writePklFile(\n \"test.pkl\",\n \"\"\"\n amends \"/non/existing.pkl\"\n \"\"\",\n )\n )\n\n val e =\n assertThrows {\n evalToFiles(\n CliEvaluatorOptions(CliBaseOptions(sourceModules = sourceFiles, rootDir = tempDir))\n )\n }\n\n assertThat(e.message).contains(\"Refusing to load module `file:///non/existing.pkl`\")\n }\n\n @Test\n fun `concatenate file outputs`() {\n val sourceFiles =\n listOf(\n writePklFile(\"test1.pkl\", \"x = 1\"),\n writePklFile(\"test2.pkl\", \"x = 2\"),\n writePklFile(\"test3.pkl\", \"x = 3\"),\n )\n\n val outputFile = tempDir.resolve(\"output.yaml\")\n\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = sourceFiles),\n outputFile.toString(),\n \"yaml\",\n )\n )\n\n checkOutputFile(outputFile, \"output.yaml\", \"x: 1\\n---\\nx: 2\\n---\\nx: 3\")\n }\n\n @Test\n fun `concatenate file outputs - some empty YAML streams`() {\n val sourceFiles =\n listOf(\n writePklFile(\n \"test0.pkl\",\n \"output { value = List(); renderer = new YamlRenderer { isStream = true } }\",\n ),\n writePklFile(\"test1.pkl\", \"x = 1\"),\n writePklFile(\n \"test2.pkl\",\n \"output { value = List(); renderer = new YamlRenderer { isStream = true } }\",\n ),\n writePklFile(\"test3.pkl\", \"x = 3\"),\n writePklFile(\n \"test4.pkl\",\n \"output { value = List(); renderer = new YamlRenderer { isStream = true } }\",\n ),\n )\n\n val outputFile = tempDir.resolve(\"output.yaml\")\n\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = sourceFiles),\n outputFile.toString(),\n \"yaml\",\n )\n )\n\n checkOutputFile(outputFile, \"output.yaml\", \"x: 1\\n---\\nx: 3\")\n }\n\n @Test\n fun `concatenate module outputs with custom separator`() {\n val sourceFiles =\n listOf(\n writePklFile(\"test1.pkl\", \"x = 1\"),\n writePklFile(\"test2.pkl\", \"x = 2\"),\n writePklFile(\"test3.pkl\", \"x = 3\"),\n )\n\n val outputFile = tempDir.resolve(\"output.pcf\")\n\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = sourceFiles),\n outputFile.toString(),\n outputFormat = \"pcf\",\n moduleOutputSeparator = \"// my module separator\",\n )\n )\n\n checkOutputFile(\n outputFile,\n \"output.pcf\",\n \"\"\"\n x = 1\n // my module separator\n x = 2\n // my module separator\n x = 3\n \"\"\"\n .trimIndent(),\n )\n }\n\n @Test\n fun `concatenate module outputs with empty custom separator`() {\n val sourceFiles =\n listOf(\n writePklFile(\"test1.pkl\", \"x = 1\"),\n writePklFile(\"test2.pkl\", \"y = 2\"),\n writePklFile(\"test3.pkl\", \"z = 3\"),\n )\n\n val outputFile = tempDir.resolve(\"output.pcf\")\n\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = sourceFiles),\n outputFile.toString(),\n outputFormat = \"pcf\",\n moduleOutputSeparator = \"\",\n )\n )\n\n checkOutputFile(\n outputFile,\n \"output.pcf\",\n \"\"\"\n x = 1\n \n y = 2\n \n z = 3\n \"\"\"\n .trimIndent(),\n )\n }\n\n @Test\n fun `concatenate console outputs`() {\n val sourceFiles =\n listOf(\n writePklFile(\"test1.pkl\", \"x = 1\"),\n writePklFile(\"test2.pkl\", \"x = 2\"),\n writePklFile(\"test3.pkl\", \"x = 3\"),\n )\n\n val output =\n evalToConsole(\n CliEvaluatorOptions(CliBaseOptions(sourceModules = sourceFiles), outputFormat = \"yaml\")\n )\n\n assertThat(output).isEqualTo(\"x: 1\\n---\\nx: 2\\n---\\nx: 3\\n\")\n }\n\n @Test\n fun `concatenate console outputs - some empty YAML streams`() {\n val sourceFiles =\n listOf(\n writePklFile(\n \"test0.pkl\",\n \"output { value = List(); renderer = new YamlRenderer { isStream = true } }\",\n ),\n writePklFile(\"test1.pkl\", \"x = 1\"),\n writePklFile(\n \"test2.pkl\",\n \"output { value = List(); renderer = new YamlRenderer { isStream = true } }\",\n ),\n writePklFile(\"test3.pkl\", \"x = 3\"),\n writePklFile(\n \"test4.pkl\",\n \"output { value = List(); renderer = new YamlRenderer { isStream = true } }\",\n ),\n )\n\n val output =\n evalToConsole(\n CliEvaluatorOptions(CliBaseOptions(sourceModules = sourceFiles), outputFormat = \"yaml\")\n )\n\n assertThat(output).isEqualTo(\"x: 1\\n---\\nx: 3\\n\")\n }\n\n // prototext can't render `Dynamic`.\n @EnumSource(names = [\"TEXTPROTO\"], mode = EnumSource.Mode.EXCLUDE)\n @ParameterizedTest(name = \"{0} console output ends with newline\")\n fun `console output ends with newline`(outputFormat: OutputFormat) {\n val sourceFiles = listOf(writePklFile(\"test0.pkl\", \"foo = 0\\nbar=\\\"Baz\\\"\"))\n val output =\n evalToConsole(\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = sourceFiles),\n outputFormat = outputFormat.toString(),\n )\n )\n assertThat(output).endsWith(\"\\n\")\n }\n\n @Test\n fun `file output throws if output file is a directory`() {\n val sourceFiles =\n listOf(\n writePklFile(\n \"test.pkl\",\n \"\"\"\n name = \"test\"\n output {\n files {\n [\"\\(name).txt\"] {\n text = \"test\"\n }\n } \n }\n \"\"\"\n .trimIndent(),\n )\n )\n val err =\n assertThrows {\n evalToFiles(\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = sourceFiles),\n outputPath = tempDir.toString(),\n )\n )\n }\n assertThat(err)\n .hasMessageContaining(\"Output file `$tempDir` is a directory. \")\n .hasMessageContaining(\"Did you mean `--multiple-file-output-path`?\")\n }\n\n @Test\n fun `multiple file output writes multiple files to the provided directory`() {\n val contents =\n \"\"\"\n output {\n files {\n [\"foo.pcf\"] {\n value = new Dynamic {\n [\"bar\"] = \"baz\"\n }\n }\n [\"bar/baz.pcf\"] {\n value = new Dynamic {\n [\"baz\"] = \"biz\"\n }\n }\n [\"buz.txt\"] {\n text = \"buz\"\n }\n }\n }\n \"\"\"\n .trimIndent()\n val sourceFile = writePklFile(\"test.pkl\", contents)\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(sourceFile), workingDir = tempDir),\n outputPath = \"my-outputs\",\n multipleFileOutputPath = \".my-output/\",\n )\n val evaluator = CliEvaluator(options)\n evaluator.run()\n checkOutputFile(\n tempDir.resolve(\".my-output/foo.pcf\"),\n \"foo.pcf\",\n \"\"\"\n [\"bar\"] = \"baz\"\n \"\"\"\n .trimIndent(),\n )\n checkOutputFile(\n tempDir.resolve(\".my-output/bar/baz.pcf\"),\n \"baz.pcf\",\n \"\"\"\n [\"baz\"] = \"biz\"\n \"\"\"\n .trimIndent(),\n )\n checkOutputFile(tempDir.resolve(\".my-output/buz.txt\"), \"buz.txt\", \"buz\")\n }\n\n @Test\n fun `multiple file output writes multiple modules to the output path`() {\n val sourceModules =\n listOf(\n writePklFile(\n \"test0.pkl\",\n \"\"\"\n output {\n files {\n [\"foo.pcf\"] {\n value = new Dynamic {\n [\"bar\"] = \"baz\"\n }\n }\n }\n }\n \"\"\"\n .trimIndent(),\n ),\n writePklFile(\n \"test1.pkl\",\n \"\"\"\n output {\n files {\n [\"bar.pcf\"] {\n value = new Dynamic {\n [\"bar\"] = \"baz\"\n }\n }\n }\n }\n \"\"\"\n .trimIndent(),\n ),\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = sourceModules, workingDir = tempDir),\n multipleFileOutputPath = \".\",\n )\n CliEvaluator(options).run()\n assertThat(tempDir.resolve(\"foo.pcf\")).isRegularFile.hasFileName(\"foo.pcf\")\n assertThat(tempDir.resolve(\"bar.pcf\")).isRegularFile.hasFileName(\"bar.pcf\")\n }\n\n @Test\n fun `multiple file output throws in case of conflict`() {\n val sourceModules =\n listOf(\n writePklFile(\n \"bar.pkl\",\n \"\"\"\n output {\n files {\n [\"foo.pcf\"] {\n text = \"myBar\"\n }\n }\n }\n \"\"\"\n .trimIndent(),\n ),\n writePklFile(\n \"foo.pkl\",\n \"\"\"\n output {\n files {\n [\"foo.pcf\"] {\n text = \"myFoo\"\n }\n }\n }\n \"\"\"\n .trimIndent(),\n ),\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = sourceModules, workingDir = tempDir),\n multipleFileOutputPath = \".\",\n )\n assertThrows { CliEvaluator(options).run() }\n }\n\n @Test\n fun `multiple file output writes nothing if output files is null`() {\n val moduleUri = writePklFile(\"test.pkl\", \"\")\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(moduleUri), workingDir = tempDir),\n multipleFileOutputPath = \".output\",\n )\n val output = evalToConsole(options)\n assertThat(output).isEqualTo(\"\")\n assertThat(tempDir.listDirectoryEntries()).hasSize(1)\n }\n\n @Test\n fun `multiple file output throws if files are written outside the base path`() {\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n output {\n files {\n [\"../foo.txt\"] {\n text = \"bar\"\n }\n }\n }\n \"\"\"\n .trimIndent(),\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(moduleUri), workingDir = tempDir),\n multipleFileOutputPath = \".output\",\n )\n assertThatCode { evalToConsole(options) }\n .hasMessageStartingWith(\"Output file conflict:\")\n .hasMessageContaining(\"which is outside output directory\")\n }\n\n @Test\n fun `multiple file output throws if file path is a directory`() {\n tempDir.resolve(\".output/myDir\").createDirectories()\n val moduleUris =\n listOf(\n writePklFile(\n \"test1.pkl\",\n \"\"\"\n output {\n files {\n [\".\"] { text = \"bar\" }\n }\n }\n \"\"\"\n .trimIndent(),\n ),\n writePklFile(\n \"test2.pkl\",\n \"\"\"\n output {\n files {\n [\"myDir\"] { text = \"bar\" }\n }\n }\n \"\"\"\n .trimIndent(),\n ),\n )\n for (moduleUri in moduleUris) {\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(moduleUri), workingDir = tempDir),\n multipleFileOutputPath = \".output\",\n )\n assertThatCode { evalToConsole(options) }\n .hasMessageStartingWith(\"Output file conflict:\")\n .hasMessageContaining(\"which is a directory\")\n }\n }\n\n @Test\n fun `multiple file output throws on conflicting files`() {\n val moduleUris =\n listOf(\n writePklFile(\n \"test1.pkl\",\n \"\"\"\n output {\n files {\n [\"foo.txt\"] { text = \"bar\" }\n }\n }\n \"\"\"\n .trimIndent(),\n ),\n writePklFile(\n \"test2.pkl\",\n \"\"\"\n output {\n files {\n [\"foo.txt\"] { text = \"bar\" }\n }\n }\n \"\"\"\n .trimIndent(),\n ),\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = moduleUris, workingDir = tempDir),\n multipleFileOutputPath = \".output\",\n )\n assertThatCode { evalToConsole(options) }\n .hasMessageContaining(\"Output file conflict:\")\n .hasMessageContaining(\"resolve to the same file path\")\n }\n\n @Test\n fun `multi-output throws on conflicting files within the same module`() {\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n output {\n files {\n [\"foo.txt\"] { text = \"bar\" }\n [\"./foo.txt\"] { text = \"bar\" }\n }\n }\n \"\"\"\n .trimIndent(),\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(moduleUri), workingDir = tempDir),\n multipleFileOutputPath = \".output\",\n )\n assertThatCode { evalToConsole(options) }\n .hasMessageContaining(\"Output file conflict:\")\n .hasMessageContaining(\"resolve to the same file path\")\n }\n\n @Test\n @EnabledOnOs(OS.WINDOWS)\n fun `multiple-file output throws when using invalid Windows characters`() {\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n output {\n files {\n [\"foo:bar\"] { text = \"bar\" }\n }\n }\n \"\"\"\n .trimIndent(),\n )\n\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(moduleUri), workingDir = tempDir),\n multipleFileOutputPath = \".output\",\n )\n assertThatCode { evalToConsole(options) }\n .hasMessageContaining(\"Path spec `foo:bar` contains illegal character `:`.\")\n }\n\n @Test\n @EnabledOnOs(OS.WINDOWS)\n fun `multiple-file output - cannot use backslash as dir separator on Windows`() {\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n output {\n files {\n [\"foo\\\\bar\"] { text = \"bar\" }\n }\n }\n \"\"\"\n .trimIndent(),\n )\n\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(moduleUri), workingDir = tempDir),\n multipleFileOutputPath = \".output\",\n )\n assertThatCode { evalToConsole(options) }\n .hasMessageContaining(\"Path spec `foo\\\\bar` contains illegal character `\\\\`.\")\n }\n\n @Test\n fun `evaluate output expression`() {\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n foo {\n bar = 1\n }\n \"\"\"\n .trimIndent(),\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(moduleUri), workingDir = tempDir),\n expression = \"foo\",\n )\n val buffer = ByteArrayOutputStream()\n CliEvaluator(options, outputStream = buffer).run()\n assertThat(buffer.toString(StandardCharsets.UTF_8))\n .isEqualTo(\n \"\"\"\n new Dynamic { bar = 1 }\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `evaluate output expression - custom toString()`() {\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n class Person {\n name: String\n\n function toString() = \"Person(\\(name))\"\n }\n person: Person = new { name = \"Frodo\" }\n \"\"\"\n .trimIndent(),\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(moduleUri), workingDir = tempDir),\n expression = \"person\",\n )\n val buffer = ByteArrayOutputStream()\n CliEvaluator(options, outputStream = buffer).run()\n assertThat(buffer.toString(StandardCharsets.UTF_8)).isEqualTo(\"Person(Frodo)\")\n }\n\n @Test\n fun `evaluate output expression - nested structure`() {\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n person {\n friend { name = \"Bilbo\" }\n }\n \"\"\"\n .trimIndent(),\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(moduleUri), workingDir = tempDir),\n expression = \"person\",\n )\n val buffer = ByteArrayOutputStream()\n CliEvaluator(options, outputStream = buffer).run()\n assertThat(buffer.toString(StandardCharsets.UTF_8))\n .isEqualTo(\"new Dynamic { friend { name = \\\"Bilbo\\\" } }\")\n }\n\n @Test\n fun `skip PklProject file`() {\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n res = 1\n \"\"\"\n .trimIndent(),\n )\n writePklFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package = throw(\"invalid project package\")\n \"\"\"\n .trimIndent(),\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(moduleUri), workingDir = tempDir, noProject = true)\n )\n val buffer = ByteArrayOutputStream()\n CliEvaluator(options, outputStream = buffer).run()\n assertThat(buffer.toString(StandardCharsets.UTF_8)).isEqualTo(\"res = 1\\n\")\n }\n\n @Test\n fun `settings from PklProject file`() {\n\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n res = read*(\"env:**\")\n \"\"\"\n .trimIndent(),\n )\n writePklFile(\n \"PklProject\",\n // language=Pkl\n \"\"\"\n amends \"pkl:Project\"\n \n evaluatorSettings {\n env {\n [\"foo\"] = \"foo\"\n [\"bar\"] = \"bar\"\n }\n }\n \"\"\"\n .trimIndent(),\n )\n val options =\n CliEvaluatorOptions(CliBaseOptions(sourceModules = listOf(moduleUri), workingDir = tempDir))\n val buffer = ByteArrayOutputStream()\n CliEvaluator(options, outputStream = buffer).run()\n assertThat(buffer.toString(StandardCharsets.UTF_8))\n .isEqualTo(\n \"\"\"\n res {\n [\"env:bar\"] = \"bar\"\n [\"env:foo\"] = \"foo\"\n }\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `noProxy settings from PklProject file`() {\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n res = read(\"https://localhost:${packageServer.port}/birds@0.5.0\").bytes.sha256\n \"\"\"\n .trimIndent(),\n )\n writePklFile(\n \"PklProject\",\n // language=Pkl\n \"\"\"\n amends \"pkl:Project\"\n \n evaluatorSettings {\n http {\n proxy {\n address = \"http://example.example\"\n noProxy {\n \"localhost:${packageServer.port}\"\n }\n }\n }\n }\n \"\"\"\n .trimIndent(),\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules = listOf(moduleUri),\n workingDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n )\n )\n val buffer = ByteArrayOutputStream()\n CliEvaluator(options, outputStream = buffer).run()\n assertThat(buffer.toString(StandardCharsets.UTF_8))\n .isEqualTo(\"res = \\\"b27206b80f4f227752b6f02143887f3ea41e554542cec38f7b572b987566c4de\\\"\\n\")\n }\n\n @Test\n fun `noProxy settings from settings file`() {\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n res = read(\"https://localhost:${packageServer.port}/birds@0.5.0\").bytes.sha256\n \"\"\"\n .trimIndent(),\n )\n val settingsFile =\n writePklFile(\n \"settings.pkl\",\n // language=Pkl\n \"\"\"\n amends \"pkl:settings\"\n \n http {\n proxy {\n address = \"http://example.example\"\n noProxy {\n \"localhost:${packageServer.port}\"\n }\n }\n }\n \"\"\"\n .trimIndent(),\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules = listOf(moduleUri),\n workingDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n settings = settingsFile,\n )\n )\n val buffer = ByteArrayOutputStream()\n CliEvaluator(options, outputStream = buffer).run()\n assertThat(buffer.toString(StandardCharsets.UTF_8))\n .isEqualTo(\"res = \\\"b27206b80f4f227752b6f02143887f3ea41e554542cec38f7b572b987566c4de\\\"\\n\")\n }\n\n @Test\n fun `setting noCache will skip writing to the cache dir`() {\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n import \"package://localhost:0/birds@0.5.0#/catalog/Swallow.pkl\"\n \n res = Swallow\n \"\"\"\n .trimIndent(),\n )\n val buffer = ByteArrayOutputStream()\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules = listOf(moduleUri),\n workingDir = tempDir,\n moduleCacheDir = tempDir,\n noCache = true,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = packageServer.port,\n )\n )\n CliEvaluator(options, outputStream = buffer).run()\n assertThat(buffer.toString(StandardCharsets.UTF_8))\n .isEqualTo(\n \"\"\"\n res {\n name = \"Swallow\"\n favoriteFruit {\n name = \"Apple\"\n }\n }\n \n \"\"\"\n .trimIndent()\n )\n assertThat(tempDir.resolve(\"package-2\")).doesNotExist()\n }\n\n @Test\n fun `gives decent error message if certificate file contains random text`() {\n val certsFile = tempDir.writeFile(\"random.pem\", \"RANDOM\")\n val err = assertThrows { evalModuleThatImportsPackage(certsFile) }\n assertThat(err)\n .hasMessageContaining(\"Error parsing CA certificate file `${certsFile.pathString}`:\")\n .hasMessageContaining(\"No certificate data found\")\n .hasMessageNotContainingAny(\"java.\", \"sun.\") // class names have been filtered out\n }\n\n @Test\n fun `gives decent error message if certificate file is empty`(@TempDir tempDir: Path) {\n val emptyCerts = tempDir.writeEmptyFile(\"empty.pem\")\n val err = assertThrows { evalModuleThatImportsPackage(emptyCerts) }\n assertThat(err).hasMessageContaining(\"CA certificate file `${emptyCerts.pathString}` is empty.\")\n }\n\n @Test\n fun `gives decent error message if certificate cannot be parsed`(@TempDir tempDir: Path) {\n val invalidCerts = FileTestUtils.writeCertificateWithMissingLines(tempDir)\n val err = assertThrows { evalModuleThatImportsPackage(invalidCerts) }\n assertThat(err)\n // no assert for detail message because it differs between JDK implementations\n .hasMessageContaining(\"Error parsing CA certificate file `${invalidCerts.pathString}`:\")\n .hasMessageNotContainingAny(\"java.\", \"sun.\") // class names have been filtered out\n }\n\n @Test\n fun `gives decent error message if CLI doesn't have the required CA certificate`() {\n val err = assertThrows { evalModuleThatImportsPackage(null, packageServer.port) }\n assertThat(err)\n .hasMessageContaining(\"Error during SSL handshake with host `localhost`:\")\n .hasMessageContaining(\"unable to find valid certification path to requested target\")\n .hasMessageNotContainingAny(\"java.\", \"sun.\") // class names have been filtered out\n }\n\n @Test\n fun `eval http module from proxy`(wwRuntimeInfo: WireMockRuntimeInfo) {\n stubFor(\n get(urlEqualTo(\"/bar.pkl\")).withHost(equalTo(\"not.a.valid.host\")).willReturn(ok(\"foo = 1\"))\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules = listOf(URI(\"http://not.a.valid.host/bar.pkl\")),\n httpProxy = URI(\"http://localhost:${wwRuntimeInfo.httpPort}\"),\n allowedModules = SecurityManagers.defaultAllowedModules + Pattern.compile(\"http:\"),\n )\n )\n val output = evalToConsole(options)\n assertThat(output).isEqualTo(\"foo = 1\\n\")\n }\n\n @Test\n fun `eval https -- no proxy`(wwRuntimeInfo: WireMockRuntimeInfo) {\n // pick an address on the local machine so we can be sure this test is not making any outbound\n // connections.\n val openPort = ServerSocket(0).use { it.localPort }\n val targetAddress = \"https://127.0.0.1:$openPort\"\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(\n // use loopback address to prevent test from making outbound http connection.\n sourceModules = listOf(URI(\"$targetAddress/foo.pkl\")),\n httpProxy = URI(wwRuntimeInfo.httpBaseUrl),\n httpNoProxy = listOf(\"*\"),\n allowedModules = SecurityManagers.defaultAllowedModules + Pattern.compile(\"http:\"),\n )\n )\n assertThatCode { evalToConsole(options) }\n .hasMessageContaining(\"I/O error loading module `$targetAddress/foo.pkl`\")\n }\n\n @Test\n @Disabled // TODO: figure out why this is failing.\n fun `eval package from proxy`(wwRuntimeInfo: WireMockRuntimeInfo) {\n stubFor(\n any(anyUrl()).willReturn(aResponse().proxiedFrom(\"https://localhost:${packageServer.port}\"))\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules = listOf(URI(\"package://localhost:1/birds@0.5.0#/catalog/Ostrich.pkl\")),\n noCache = true,\n httpProxy = URI(wwRuntimeInfo.httpBaseUrl),\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n allowedModules = SecurityManagers.defaultAllowedModules + Pattern.compile(\"http:\"),\n )\n )\n val output = evalToConsole(options)\n assertThat(output)\n .isEqualTo(\n \"\"\"\n name = \"Ostrich\"\n\n favoriteFruit {\n name = \"Orange\"\n }\n\n \"\"\"\n .trimIndent()\n )\n verify(getRequestedFor(urlEqualTo(\"birds@0.5.0\")))\n verify(getRequestedFor(urlEqualTo(\"fruit@1.0.5\")))\n }\n\n @Test\n fun `eval http module from proxy -- configured in settings`(\n @TempDir tempDir: Path,\n wwRuntimeInfo: WireMockRuntimeInfo,\n ) {\n val settingsModule =\n tempDir.writeFile(\n \"settings.pkl\",\n \"\"\"\n amends \"pkl:settings\"\n\n http {\n proxy {\n address = \"${wwRuntimeInfo.httpBaseUrl}\"\n }\n }\n \"\"\"\n .trimIndent(),\n )\n\n stubFor(\n get(urlEqualTo(\"/bar.pkl\")).withHost(equalTo(\"not.a.valid.host\")).willReturn(ok(\"foo = 1\"))\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules = listOf(URI(\"http://not.a.valid.host/bar.pkl\")),\n settings = settingsModule.toUri(),\n allowedModules = SecurityManagers.defaultAllowedModules + Pattern.compile(\"http:\"),\n )\n )\n val output = evalToConsole(options)\n assertThat(output).isEqualTo(\"foo = 1\\n\")\n }\n\n @Test\n fun `eval http module from proxy -- configured in PklProject`(\n @TempDir tempDir: Path,\n wwRuntimeInfo: WireMockRuntimeInfo,\n ) {\n tempDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n\n evaluatorSettings {\n http {\n proxy {\n address = \"${wwRuntimeInfo.httpBaseUrl}\"\n }\n }\n }\n \"\"\"\n .trimIndent(),\n )\n\n stubFor(\n get(urlEqualTo(\"/bar.pkl\")).withHost(equalTo(\"not.a.valid.host\")).willReturn(ok(\"foo = 1\"))\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules = listOf(URI(\"http://not.a.valid.host/bar.pkl\")),\n allowedModules = SecurityManagers.defaultAllowedModules + Pattern.compile(\"http:\"),\n projectDir = tempDir,\n )\n )\n val output = evalToConsole(options)\n assertThat(output).isEqualTo(\"foo = 1\\n\")\n }\n\n @Test\n fun `eval http module from proxy -- PklProject beats user settings`(\n @TempDir tempDir: Path,\n wwRuntimeInfo: WireMockRuntimeInfo,\n ) {\n val projectDir = tempDir.resolve(\"my-project\")\n projectDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n\n evaluatorSettings {\n http {\n proxy {\n address = \"${wwRuntimeInfo.httpBaseUrl}\"\n }\n }\n }\n \"\"\"\n .trimIndent(),\n )\n val homeDir = tempDir.resolve(\"my-home\")\n homeDir.writeFile(\n \"settings.pkl\",\n \"\"\"\n amends \"pkl:settings\"\n\n http {\n proxy {\n address = \"http://invalid.proxy.address\"\n }\n }\n \"\"\"\n .trimIndent(),\n )\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules = listOf(URI(\"http://not.a.valid.host/bar.pkl\")),\n allowedModules = SecurityManagers.defaultAllowedModules + Pattern.compile(\"http:\"),\n projectDir = projectDir,\n settings = homeDir.resolve(\"settings.pkl\").toUri(),\n )\n )\n stubFor(get(anyUrl()).willReturn(ok(\"result = 1\")))\n val output = evalToConsole(options)\n assertThat(output).isEqualTo(\"result = 1\\n\")\n }\n\n @Test\n fun `eval file with non-ASCII name`() {\n val tempDirUri = tempDir.toUri()\n val dir = tempDir.resolve(\"🤬\").createDirectory()\n val file =\n writePklFile(\n dir.resolve(\"日本語.pkl\").toString(),\n \"\"\"\n 日本語 = \"Japanese language\"\n readDir = read(\".\").text\n readDirFile = read(\"$tempDirUri🤬\").text\n readOne = read(\"日本語.pkl\").text.split(\"\\n\").first\n readOneFile = read(\"$tempDirUri🤬/日本語.pkl\").text.split(\"\\n\").first\n readGlob = read*(\"./日*.pkl\").keys\n readGlobFile = read*(\"$tempDirUri**/*.pkl\").keys.map((it) -> it.replaceAll(\"$tempDirUri\".replaceAll(\"///\", \"/\"), \"\"))\n importOne = import(\"日本語.pkl\").readOne\n importOneFile = import(\"$tempDirUri🤬/日本語.pkl\").日本語\n importGlob = import*(\"./日*.pkl\").keys\n importGlobFile = import*(\"$tempDirUri**/*.pkl\").keys.map((it) -> it.replaceAll(\"$tempDirUri\".replaceAll(\"///\", \"/\"), \"\"))\n \"\"\"\n .trimIndent(),\n )\n val output = evalToConsole(CliEvaluatorOptions(CliBaseOptions(sourceModules = listOf(file))))\n\n val tripleQuote = \"\\\"\\\"\\\"\"\n assertThat(output)\n .isEqualTo(\n \"\"\"\n 日本語 = \"Japanese language\"\n readDir = $tripleQuote\n 日本語.pkl\n \n $tripleQuote\n readDirFile = $tripleQuote\n 日本語.pkl\n \n $tripleQuote\n readOne = \"日本語 = \\\"Japanese language\\\"\"\n readOneFile = \"日本語 = \\\"Japanese language\\\"\"\n readGlob = Set(\"./日本語.pkl\")\n readGlobFile = Set(\"🤬/日本語.pkl\")\n importOne = \"日本語 = \\\"Japanese language\\\"\"\n importOneFile = \"Japanese language\"\n importGlob = Set(\"./日本語.pkl\")\n importGlobFile = Set(\"🤬/日本語.pkl\")\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n @DisabledOnOs(OS.WINDOWS)\n fun `multiple file output works with symlinked output directory`() {\n val realOutputDir = tempDir.resolve(\"real-output\").createDirectories()\n\n val symlinkOutputDir =\n Files.createSymbolicLink(tempDir.resolve(\"symlink-output\"), realOutputDir)\n\n val sourceFile =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n pigeon {\n name = \"Pigeon\"\n diet = \"Seeds\"\n }\n parrot {\n name = \"Parrot\"\n diet = \"Seeds\"\n }\n output {\n files {\n [\"pigeon.json\"] {\n value = pigeon\n renderer = new JsonRenderer {}\n }\n [\"birds/parrot.yaml\"] {\n value = parrot\n renderer = new YamlRenderer {}\n }\n }\n }\n \"\"\"\n .trimIndent(),\n )\n\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(sourceModules = listOf(sourceFile), workingDir = tempDir),\n multipleFileOutputPath = symlinkOutputDir.toString(),\n )\n\n CliEvaluator(options).run()\n\n checkOutputFile(\n realOutputDir.resolve(\"pigeon.json\"),\n \"pigeon.json\",\n \"\"\"\n {\n \"name\": \"Pigeon\",\n \"diet\": \"Seeds\"\n }\n \"\"\"\n .trimIndent(),\n )\n\n checkOutputFile(\n realOutputDir.resolve(\"birds/parrot.yaml\"),\n \"parrot.yaml\",\n \"\"\"\n name: Parrot\n diet: Seeds\n \"\"\"\n .trimIndent(),\n )\n\n checkOutputFile(\n symlinkOutputDir.resolve(\"pigeon.json\"),\n \"pigeon.json\",\n \"\"\"\n {\n \"name\": \"Pigeon\",\n \"diet\": \"Seeds\"\n }\n \"\"\"\n .trimIndent(),\n )\n\n checkOutputFile(\n symlinkOutputDir.resolve(\"birds/parrot.yaml\"),\n \"parrot.yaml\",\n \"\"\"\n name: Parrot\n diet: Seeds\n \"\"\"\n .trimIndent(),\n )\n }\n\n private fun evalModuleThatImportsPackage(certsFile: Path?, testPort: Int = -1) {\n val moduleUri =\n writePklFile(\n \"test.pkl\",\n \"\"\"\n import \"package://localhost:0/birds@0.5.0#/catalog/Swallow.pkl\"\n \n res = Swallow\n \"\"\",\n )\n\n val options =\n CliEvaluatorOptions(\n CliBaseOptions(\n sourceModules = listOf(moduleUri),\n caCertificates = buildList { if (certsFile != null) add(certsFile) },\n workingDir = tempDir,\n noCache = true,\n testPort = testPort,\n )\n )\n CliEvaluator(options).run()\n }\n\n private fun writePklFile(fileName: String, contents: String = defaultContents): URI {\n tempDir.resolve(fileName).createParentDirectories()\n return tempDir.resolve(fileName).writeString(contents).toUri()\n }\n\n private fun evalToFiles(options: CliEvaluatorOptions): List {\n val evaluator =\n CliEvaluator(\n options.copy(\n outputPath = options.outputPath ?: \"%{moduleDir}/%{moduleName}.%{outputFormat}\"\n )\n )\n\n evaluator.run()\n return evaluator.fileOutputPaths!!.values.toList()\n }\n\n private fun evalToConsole(options: CliEvaluatorOptions): String {\n val reader = ByteArrayInputStream(byteArrayOf())\n val writer = ByteArrayOutputStream()\n CliEvaluator(options, reader, writer).run()\n return writer.toString(StandardCharsets.UTF_8)\n }\n\n private fun checkOutputFile(file: Path, name: String, contents: String) {\n assertThat(file).isRegularFile.hasFileName(name)\n assertThat(file.readString().trim()).isEqualTo(contents.trim())\n }\n}\n" }, { "path": "pkl-cli/src/test/kotlin/org/pkl/cli/CliFormatterTest.kt", "content": "/*\n * Copyright © 2025-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.nio.file.Path\nimport kotlin.io.path.writeText\nimport org.assertj.core.api.Assertions.assertThat\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertThrows\nimport org.junit.jupiter.api.io.TempDir\nimport org.pkl.commons.cli.CliBugException\nimport org.pkl.commons.cli.CliException\nimport org.pkl.core.util.StringBuilderWriter\nimport org.pkl.formatter.GrammarVersion\n\nclass CliFormatterTest {\n @Test\n fun `no double newline when writing to stdout`(@TempDir tempDir: Path) {\n val file = tempDir.resolve(\"foo.pkl\").also { it.writeText(\"foo = 1\") }\n val sb = StringBuilder()\n val writer = StringBuilderWriter(sb)\n val cmd =\n CliFormatterCommand(\n listOf(file),\n GrammarVersion.latest(),\n overwrite = false,\n diffNameOnly = false,\n silent = false,\n consoleWriter = writer,\n )\n try {\n cmd.run()\n } catch (_: CliException) {}\n assertThat(sb.toString()).isEqualTo(\"foo = 1\\n\")\n }\n\n @Test\n fun `parse errors do not result in bug exceptions`(@TempDir tempDir: Path) {\n val file = tempDir.resolve(\"foo.pkl\").also { it.writeText(\"foo = \\\"/foo/\\\\\\${BAR}/baz\\\"\") }\n val sb = StringBuilder()\n val writer = StringBuilderWriter(sb)\n val cmd =\n CliFormatterCommand(\n listOf(file),\n GrammarVersion.latest(),\n overwrite = false,\n diffNameOnly = false,\n silent = false,\n consoleWriter = writer,\n )\n val exc = assertThrows { cmd.run() }\n assertThat(exc).isNotInstanceOf(CliBugException::class.java)\n }\n}\n" }, { "path": "pkl-cli/src/test/kotlin/org/pkl/cli/CliImportAnalyzerTest.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.net.URI\nimport java.nio.file.Path\nimport org.assertj.core.api.Assertions.assertThat\nimport org.assertj.core.api.Assertions.assertThatCode\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.io.TempDir\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.writeString\nimport org.pkl.core.OutputFormat\nimport org.pkl.core.util.StringBuilderWriter\n\nclass CliImportAnalyzerTest {\n @Test\n fun `write to console writer`(@TempDir tempDir: Path) {\n val file = tempDir.resolve(\"test.pkl\").writeString(\"import \\\"bar.pkl\\\"\")\n val otherFile = tempDir.resolve(\"bar.pkl\").writeString(\"\")\n val baseOptions = CliBaseOptions(sourceModules = listOf(file.toUri()))\n val sb = StringBuilder()\n val analyzer = CliImportAnalyzer(CliImportAnalyzerOptions(baseOptions), StringBuilderWriter(sb))\n analyzer.run()\n assertThat(sb.toString())\n .isEqualTo(\n \"\"\"\n imports {\n [\"${otherFile.toUri()}\"] {}\n [\"${file.toUri()}\"] {\n new {\n uri = \"${otherFile.toUri()}\"\n }\n }\n }\n resolvedImports {\n [\"${otherFile.toUri()}\"] = \"${otherFile.toRealPath().toUri()}\"\n [\"${file.toUri()}\"] = \"${file.toRealPath().toUri()}\"\n }\n\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `different output format`(@TempDir tempDir: Path) {\n val file = tempDir.resolve(\"test.pkl\").writeString(\"import \\\"bar.pkl\\\"\")\n val otherFile = tempDir.resolve(\"bar.pkl\").writeString(\"\")\n val baseOptions = CliBaseOptions(sourceModules = listOf(file.toUri()))\n val sb = StringBuilder()\n val analyzer =\n CliImportAnalyzer(\n CliImportAnalyzerOptions(baseOptions, outputFormat = OutputFormat.JSON.toString()),\n StringBuilderWriter(sb),\n )\n analyzer.run()\n assertThat(sb.toString())\n .isEqualTo(\n \"\"\"\n {\n \"imports\": {\n \"${otherFile.toUri()}\": [],\n \"${file.toUri()}\": [\n {\n \"uri\": \"${otherFile.toUri()}\"\n }\n ]\n },\n \"resolvedImports\": {\n \"${otherFile.toUri()}\": \"${otherFile.toRealPath().toUri()}\",\n \"${file.toUri()}\": \"${file.toRealPath().toUri()}\"\n }\n }\n\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `write to output file`(@TempDir tempDir: Path) {\n val file = tempDir.resolve(\"test.pkl\").writeString(\"import \\\"bar.pkl\\\"\")\n val otherFile = tempDir.resolve(\"bar.pkl\").writeString(\"\")\n val outputPath = tempDir.resolve(\"imports.pcf\")\n val baseOptions = CliBaseOptions(sourceModules = listOf(file.toUri()))\n val analyzer = CliImportAnalyzer(CliImportAnalyzerOptions(baseOptions, outputPath = outputPath))\n analyzer.run()\n assertThat(outputPath)\n .hasContent(\n \"\"\"\n imports {\n [\"${otherFile.toUri()}\"] {}\n [\"${file.toUri()}\"] {\n new {\n uri = \"${otherFile.toUri()}\"\n }\n }\n }\n resolvedImports {\n [\"${otherFile.toUri()}\"] = \"${otherFile.toRealPath().toUri()}\"\n [\"${file.toUri()}\"] = \"${file.toRealPath().toUri()}\"\n }\n\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `invalid syntax in module`(@TempDir tempDir: Path) {\n val file = tempDir.resolve(\"test.pkl\").writeString(\"foo = bar(]\")\n assertThatCode {\n CliImportAnalyzer(\n CliImportAnalyzerOptions(\n CliBaseOptions(sourceModules = listOf(file.toUri()), settings = URI(\"pkl:settings\"))\n )\n )\n .run()\n }\n .hasMessageContaining(\n \"\"\"\n –– Pkl Error ––\n Found a syntax error when parsing module `${file.toUri()}`.\n \"\"\"\n .trimIndent()\n )\n }\n}\n" }, { "path": "pkl-cli/src/test/kotlin/org/pkl/cli/CliMainTest.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport com.github.ajalt.clikt.core.BadParameterValue\nimport com.github.ajalt.clikt.core.CliktError\nimport com.github.ajalt.clikt.core.parse\nimport java.nio.file.Path\nimport kotlin.io.path.createDirectory\nimport kotlin.io.path.createSymbolicLinkPointingTo\nimport org.assertj.core.api.Assertions.assertThat\nimport org.assertj.core.api.AssertionsForClassTypes.assertThatCode\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertThrows\nimport org.junit.jupiter.api.condition.DisabledOnOs\nimport org.junit.jupiter.api.condition.OS\nimport org.junit.jupiter.api.io.TempDir\nimport org.pkl.cli.commands.EvalCommand\nimport org.pkl.cli.commands.RootCommand\nimport org.pkl.commons.writeString\nimport org.pkl.core.Release\n\nclass CliMainTest {\n private val rootCmd = RootCommand()\n\n @Test\n fun `duplicate CLI option produces meaningful error message`(@TempDir tempDir: Path) {\n val inputFile = tempDir.resolve(\"test.pkl\").writeString(\"\").toString()\n\n assertThatCode {\n rootCmd.parse(\n arrayOf(\"eval\", \"--output-path\", \"path1\", \"--output-path\", \"path2\", inputFile)\n )\n }\n .hasMessage(\"Option cannot be repeated\")\n\n assertThatCode {\n rootCmd.parse(arrayOf(\"eval\", \"-o\", \"path1\", \"--output-path\", \"path2\", inputFile))\n }\n .hasMessage(\"Option cannot be repeated\")\n }\n\n @Test\n fun `eval requires at least one file`() {\n assertThatCode { rootCmd.parse(arrayOf(\"eval\")) }\n .isInstanceOf(CliktError::class.java)\n .extracting(\"paramName\")\n .isEqualTo(\"modules\")\n }\n\n // Can't reliably create symlinks on Windows.\n // Might get errors like \"A required privilege is not held by the client\".\n @Test\n @DisabledOnOs(OS.WINDOWS)\n fun `output to symlinked directory works`(@TempDir tempDir: Path) {\n val code =\n \"\"\"\n x = 3\n \n output {\n value = x\n renderer = new JsonRenderer {}\n }\n \"\"\"\n .trimIndent()\n val inputFile = tempDir.resolve(\"test.pkl\").writeString(code).toString()\n val outputFile = makeSymdir(tempDir, \"out\", \"linkOut\").resolve(\"test.pkl\").toString()\n\n assertThatCode { rootCmd.parse(arrayOf(\"eval\", inputFile, \"-o\", outputFile)) }\n .doesNotThrowAnyException()\n }\n\n @Test\n fun `cannot have multiple output with -o or -x`(@TempDir tempDir: Path) {\n val testIn = makeInput(tempDir)\n val testOut = tempDir.resolve(\"test\").toString()\n val error = \"\"\"Option is mutually exclusive with -o, --output-path and -x, --expression.\"\"\"\n\n assertThatCode { rootCmd.parse(arrayOf(\"eval\", \"-m\", testOut, \"-x\", \"x\", testIn)) }\n .hasMessage(error)\n\n assertThatCode { rootCmd.parse(arrayOf(\"eval\", \"-m\", testOut, \"-o\", \"/tmp/test\", testIn)) }\n .hasMessage(error)\n }\n\n @Test\n fun `showing version works`() {\n assertThatCode { rootCmd.parse(arrayOf(\"--version\")) }.hasMessage(Release.current().versionInfo)\n }\n\n @Test\n fun `file paths get parsed into URIs`(@TempDir tempDir: Path) {\n val cmd = RootCommand()\n cmd.parse(arrayOf(\"eval\", makeInput(tempDir, \"my file.txt\")))\n\n val evalCmd = cmd.registeredSubcommands().filterIsInstance().first()\n val modules = evalCmd.baseOptions.baseOptions(evalCmd.modules).normalizedSourceModules\n assertThat(modules).hasSize(1)\n assertThat(modules[0].path).endsWith(\"my file.txt\")\n }\n\n @Test\n fun `invalid URIs are not accepted`() {\n val ex = assertThrows { rootCmd.parse(arrayOf(\"eval\", \"file:my file.txt\")) }\n\n assertThat(ex.message).contains(\"URI `file:my file.txt` has invalid syntax\")\n }\n\n @Test\n fun `invalid rewrites -- non-HTTP URI`() {\n val ex =\n assertThrows {\n rootCmd.parse(arrayOf(\"eval\", \"--http-rewrite\", \"foo=bar\", \"mymodule.pkl\"))\n }\n assertThat(ex.message)\n .contains(\"Rewrite rule must start with 'http://' or 'https://', but was 'foo'\")\n }\n\n @Test\n fun `invalid rewrites -- invalid URI`() {\n val ex =\n assertThrows {\n rootCmd.parse(arrayOf(\"eval\", \"--http-rewrite\", \"https://foo bar=baz\", \"mymodule.pkl\"))\n }\n assertThat(ex.message).contains(\"Rewrite target `https://foo bar` has invalid syntax\")\n }\n\n @Test\n fun `invalid rewrites -- doesn't end with slash`() {\n val ex =\n assertThrows {\n rootCmd.parse(\n arrayOf(\"eval\", \"--http-rewrite\", \"http://foo.com=https://bar.com\", \"mymodule.pkl\")\n )\n }\n assertThat(ex.message).contains(\"Rewrite rule must end with '/', but was 'http://foo.com'\")\n }\n\n @Test\n fun `missing --http-no-proxy flag is null`(@TempDir tempDir: Path) {\n val inputFile = tempDir.resolve(\"test.pkl\").writeString(\"\").toString()\n val command = EvalCommand()\n command.parse(arrayOf(inputFile))\n assertThat(command.baseOptions.noProxy).isNull()\n }\n\n private fun makeInput(tempDir: Path, fileName: String = \"test.pkl\"): String {\n val code = \"x = 1\"\n return tempDir.resolve(fileName).writeString(code).toString()\n }\n\n private fun makeSymdir(baseDir: Path, name: String, linkName: String): Path {\n val dir = baseDir.resolve(name)\n val link = baseDir.resolve(linkName)\n dir.createDirectory()\n link.createSymbolicLinkPointingTo(dir)\n return link\n }\n}\n" }, { "path": "pkl-cli/src/test/kotlin/org/pkl/cli/CliPackageDownloaderTest.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.nio.file.Path\nimport org.assertj.core.api.Assertions.assertThat\nimport org.assertj.core.api.Assertions.assertThatCode\nimport org.junit.jupiter.api.AfterAll\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.io.TempDir\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.test.FileTestUtils\nimport org.pkl.commons.test.PackageServer\nimport org.pkl.core.packages.PackageUri\n\nclass CliPackageDownloaderTest {\n companion object {\n private val server = PackageServer()\n\n @AfterAll\n @JvmStatic\n fun afterAll() {\n server.close()\n }\n }\n\n @Test\n fun `download packages`(@TempDir tempDir: Path) {\n val cmd =\n CliPackageDownloader(\n baseOptions =\n CliBaseOptions(\n moduleCacheDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = server.port,\n ),\n packageUris =\n listOf(\n PackageUri(\"package://localhost:0/birds@0.5.0\"),\n PackageUri(\"package://localhost:0/fruit@1.0.5\"),\n PackageUri(\"package://localhost:0/fruit@1.1.0\"),\n ),\n noTransitive = true,\n )\n cmd.run()\n assertThat(tempDir.resolve(\"package-2/localhost(3a)0/birds@0.5.0/birds@0.5.0.zip\")).exists()\n assertThat(tempDir.resolve(\"package-2/localhost(3a)0/birds@0.5.0/birds@0.5.0.json\")).exists()\n assertThat(tempDir.resolve(\"package-2/localhost(3a)0/fruit@1.0.5/fruit@1.0.5.zip\")).exists()\n assertThat(tempDir.resolve(\"package-2/localhost(3a)0/fruit@1.0.5/fruit@1.0.5.json\")).exists()\n assertThat(tempDir.resolve(\"package-2/localhost(3a)0/fruit@1.1.0/fruit@1.1.0.zip\")).exists()\n assertThat(tempDir.resolve(\"package-2/localhost(3a)0/fruit@1.1.0/fruit@1.1.0.json\")).exists()\n }\n\n @Test\n fun `download packages with cache dir set by project`(@TempDir tempDir: Path) {\n tempDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n evaluatorSettings {\n moduleCacheDir = \".my-cache\"\n }\n \"\"\"\n .trimIndent(),\n )\n\n val cmd =\n CliPackageDownloader(\n baseOptions =\n CliBaseOptions(\n workingDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = server.port,\n ),\n packageUris = listOf(PackageUri(\"package://localhost:0/birds@0.5.0\")),\n noTransitive = true,\n )\n cmd.run()\n assertThat(tempDir.resolve(\".my-cache/package-2/localhost(3a)0/birds@0.5.0/birds@0.5.0.zip\"))\n .exists()\n assertThat(tempDir.resolve(\".my-cache/package-2/localhost(3a)0/birds@0.5.0/birds@0.5.0.json\"))\n .exists()\n }\n\n @Test\n fun `download package while specifying checksum`(@TempDir tempDir: Path) {\n val cmd =\n CliPackageDownloader(\n baseOptions =\n CliBaseOptions(\n moduleCacheDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = server.port,\n ),\n packageUris =\n listOf(\n PackageUri(\"package://localhost:0/birds@0.5.0::sha256:${PackageServer.BIRDS_SHA}\")\n ),\n noTransitive = true,\n )\n cmd.run()\n assertThat(tempDir.resolve(\"package-2/localhost(3a)0/birds@0.5.0/birds@0.5.0.zip\")).exists()\n assertThat(tempDir.resolve(\"package-2/localhost(3a)0/birds@0.5.0/birds@0.5.0.json\")).exists()\n }\n\n @Test\n fun `download package with invalid checksum`(@TempDir tempDir: Path) {\n val cmd =\n CliPackageDownloader(\n baseOptions =\n CliBaseOptions(\n moduleCacheDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = server.port,\n ),\n packageUris =\n listOf(\n PackageUri(\"package://localhost:0/birds@0.5.0::sha256:intentionallyBogusChecksum\")\n ),\n noTransitive = true,\n )\n assertThatCode { cmd.run() }\n .hasMessage(\n \"\"\"\n Cannot download package `package://localhost:0/birds@0.5.0` because the computed checksum for package metadata does not match the expected checksum.\n\n Computed checksum: \"${PackageServer.BIRDS_SHA}\"\n Expected checksum: \"intentionallyBogusChecksum\"\n Asset URL: \"https://localhost:0/birds@0.5.0\"\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `disabling caching is an error`(@TempDir tempDir: Path) {\n val cmd =\n CliPackageDownloader(\n baseOptions = CliBaseOptions(workingDir = tempDir, noCache = true),\n packageUris = listOf(PackageUri(\"package://localhost:0/birds@0.5.0\")),\n noTransitive = true,\n )\n assertThatCode { cmd.run() }\n .hasMessage(\"Cannot download packages because no cache directory is specified.\")\n }\n\n @Test\n fun `download packages with bad checksum`(@TempDir tempDir: Path) {\n val cmd =\n CliPackageDownloader(\n baseOptions =\n CliBaseOptions(\n moduleCacheDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = server.port,\n ),\n packageUris = listOf(PackageUri(\"package://localhost:0/badChecksum@1.0.0\")),\n noTransitive = true,\n )\n assertThatCode { cmd.run() }\n .hasMessageStartingWith(\n \"Cannot download package `package://localhost:0/badChecksum@1.0.0` because the computed checksum does not match the expected checksum.\"\n )\n }\n\n @Test\n fun `download multiple failing packages`(@TempDir tempDir: Path) {\n val cmd =\n CliPackageDownloader(\n baseOptions =\n CliBaseOptions(\n moduleCacheDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = server.port,\n ),\n packageUris =\n listOf(\n PackageUri(\"package://localhost:0/badChecksum@1.0.0\"),\n PackageUri(\"package://bogus.domain/notAPackage@1.0.0\"),\n ),\n noTransitive = true,\n )\n assertThatCode { cmd.run() }\n .hasMessage(\n \"\"\"\n Failed to download some packages.\n\n Failed to download package://localhost:0/badChecksum@1.0.0 because:\n Cannot download package `package://localhost:0/badChecksum@1.0.0` because the computed checksum does not match the expected checksum.\n\n Computed checksum: \"a6bf858cdd1c09da475c2abe50525902580910ee5cc1ff624999170591bf8f69\"\n Expected checksum: \"intentionally bogus checksum\"\n Asset URL: \"https://localhost:0/badChecksum@1.0.0/badChecksum@1.0.0.zip\"\n\n Failed to download package://bogus.domain/notAPackage@1.0.0 because:\n Exception when making request `GET https://bogus.domain/notAPackage@1.0.0`:\n Error connecting to host `bogus.domain`.\n\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `download package, including transitive dependencies`(@TempDir tempDir: Path) {\n CliPackageDownloader(\n baseOptions =\n CliBaseOptions(\n moduleCacheDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = server.port,\n ),\n packageUris = listOf(PackageUri(\"package://localhost:0/birds@0.5.0\")),\n noTransitive = false,\n )\n .run()\n assertThat(tempDir.resolve(\"package-2/localhost(3a)0/birds@0.5.0/birds@0.5.0.zip\")).exists()\n assertThat(tempDir.resolve(\"package-2/localhost(3a)0/birds@0.5.0/birds@0.5.0.json\")).exists()\n assertThat(tempDir.resolve(\"package-2/localhost(3a)0/fruit@1.0.5/fruit@1.0.5.zip\")).exists()\n assertThat(tempDir.resolve(\"package-2/localhost(3a)0/fruit@1.0.5/fruit@1.0.5.json\")).exists()\n }\n}\n" }, { "path": "pkl-cli/src/test/kotlin/org/pkl/cli/CliProjectPackagerTest.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.io.File\nimport java.io.StringWriter\nimport java.net.URI\nimport java.nio.file.FileSystems\nimport java.nio.file.Files\nimport java.nio.file.Path\nimport java.util.stream.Collectors\nimport kotlin.io.path.createDirectories\nimport org.assertj.core.api.Assertions.assertThat\nimport org.assertj.core.api.Assertions.assertThatCode\nimport org.junit.jupiter.api.AfterAll\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertThrows\nimport org.junit.jupiter.api.condition.DisabledOnOs\nimport org.junit.jupiter.api.condition.OS\nimport org.junit.jupiter.api.io.TempDir\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.CliException\nimport org.pkl.commons.cli.CliTestOptions\nimport org.pkl.commons.readString\nimport org.pkl.commons.test.FileTestUtils\nimport org.pkl.commons.test.PackageServer\nimport org.pkl.commons.writeString\nimport org.pkl.core.util.IoUtils\n\nclass CliProjectPackagerTest {\n companion object {\n private val packageServer = PackageServer()\n\n @AfterAll\n @JvmStatic\n fun afterAll() {\n packageServer.close()\n }\n }\n\n @Test\n fun `missing PklProject when inferring a project dir`(@TempDir tempDir: Path) {\n val packager =\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n )\n val err = assertThrows { packager.run() }\n assertThat(err).hasMessageStartingWith(\"No project visible to the working directory.\")\n }\n\n @Test\n fun `missing PklProject when explicit dir is provided`(@TempDir tempDir: Path) {\n val packager =\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(tempDir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n )\n val err = assertThrows { packager.run() }\n assertThat(err).hasMessageStartingWith(\"Directory $tempDir does not contain a PklProject file.\")\n }\n\n @Test\n fun `PklProject missing package section`(@TempDir tempDir: Path) {\n tempDir\n .resolve(\"PklProject\")\n .writeString(\n \"\"\"\n amends \"pkl:Project\"\n \"\"\"\n .trimIndent()\n )\n val packager =\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(tempDir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n )\n val err = assertThrows { packager.run() }\n assertThat(err)\n .hasMessageStartingWith(\"No package was declared in project `${tempDir.toUri()}PklProject`.\")\n }\n\n @Test\n fun `failing apiTests`(@TempDir tempDir: Path) {\n tempDir.writeFile(\n \"myTest.pkl\",\n \"\"\"\n amends \"pkl:test\"\n \n facts {\n [\"1 == 2\"] {\n 1 == 2\n }\n }\n \"\"\"\n .trimIndent(),\n )\n tempDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"mypackage\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/mypackage\"\n packageZipUrl = \"https://foo.com\"\n apiTests { \"myTest.pkl\" }\n }\n \"\"\"\n .trimIndent(),\n )\n val buffer = StringWriter()\n val packager =\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(tempDir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n consoleWriter = buffer,\n )\n val err = assertThrows { packager.run() }\n assertThat(err).hasMessageContaining(\"because its API tests are failing\")\n assertThat(buffer.toString()).contains(\"1 == 2\")\n }\n\n @Test\n fun `passing apiTests`(@TempDir tempDir: Path) {\n tempDir\n .resolve(\"myTest.pkl\")\n .writeString(\n \"\"\"\n amends \"pkl:test\"\n \n facts {\n [\"1 == 1\"] {\n 1 == 1\n }\n }\n \"\"\"\n .trimIndent()\n )\n tempDir\n .resolve(\"PklProject\")\n .writeString(\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"mypackage\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/mypackage\"\n packageZipUrl = \"https://foo.com\"\n apiTests { \"myTest.pkl\" }\n }\n \"\"\"\n .trimIndent()\n )\n val buffer = StringWriter()\n val packager =\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(tempDir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n consoleWriter = buffer,\n )\n packager.run()\n }\n\n @Test\n fun `apiTests that import dependencies`(@TempDir tempDir: Path) {\n val cacheDir = tempDir.resolve(\"cache\")\n val projectDir = tempDir.resolve(\"myProject\").createDirectories()\n PackageServer.populateCacheDir(cacheDir)\n projectDir\n .resolve(\"myTest.pkl\")\n .writeString(\n \"\"\"\n amends \"pkl:test\"\n import \"@birds/Bird.pkl\"\n \n examples {\n [\"Bird\"] {\n new Bird { name = \"Finch\"; favoriteFruit { name = \"Tangerine\" } }\n }\n }\n \"\"\"\n .trimIndent()\n )\n projectDir\n .resolve(\"myTest.pkl-expected.pcf\")\n .writeString(\n \"\"\"\n examples {\n [\"Bird\"] {\n new {\n name = \"Finch\"\n favoriteFruit {\n name = \"Tangerine\"\n }\n }\n }\n }\n \n \"\"\"\n .trimIndent()\n )\n projectDir\n .resolve(\"PklProject\")\n .writeString(\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"mypackage\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/mypackage\"\n packageZipUrl = \"https://foo.com\"\n apiTests { \"myTest.pkl\" }\n }\n\n dependencies {\n [\"birds\"] {\n uri = \"package://localhost:0/birds@0.5.0\"\n }\n }\n \"\"\"\n .trimIndent()\n )\n projectDir\n .resolve(\"PklProject.deps.json\")\n .writeString(\n \"\"\"\n {\n \"schemaVersion\": 1,\n \"resolvedDependencies\": {\n \"package://localhost:0/birds@0\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/birds@0.5.0\",\n \"checksums\": {\n \"sha256\": \"04eec465b217fb9779489525d26e9b587e5e47ff4d584c7673a450109715bc31\"\n }\n },\n \"package://localhost:0/fruit@1\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/fruit@1.0.5\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.FRUIT_SHA}\"\n }\n }\n }\n }\n \"\"\"\n .trimIndent()\n )\n val buffer = StringWriter()\n val packager =\n CliProjectPackager(\n CliBaseOptions(workingDir = projectDir, moduleCacheDir = cacheDir),\n listOf(projectDir),\n CliTestOptions(),\n \".out\",\n skipPublishCheck = true,\n consoleWriter = buffer,\n )\n packager.run()\n }\n\n @Test\n fun `generate package`(@TempDir tempDir: Path) {\n val fooPkl =\n tempDir.writeFile(\n \"a/b/foo.pkl\",\n \"\"\"\n module foo\n \n name: String\n \"\"\"\n .trimIndent(),\n )\n\n val fooTxt =\n tempDir.writeFile(\n \"c/d/foo.txt\",\n \"\"\"\n foo\n bar\n baz\n \"\"\"\n .trimIndent(),\n )\n\n tempDir\n .resolve(\"PklProject\")\n .writeString(\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"mypackage\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/mypackage\"\n packageZipUrl = \"https://foo.com\"\n }\n \"\"\"\n .trimIndent()\n )\n val packager =\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(tempDir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n consoleWriter = StringWriter(),\n )\n packager.run()\n val expectedMetadata = tempDir.resolve(\".out/mypackage@1.0.0/mypackage@1.0.0\")\n val expectedMetadataChecksum = tempDir.resolve(\".out/mypackage@1.0.0/mypackage@1.0.0.sha256\")\n val expectedArchive = tempDir.resolve(\".out/mypackage@1.0.0/mypackage@1.0.0.zip\")\n val expectedArchiveChecksum = tempDir.resolve(\".out/mypackage@1.0.0/mypackage@1.0.0.zip.sha256\")\n assertThat(expectedMetadata).exists()\n assertThat(expectedMetadata)\n .hasContent(\n \"\"\"\n {\n \"name\": \"mypackage\",\n \"packageUri\": \"package://example.com/mypackage@1.0.0\",\n \"version\": \"1.0.0\",\n \"packageZipUrl\": \"https://foo.com\",\n \"packageZipChecksums\": {\n \"sha256\": \"e83b67722ea17ba41717ce6e99ae8ee02d66df6294bd319ce403075b1071c3e0\"\n },\n \"dependencies\": {},\n \"authors\": []\n }\n \"\"\"\n .trimIndent()\n )\n assertThat(expectedArchive).exists()\n assertThat(expectedArchive.zipFilePaths())\n .hasSameElementsAs(listOf(\"/\", \"/c\", \"/c/d\", \"/c/d/foo.txt\", \"/a\", \"/a/b\", \"/a/b/foo.pkl\"))\n assertThat(expectedMetadataChecksum)\n .hasContent(\"72ab32b27393bde5f316b00f184faae919378e4d7643872c605f681b14b647bf\")\n assertThat(expectedArchiveChecksum)\n .hasContent(\"e83b67722ea17ba41717ce6e99ae8ee02d66df6294bd319ce403075b1071c3e0\")\n FileSystems.newFileSystem(URI(\"jar:\" + expectedArchive.toUri()), mutableMapOf())\n .use { fs ->\n assertThat(fs.getPath(\"a/b/foo.pkl\")).hasSameTextualContentAs(fooPkl)\n assertThat(fs.getPath(\"c/d/foo.txt\")).hasSameTextualContentAs(fooTxt)\n }\n }\n\n @Test\n fun `generate package with excludes`(@TempDir tempDir: Path) {\n tempDir.apply {\n writeEmptyFile(\"a/b/c/d.bin\")\n writeEmptyFile(\"input/foo/bar.txt\")\n writeEmptyFile(\"z.bin\")\n writeEmptyFile(\"main.pkl\")\n writeEmptyFile(\"main.test.pkl\")\n writeEmptyFile(\"child/main.pkl\")\n writeEmptyFile(\"child/main.test.pkl\")\n writeEmptyFile(\"examples/Workflow.pkl\")\n writeEmptyFile(\"examples/Ex1.pkl\")\n writeEmptyFile(\"tests/Test1.pkl\")\n writeEmptyFile(\"tests/integration/TestIng1.pkl\")\n }\n\n tempDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"mypackage\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/mypackage\"\n packageZipUrl = \"https://foo.com\"\n exclude {\n \"*.bin\"\n \"child/main.pkl\"\n \"*.test.pkl\"\n \"examples/Ex1.pkl\"\n \"tests/**\"\n }\n }\n \"\"\"\n .trimIndent(),\n )\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(tempDir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n consoleWriter = StringWriter(),\n )\n .run()\n val expectedArchive = tempDir.resolve(\".out/mypackage@1.0.0/mypackage@1.0.0.zip\")\n assertThat(expectedArchive.zipFilePaths())\n .hasSameElementsAs(\n listOf(\n \"/\",\n \"/examples\",\n \"/examples/Workflow.pkl\",\n \"/input\",\n \"/input/foo\",\n \"/input/foo/bar.txt\",\n \"/main.pkl\",\n )\n )\n }\n\n @Test\n fun `generate packages with local dependencies`(@TempDir tempDir: Path) {\n val projectDir = tempDir.resolve(\"project\")\n val project2Dir = tempDir.resolve(\"project2\")\n projectDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"mypackage\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/mypackage\"\n packageZipUrl = \"https://foo.com\"\n }\n \n dependencies {\n [\"birds\"] {\n uri = \"package://localhost:0/birds@0.5.0\"\n }\n [\"project2\"] = import(\"../project2/PklProject\")\n }\n \"\"\"\n .trimIndent(),\n )\n projectDir.writeFile(\n \"PklProject.deps.json\",\n \"\"\"\n {\n \"schemaVersion\": 1,\n \"resolvedDependencies\": {\n \"package://localhost:0/birds@0\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/birds@0.5.0\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.BIRDS_SHA}\"\n }\n },\n \"package://localhost:0/project2@5\": {\n \"type\": \"local\",\n \"uri\": \"projectpackage://localhost:0/project2@5.0.0\",\n \"path\": \"../project2\"\n }\n }\n }\n \"\"\"\n .trimIndent(),\n )\n\n project2Dir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"project2\"\n baseUri = \"package://localhost:0/project2\"\n version = \"5.0.0\"\n packageZipUrl = \"https://foo.com/project2.zip\"\n }\n \"\"\"\n .trimIndent(),\n )\n project2Dir.writeFile(\n \"PklProject.deps.json\",\n \"\"\"\n {\n \"schemaVersion\": 1,\n \"resolvedDependencies\": {}\n }\n \"\"\"\n .trimIndent(),\n )\n\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(projectDir, project2Dir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n consoleWriter = StringWriter(),\n )\n .run()\n val expectedMetadata = tempDir.resolve(\".out/mypackage@1.0.0/mypackage@1.0.0\")\n assertThat(expectedMetadata).exists()\n assertThat(expectedMetadata)\n .hasContent(\n \"\"\"\n {\n \"name\": \"mypackage\",\n \"packageUri\": \"package://example.com/mypackage@1.0.0\",\n \"version\": \"1.0.0\",\n \"packageZipUrl\": \"https://foo.com\",\n \"packageZipChecksums\": {\n \"sha256\": \"8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85\"\n },\n \"dependencies\": {\n \"birds\": {\n \"uri\": \"package://localhost:0/birds@0.5.0\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.BIRDS_SHA}\"\n }\n },\n \"project2\": {\n \"uri\": \"package://localhost:0/project2@5.0.0\",\n \"checksums\": {\n \"sha256\": \"981787869571330b2f609a94a5912466990ce00e3fa94e7f290c2f99a6d5e5ed\"\n }\n }\n },\n \"authors\": []\n }\n \"\"\"\n .trimIndent()\n )\n val project2Metadata = tempDir.resolve(\".out/project2@5.0.0/project2@5.0.0\")\n assertThat(project2Metadata).exists()\n assertThat(project2Metadata.readString())\n .isEqualTo(\n \"\"\"\n {\n \"name\": \"project2\",\n \"packageUri\": \"package://localhost:0/project2@5.0.0\",\n \"version\": \"5.0.0\",\n \"packageZipUrl\": \"https://foo.com/project2.zip\",\n \"packageZipChecksums\": {\n \"sha256\": \"8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85\"\n },\n \"dependencies\": {},\n \"authors\": []\n }\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `generate package with local dependencies fails if local dep is not included for packaging`(\n @TempDir tempDir: Path\n ) {\n val projectDir = tempDir.resolve(\"project\")\n val project2Dir = tempDir.resolve(\"project2\")\n projectDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"mypackage\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/mypackage\"\n packageZipUrl = \"https://foo.com\"\n }\n \n dependencies {\n [\"birds\"] {\n uri = \"package://localhost:0/birds@0.5.0\"\n }\n [\"project2\"] = import(\"../project2/PklProject\")\n }\n \"\"\"\n .trimIndent(),\n )\n projectDir.writeFile(\n \"PklProject.deps.json\",\n \"\"\"\n {\n \"schemaVersion\": 1,\n \"resolvedDependencies\": {\n \"package://localhost:0/birds@0\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/birds@0.5.0\",\n \"checksums\": {\n \"sha256\": \"0a5ad2dc13f06f73f96ba94e8d01d48252bc934e2de71a837620ca0fef8a7453\"\n }\n },\n \"package://localhost:0/project2@5\": {\n \"type\": \"local\",\n \"uri\": \"projectpackage://localhost:0/project2@5.0.0\",\n \"path\": \"../project2\"\n }\n }\n }\n \"\"\"\n .trimIndent(),\n )\n\n project2Dir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"project2\"\n baseUri = \"package://localhost:0/project2\"\n version = \"5.0.0\"\n packageZipUrl = \"https://foo.com/project2.zip\"\n }\n \"\"\"\n .trimIndent(),\n )\n project2Dir.writeFile(\n \"PklProject.deps.json\",\n \"\"\"\n {\n \"schemaVersion\": 1,\n \"resolvedDependencies\": {}\n }\n \"\"\"\n .trimIndent(),\n )\n assertThatCode {\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(projectDir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n consoleWriter = StringWriter(),\n )\n .run()\n }\n .hasMessageContaining(\"which is not included for packaging\")\n }\n\n @Test\n fun `import path verification -- relative path outside project dir`(@TempDir tempDir: Path) {\n tempDir.writeFile(\n \"main.pkl\",\n \"\"\"\n import \"../foo.pkl\"\n \n res = foo\n \"\"\"\n .trimIndent(),\n )\n tempDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"mypackage\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/mypackage\"\n packageZipUrl = \"https://foo.com\"\n }\n \"\"\"\n .trimIndent(),\n )\n val e =\n assertThrows {\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(tempDir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n consoleWriter = StringWriter(),\n )\n .run()\n }\n assertThat(e.message)\n .startsWith(\n \"\"\"\n –– Pkl Error ––\n Path `../foo.pkl` includes path segments that are outside the project root directory.\n \n 1 | import \"../foo.pkl\"\n ^^^^^^^^^^^^\n \"\"\"\n .trimIndent()\n )\n }\n\n // Absolute path imports on Windows must use an absolute URI (e.g. file:///C:/Foo/Bar), because\n // they must contain drive letters, which conflict with schemes.\n // We skip validation for absolute URIs, so effectively we skip this check on Windows.\n @Test\n @DisabledOnOs(OS.WINDOWS)\n fun `import path verification -- absolute import from root dir`(@TempDir tempDir: Path) {\n tempDir.writeFile(\n \"main.pkl\",\n \"\"\"\n import \"$tempDir/foo.pkl\"\n \n res = foo\n \"\"\"\n .trimIndent(),\n )\n tempDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"mypackage\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/mypackage\"\n packageZipUrl = \"https://foo.com\"\n }\n \"\"\"\n .trimIndent(),\n )\n val e =\n assertThrows {\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(tempDir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n consoleWriter = StringWriter(),\n )\n .run()\n }\n assertThat(e.message)\n .startsWith(\n \"\"\"\n –– Pkl Error ––\n Path `$tempDir/foo.pkl` includes path segments that are outside the project root directory.\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n @DisabledOnOs(OS.WINDOWS)\n fun `import path verification -- absolute read from root dir`(@TempDir tempDir: Path) {\n tempDir.writeFile(\n \"main.pkl\",\n \"\"\"\n res = read(\"$tempDir/foo.pkl\")\n \"\"\"\n .trimIndent(),\n )\n tempDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"mypackage\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/mypackage\"\n packageZipUrl = \"https://foo.com\"\n }\n \"\"\"\n .trimIndent(),\n )\n val e =\n assertThrows {\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(tempDir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n consoleWriter = StringWriter(),\n )\n .run()\n }\n assertThat(e.message)\n .startsWith(\n \"\"\"\n –– Pkl Error ––\n Path `$tempDir/foo.pkl` includes path segments that are outside the project root directory.\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `import path verification -- passing`(@TempDir tempDir: Path) {\n tempDir.writeFile(\n \"foo/bar.pkl\",\n \"\"\"\n import \"baz.pkl\"\n \"\"\"\n .trimIndent(),\n )\n tempDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"mypackage\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/mypackage\"\n packageZipUrl = \"https://foo.com\"\n }\n \"\"\"\n .trimIndent(),\n )\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(tempDir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n consoleWriter = StringWriter(),\n )\n .run()\n }\n\n @Test\n fun `multiple projects`(@TempDir tempDir: Path) {\n tempDir.writeFile(\"project1/main.pkl\", \"res = 1\")\n tempDir.writeFile(\n \"project1/PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"project1\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/project1\"\n packageZipUrl = \"https://foo.com\"\n }\n \"\"\"\n .trimIndent(),\n )\n tempDir.writeFile(\"project2/main2.pkl\", \"res = 2\")\n tempDir.writeFile(\n \"project2/PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"project2\"\n version = \"2.0.0\"\n baseUri = \"package://example.com/project2\"\n packageZipUrl = \"https://foo.com\"\n }\n \"\"\"\n .trimIndent(),\n )\n val out = StringWriter()\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(tempDir.resolve(\"project1\"), tempDir.resolve(\"project2\")),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n consoleWriter = out,\n )\n .run()\n val sep = File.separatorChar\n assertThat(out.toString())\n .isEqualToNormalizingNewlines(\n \"\"\"\n .out${sep}project1@1.0.0${sep}project1@1.0.0.zip\n .out${sep}project1@1.0.0${sep}project1@1.0.0.zip.sha256\n .out${sep}project1@1.0.0${sep}project1@1.0.0\n .out${sep}project1@1.0.0${sep}project1@1.0.0.sha256\n .out${sep}project2@2.0.0${sep}project2@2.0.0.zip\n .out${sep}project2@2.0.0${sep}project2@2.0.0.zip.sha256\n .out${sep}project2@2.0.0${sep}project2@2.0.0\n .out${sep}project2@2.0.0${sep}project2@2.0.0.sha256\n\n \"\"\"\n .trimIndent()\n )\n assertThat(tempDir.resolve(\".out/project1@1.0.0/project1@1.0.0.zip\").zipFilePaths())\n .hasSameElementsAs(listOf(\"/\", \"/main.pkl\"))\n assertThat(tempDir.resolve(\".out/project2@2.0.0/project2@2.0.0.zip\").zipFilePaths())\n .hasSameElementsAs(listOf(\"/\", \"/main2.pkl\"))\n }\n\n @Test\n fun `publish checks`(@TempDir tempDir: Path) {\n tempDir.writeFile(\"project/main.pkl\", \"res = 1\")\n tempDir.writeFile(\n \"project/PklProject\",\n // intentionally conflict with localhost:0/birds@0.5.0 from our test fixtures\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"birds\"\n version = \"0.5.0\"\n baseUri = \"package://localhost:0/birds\"\n packageZipUrl = \"https://foo.com\"\n }\n \"\"\"\n .trimIndent(),\n )\n val e =\n assertThrows {\n CliProjectPackager(\n CliBaseOptions(\n workingDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = packageServer.port,\n ),\n listOf(tempDir.resolve(\"project\")),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = false,\n consoleWriter = StringWriter(),\n )\n .run()\n }\n assertThat(e)\n .hasMessageStartingWith(\n \"\"\"\n Package `package://localhost:0/birds@0.5.0` was already published with different contents.\n \n Computed checksum: aa8c883841db22e92794f4708b01dc905b5da77645b7dfb5b22a73da8c347db1\n Published checksum: ${PackageServer.BIRDS_SHA}\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `publish check when package is not yet published`(@TempDir tempDir: Path) {\n tempDir.writeFile(\"project/main.pkl\", \"res = 1\")\n tempDir.writeFile(\n \"project/PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"mangos\"\n version = \"1.0.0\"\n baseUri = \"package://localhost:0/mangos\"\n packageZipUrl = \"https://foo.com\"\n }\n \"\"\"\n .trimIndent(),\n )\n val out = StringWriter()\n CliProjectPackager(\n CliBaseOptions(\n workingDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = packageServer.port,\n ),\n listOf(tempDir.resolve(\"project\")),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = false,\n consoleWriter = out,\n )\n .run()\n val sep = File.separatorChar\n assertThat(out.toString())\n .isEqualToNormalizingNewlines(\n \"\"\"\n .out${sep}mangos@1.0.0${sep}mangos@1.0.0.zip\n .out${sep}mangos@1.0.0${sep}mangos@1.0.0.zip.sha256\n .out${sep}mangos@1.0.0${sep}mangos@1.0.0\n .out${sep}mangos@1.0.0${sep}mangos@1.0.0.sha256\n\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `generate annotations`(@TempDir tempDir: Path) {\n tempDir\n .resolve(\"PklProject\")\n .writeString(\n \"\"\"\n @Unlisted\n @Deprecated { since = \"0.26.1\"; message = \"do not use\" }\n @ModuleInfo { minPklVersion = \"0.26.0\" }\n amends \"pkl:Project\"\n \n package {\n name = \"mypackage\"\n version = \"1.0.0\"\n baseUri = \"package://example.com/mypackage\"\n packageZipUrl = \"https://foo.com\"\n }\n \"\"\"\n .trimIndent()\n )\n val packager =\n CliProjectPackager(\n CliBaseOptions(workingDir = tempDir),\n listOf(tempDir),\n CliTestOptions(),\n \".out/%{name}@%{version}\",\n skipPublishCheck = true,\n consoleWriter = StringWriter(),\n )\n packager.run()\n val expectedMetadata = tempDir.resolve(\".out/mypackage@1.0.0/mypackage@1.0.0\")\n assertThat(expectedMetadata).exists()\n assertThat(expectedMetadata)\n .hasContent(\n \"\"\"\n {\n \"name\": \"mypackage\",\n \"packageUri\": \"package://example.com/mypackage@1.0.0\",\n \"version\": \"1.0.0\",\n \"packageZipUrl\": \"https://foo.com\",\n \"packageZipChecksums\": {\n \"sha256\": \"8739c76e681f900923b900c9df0ef75cf421d39cabb54650c4b9ad19b6a76d85\"\n },\n \"dependencies\": {},\n \"authors\": [],\n \"annotations\": [\n {\n \"type\": \"PObject\",\n \"classInfo\": {\n \"moduleName\": \"pkl.base\",\n \"class\": \"Unlisted\",\n \"moduleUri\": \"pkl:base\"\n },\n \"properties\": {}\n },\n {\n \"type\": \"PObject\",\n \"classInfo\": {\n \"moduleName\": \"pkl.base\",\n \"class\": \"Deprecated\",\n \"moduleUri\": \"pkl:base\"\n },\n \"properties\": {\n \"since\": \"0.26.1\",\n \"message\": \"do not use\",\n \"replaceWith\": null\n }\n },\n {\n \"type\": \"PObject\",\n \"classInfo\": {\n \"moduleName\": \"pkl.base\",\n \"class\": \"ModuleInfo\",\n \"moduleUri\": \"pkl:base\"\n },\n \"properties\": {\n \"minPklVersion\": \"0.26.0\"\n }\n }\n ]\n }\n \"\"\"\n .trimIndent()\n )\n }\n\n private fun Path.zipFilePaths(): List {\n return FileSystems.newFileSystem(URI(\"jar:${toUri()}\"), emptyMap()).use { fs ->\n Files.walk(fs.getPath(\"/\")).map(IoUtils::toNormalizedPathString).collect(Collectors.toList())\n }\n }\n}\n" }, { "path": "pkl-cli/src/test/kotlin/org/pkl/cli/CliProjectResolverTest.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.io.File\nimport java.io.StringWriter\nimport java.nio.file.Path\nimport kotlin.io.path.createDirectories\nimport org.assertj.core.api.Assertions.assertThat\nimport org.assertj.core.api.Assertions.assertThatCode\nimport org.junit.jupiter.api.AfterAll\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertThrows\nimport org.junit.jupiter.api.io.TempDir\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.CliException\nimport org.pkl.commons.test.FileTestUtils\nimport org.pkl.commons.test.PackageServer\nimport org.pkl.commons.writeString\nimport org.pkl.core.util.IoUtils\n\nclass CliProjectResolverTest {\n companion object {\n private val packageServer = PackageServer()\n\n @AfterAll\n @JvmStatic\n fun afterAll() {\n packageServer.close()\n }\n }\n\n @Test\n fun `missing PklProject when inferring a project dir`(@TempDir tempDir: Path) {\n val packager =\n CliProjectResolver(\n CliBaseOptions(workingDir = tempDir, noCache = true),\n emptyList(),\n consoleWriter = StringWriter(),\n errWriter = StringWriter(),\n )\n val err = assertThrows { packager.run() }\n assertThat(err).hasMessageStartingWith(\"No project visible to the working directory.\")\n }\n\n @Test\n fun `missing PklProject when explicit dir is provided`(@TempDir tempDir: Path) {\n val packager =\n CliProjectResolver(\n CliBaseOptions(noCache = true),\n listOf(tempDir),\n consoleWriter = StringWriter(),\n errWriter = StringWriter(),\n )\n val err = assertThrows { packager.run() }\n assertThat(err).hasMessageStartingWith(\"Directory $tempDir does not contain a PklProject file.\")\n }\n\n @Test\n fun `basic project`(@TempDir tempDir: Path) {\n tempDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n\n dependencies {\n [\"birds\"] {\n uri = \"package://localhost:0/birds@0.5.0\"\n }\n }\n \"\"\"\n .trimIndent(),\n )\n CliProjectResolver(\n CliBaseOptions(\n workingDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = packageServer.port,\n noCache = true,\n ),\n listOf(tempDir),\n consoleWriter = StringWriter(),\n errWriter = StringWriter(),\n )\n .run()\n val expectedOutput = tempDir.resolve(\"PklProject.deps.json\")\n assertThat(expectedOutput)\n .hasContent(\n \"\"\"\n {\n \"schemaVersion\": 1,\n \"resolvedDependencies\": {\n \"package://localhost:0/birds@0\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/birds@0.5.0\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.BIRDS_SHA}\"\n }\n },\n \"package://localhost:0/fruit@1\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/fruit@1.0.5\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.FRUIT_SHA}\"\n }\n }\n }\n }\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `basic project, inferred from working dir`(@TempDir tempDir: Path) {\n tempDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n\n dependencies {\n [\"birds\"] {\n uri = \"package://localhost:0/birds@0.5.0\"\n }\n }\n \"\"\"\n .trimIndent(),\n )\n CliProjectResolver(\n CliBaseOptions(\n workingDir = tempDir,\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = packageServer.port,\n noCache = true,\n ),\n emptyList(),\n consoleWriter = StringWriter(),\n errWriter = StringWriter(),\n )\n .run()\n val expectedOutput = tempDir.resolve(\"PklProject.deps.json\")\n assertThat(expectedOutput)\n .hasContent(\n \"\"\"\n {\n \"schemaVersion\": 1,\n \"resolvedDependencies\": {\n \"package://localhost:0/birds@0\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/birds@0.5.0\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.BIRDS_SHA}\"\n }\n },\n \"package://localhost:0/fruit@1\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/fruit@1.0.5\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.FRUIT_SHA}\"\n }\n }\n }\n }\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `local dependencies`(@TempDir tempDir: Path) {\n val projectDir = tempDir.resolve(\"theproject\")\n projectDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n\n dependencies {\n [\"birds\"] {\n uri = \"package://localhost:0/birds@0.5.0\"\n }\n [\"project2\"] = import(\"../project2/PklProject\")\n }\n \"\"\"\n .trimIndent(),\n )\n projectDir.writeFile(\n \"../project2/PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"project2\"\n baseUri = \"package://localhost:0/package2\"\n version = \"5.0.0\"\n packageZipUrl = \"https://foo.com/package2.zip\"\n }\n \n dependencies {\n [\"fruit\"] {\n uri = \"package://localhost:0/fruit@1.0.5\"\n }\n [\"project3\"] = import(\"../project3/PklProject\")\n }\n \"\"\"\n .trimIndent(),\n )\n\n projectDir.writeFile(\n \"../project3/PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"project3\"\n baseUri = \"package://localhost:0/package3\"\n version = \"5.0.0\"\n packageZipUrl = \"https://foo.com/package3.zip\"\n }\n \n dependencies {\n [\"fruit\"] {\n uri = \"package://localhost:0/fruit@1.1.0\"\n }\n }\n \"\"\"\n .trimIndent(),\n )\n CliProjectResolver(\n CliBaseOptions(\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = packageServer.port,\n noCache = true,\n ),\n listOf(projectDir),\n consoleWriter = StringWriter(),\n errWriter = StringWriter(),\n )\n .run()\n val expectedOutput = projectDir.resolve(\"PklProject.deps.json\")\n assertThat(expectedOutput)\n .hasContent(\n \"\"\"\n {\n \"schemaVersion\": 1,\n \"resolvedDependencies\": {\n \"package://localhost:0/birds@0\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/birds@0.5.0\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.BIRDS_SHA}\"\n }\n },\n \"package://localhost:0/fruit@1\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/fruit@1.1.0\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.FRUIT_1_1_SHA}\"\n }\n },\n \"package://localhost:0/package2@5\": {\n \"type\": \"local\",\n \"uri\": \"projectpackage://localhost:0/package2@5.0.0\",\n \"path\": \"../project2\"\n },\n \"package://localhost:0/package3@5\": {\n \"type\": \"local\",\n \"uri\": \"projectpackage://localhost:0/package3@5.0.0\",\n \"path\": \"../project3\"\n }\n }\n }\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `local dependency overridden by remote dependency`(@TempDir tempDir: Path) {\n val projectDir = tempDir.resolve(\"theproject\")\n projectDir.writeFile(\n \"PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n\n dependencies {\n [\"birds\"] {\n uri = \"package://localhost:0/birds@0.5.0\"\n }\n [\"fruit\"] = import(\"../fruit/PklProject\")\n }\n \"\"\"\n .trimIndent(),\n )\n projectDir.writeFile(\n \"../fruit/PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n \n package {\n name = \"fruit\"\n baseUri = \"package://localhost:0/fruit\"\n version = \"1.0.0\"\n packageZipUrl = \"https://foo.com/fruit.zip\"\n }\n \"\"\"\n .trimIndent(),\n )\n val consoleOut = StringWriter()\n val errOut = StringWriter()\n CliProjectResolver(\n CliBaseOptions(\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = packageServer.port,\n noCache = true,\n ),\n listOf(projectDir),\n consoleWriter = consoleOut,\n errWriter = errOut,\n )\n .run()\n val expectedOutput = projectDir.resolve(\"PklProject.deps.json\")\n assertThat(expectedOutput)\n .hasContent(\n \"\"\"\n {\n \"schemaVersion\": 1,\n \"resolvedDependencies\": {\n \"package://localhost:0/birds@0\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/birds@0.5.0\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.BIRDS_SHA}\"\n }\n },\n \"package://localhost:0/fruit@1\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/fruit@1.0.5\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.FRUIT_SHA}\"\n }\n }\n }\n }\n \"\"\"\n .trimIndent()\n )\n assertThat(errOut.toString())\n .isEqualTo(\n \"WARN: local dependency `package://localhost:0/fruit@1.0.0` was overridden to remote dependency `package://localhost:0/fruit@1.0.5`.${IoUtils.getLineSeparator()}\"\n )\n }\n\n @Test\n fun `resolving multiple projects`(@TempDir tempDir: Path) {\n tempDir.writeFile(\n \"project1/PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n\n dependencies {\n [\"birds\"] {\n uri = \"package://localhost:0/birds@0.5.0\"\n }\n }\n \"\"\"\n .trimIndent(),\n )\n\n tempDir.writeFile(\n \"project2/PklProject\",\n \"\"\"\n amends \"pkl:Project\"\n\n dependencies {\n [\"fruit\"] {\n uri = \"package://localhost:0/fruit@1.1.0\"\n }\n }\n \"\"\"\n .trimIndent(),\n )\n\n val consoleOut = StringWriter()\n val errOut = StringWriter()\n CliProjectResolver(\n CliBaseOptions(\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = packageServer.port,\n noCache = true,\n ),\n listOf(tempDir.resolve(\"project1\"), tempDir.resolve(\"project2\")),\n consoleWriter = consoleOut,\n errWriter = errOut,\n )\n .run()\n val sep = File.separatorChar\n assertThat(consoleOut.toString())\n .isEqualToNormalizingNewlines(\n \"\"\"\n $tempDir${sep}project1${sep}PklProject.deps.json\n $tempDir${sep}project2${sep}PklProject.deps.json\n \n \"\"\"\n .trimIndent()\n )\n assertThat(tempDir.resolve(\"project1/PklProject.deps.json\"))\n .hasContent(\n \"\"\"\n {\n \"schemaVersion\": 1,\n \"resolvedDependencies\": {\n \"package://localhost:0/birds@0\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/birds@0.5.0\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.BIRDS_SHA}\"\n }\n },\n \"package://localhost:0/fruit@1\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/fruit@1.0.5\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.FRUIT_SHA}\"\n }\n }\n }\n }\n \"\"\"\n .trimIndent()\n )\n assertThat(tempDir.resolve(\"project2/PklProject.deps.json\"))\n .hasContent(\n \"\"\"\n {\n \"schemaVersion\": 1,\n \"resolvedDependencies\": {\n \"package://localhost:0/fruit@1\": {\n \"type\": \"remote\",\n \"uri\": \"projectpackage://localhost:0/fruit@1.1.0\",\n \"checksums\": {\n \"sha256\": \"${PackageServer.FRUIT_1_1_SHA}\"\n }\n }\n }\n }\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `IOException when writing to PklProject-deps-json`(@TempDir tempDir: Path) {\n val consoleOut = StringWriter()\n val errOut = StringWriter()\n tempDir\n .resolve(\"PklProject\")\n .writeString(\n \"\"\"\n amends \"pkl:Project\"\n\n dependencies {\n [\"birds\"] {\n uri = \"package://localhost:0/birds@0.5.0\"\n }\n }\n \"\"\"\n .trimIndent()\n )\n // coerce an IOException by making this a directory\n val depsJsonFile = tempDir.resolve(\"PklProject.deps.json\").also { it.createDirectories() }\n assertThatCode {\n CliProjectResolver(\n CliBaseOptions(\n caCertificates = listOf(FileTestUtils.selfSignedCertificate),\n testPort = packageServer.port,\n noCache = true,\n ),\n listOf(tempDir),\n consoleWriter = consoleOut,\n errWriter = errOut,\n )\n .run()\n }\n .hasMessageContaining(\"Failed to write to $depsJsonFile\")\n }\n}\n" }, { "path": "pkl-cli/src/test/kotlin/org/pkl/cli/CliShellCompletionTest.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport com.github.ajalt.clikt.testing.test\nimport org.assertj.core.api.Assertions.assertThat\nimport org.junit.jupiter.api.Test\nimport org.pkl.cli.commands.RootCommand\n\nclass CliShellCompletionTest {\n @Test\n fun `shell completion command supports required shells`() {\n val shellList = listOf(\"bash\", \"zsh\", \"fish\")\n\n for (shell in shellList) {\n val result = RootCommand().test(\"shell-completion $shell\")\n\n assertThat(result.stdout).contains(\"Command completion for pkl\")\n }\n }\n}\n" }, { "path": "pkl-cli/src/test/kotlin/org/pkl/cli/CliTestRunnerTest.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport com.github.ajalt.clikt.testing.test\nimport java.io.StringWriter\nimport java.io.Writer\nimport java.net.URI\nimport java.nio.file.Path\nimport java.util.*\nimport org.assertj.core.api.Assertions.assertThat\nimport org.assertj.core.api.Assertions.assertThatCode\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertThrows\nimport org.junit.jupiter.api.io.TempDir\nimport org.pkl.cli.commands.RootCommand\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.CliException\nimport org.pkl.commons.cli.CliTestOptions\nimport org.pkl.commons.readString\nimport org.pkl.commons.toUri\nimport org.pkl.commons.writeString\n\nclass CliTestRunnerTest {\n @Test\n fun `CliTestRunner succeed test`(@TempDir tempDir: Path) {\n val code =\n \"\"\"\n amends \"pkl:test\"\n\n facts {\n [\"succeed\"] {\n 8 == 8\n 3 == 3\n }\n }\n \"\"\"\n .trimIndent()\n val input = tempDir.resolve(\"test.pkl\").writeString(code).toString()\n val out = StringWriter()\n val err = StringWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input.toUri()),\n settings = URI(\"pkl:settings\"),\n powerAssertionsEnabled = true,\n )\n val testOpts = CliTestOptions()\n val runner = CliTestRunner(opts, testOpts, consoleWriter = out, errWriter = err)\n runner.run()\n\n assertThat(out.toString().stripFileAndLines(tempDir))\n .isEqualTo(\n \"\"\"\n module test\n facts\n ✔ succeed\n \n 100.0% tests pass [1 passed], 100.0% asserts pass [2 passed]\n\n \"\"\"\n .trimIndent()\n )\n assertThat(err.toString()).isEqualTo(\"\")\n }\n\n @Test\n fun `CliTestRunner fail test`(@TempDir tempDir: Path) {\n val code =\n \"\"\"\n amends \"pkl:test\"\n\n facts {\n [\"fail\"] {\n 4 == 9\n 1 == 5\n }\n }\n \"\"\"\n .trimIndent()\n val input = tempDir.resolve(\"test.pkl\").writeString(code).toString()\n val out = StringWriter()\n val err = StringWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input.toUri()),\n settings = URI(\"pkl:settings\"),\n powerAssertionsEnabled = true,\n )\n val testOpts = CliTestOptions()\n val runner = CliTestRunner(opts, testOpts, consoleWriter = out, errWriter = err)\n assertThatCode { runner.run() }.hasMessage(\"Tests failed.\")\n\n assertThat(out.toString().stripFileAndLines(tempDir))\n .isEqualTo(\n \"\"\"\n module test\n facts\n ✘ fail\n 4 == 9 (/tempDir/test.pkl, line xx)\n │\n false\n 1 == 5 (/tempDir/test.pkl, line xx)\n │\n false\n\n 0.0% tests pass [1/1 failed], 0.0% asserts pass [2/2 failed]\n\n \"\"\"\n .trimIndent()\n )\n assertThat(err.toString()).isEqualTo(\"\")\n }\n\n @Test\n fun `CliTestRunner with thrown error in facts`(@TempDir tempDir: Path) {\n val code =\n \"\"\"\n amends \"pkl:test\"\n\n facts {\n [\"fail\"] {\n throw(\"uh oh\")\n }\n }\n \"\"\"\n .trimIndent()\n val input = tempDir.resolve(\"test.pkl\").writeString(code).toString()\n val out = StringWriter()\n val err = StringWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input.toUri()),\n settings = URI(\"pkl:settings\"),\n powerAssertionsEnabled = true,\n )\n val testOpts = CliTestOptions()\n val runner = CliTestRunner(opts, testOpts, consoleWriter = out, errWriter = err)\n assertThatCode { runner.run() }.hasMessage(\"Tests failed.\")\n\n assertThat(out.toString().stripFileAndLines(tempDir))\n .isEqualToNormalizingNewlines(\n \"\"\"\n module test\n facts\n ✘ fail\n –– Pkl Error ––\n uh oh\n\n 5 | throw(\"uh oh\")\n ^^^^^^^^^^^^^^\n at test#facts[\"fail\"][#1] (/tempDir/test.pkl, line xx)\n\n 0.0% tests pass [1/1 failed], 0.0% asserts pass [1/1 failed]\n\n \"\"\"\n .trimIndent()\n )\n assertThat(err.toString()).isEqualTo(\"\")\n }\n\n @Test\n fun `CliTestRunner with thrown error in examples -- no expected output`(@TempDir tempDir: Path) {\n val code =\n \"\"\"\n amends \"pkl:test\"\n\n examples {\n [\"fail\"] {\n throw(\"uh oh\")\n }\n }\n \"\"\"\n .trimIndent()\n val input = tempDir.resolve(\"test.pkl\").writeString(code).toString()\n val out = StringWriter()\n val err = StringWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input.toUri()),\n settings = URI(\"pkl:settings\"),\n powerAssertionsEnabled = true,\n )\n val testOpts = CliTestOptions()\n val runner = CliTestRunner(opts, testOpts, consoleWriter = out, errWriter = err)\n assertThatCode { runner.run() }.hasMessage(\"Tests failed.\")\n\n assertThat(out.toString().stripFileAndLines(tempDir))\n .isEqualTo(\n \"\"\"\n module test\n examples\n ✘ fail\n –– Pkl Error ––\n uh oh\n\n 5 | throw(\"uh oh\")\n ^^^^^^^^^^^^^^\n at test#examples[\"fail\"][#1] (/tempDir/test.pkl, line xx)\n\n 0.0% tests pass [1/1 failed], 0.0% asserts pass [1/1 failed]\n\n \"\"\"\n .trimIndent()\n )\n assertThat(err.toString()).isEqualTo(\"\")\n }\n\n @Test\n fun `CliTestRunner with thrown error in examples -- existing expected output`(\n @TempDir tempDir: Path\n ) {\n val code =\n \"\"\"\n amends \"pkl:test\"\n\n examples {\n [\"fail\"] {\n throw(\"uh oh\")\n }\n }\n \"\"\"\n .trimIndent()\n val input = tempDir.resolve(\"test.pkl\").writeString(code).toString()\n tempDir\n .resolve(\"test.pkl-expected.pcf\")\n .writeString(\n \"\"\"\n examples {\n [\"fail\"] {\n \"never compared to\"\n }\n }\n \"\"\"\n .trimIndent()\n )\n val out = StringWriter()\n val err = StringWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input.toUri()),\n settings = URI(\"pkl:settings\"),\n powerAssertionsEnabled = true,\n )\n val testOpts = CliTestOptions()\n val runner = CliTestRunner(opts, testOpts, consoleWriter = out, errWriter = err)\n assertThatCode { runner.run() }.hasMessage(\"Tests failed.\")\n\n assertThat(out.toString().stripFileAndLines(tempDir))\n .isEqualToNormalizingNewlines(\n \"\"\"\n module test\n examples\n ✘ fail\n –– Pkl Error ––\n uh oh\n \n 5 | throw(\"uh oh\")\n ^^^^^^^^^^^^^^\n at test#examples[\"fail\"][#1] (/tempDir/test.pkl, line xx)\n\n 0.0% tests pass [1/1 failed], 0.0% asserts pass [1/1 failed]\n\n \"\"\"\n .trimIndent()\n )\n assertThat(err.toString()).isEqualTo(\"\")\n }\n\n @Test\n fun `CliTestRunner JUnit reports`(@TempDir tempDir: Path) {\n val code =\n \"\"\"\n amends \"pkl:test\"\n\n facts {\n [\"foo\"] {\n 9 == trace(9)\n \"foo\" == \"foo\"\n }\n [\"bar\"] {\n \"foo\" == \"foo\"\n 5 == 9\n }\n }\n \"\"\"\n .trimIndent()\n val input = tempDir.resolve(\"test.pkl\").writeString(code).toString()\n val noopWriter = noopWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input.toUri()),\n settings = URI(\"pkl:settings\"),\n powerAssertionsEnabled = true,\n )\n val testOpts = CliTestOptions(junitDir = tempDir)\n val runner = CliTestRunner(opts, testOpts, noopWriter, noopWriter)\n assertThatCode { runner.run() }.hasMessageContaining(\"failed\")\n\n val junitReport = tempDir.resolve(\"test.xml\").readString().stripFileAndLines(tempDir)\n assertThat(junitReport)\n .isEqualTo(\n \"\"\"\n \n \n \n \n 5 == 9 (/tempDir/test.pkl, line xx)\n │\n false\n \n \n \n\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `CliTestRunner JUnit reports, with thrown error`(@TempDir tempDir: Path) {\n val code =\n \"\"\"\n amends \"pkl:test\"\n\n facts {\n [\"foo\"] {\n 9 == trace(9)\n \"foo\" == \"foo\"\n }\n [\"fail\"] {\n throw(\"uh oh\")\n }\n }\n \"\"\"\n .trimIndent()\n val input = tempDir.resolve(\"test.pkl\").writeString(code).toString()\n val noopWriter = noopWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input.toUri()),\n settings = URI(\"pkl:settings\"),\n powerAssertionsEnabled = true,\n )\n val testOpts = CliTestOptions(junitDir = tempDir)\n val runner = CliTestRunner(opts, testOpts, noopWriter, noopWriter)\n assertThatCode { runner.run() }.hasMessageContaining(\"failed\")\n\n val junitReport = tempDir.resolve(\"test.xml\").readString().stripFileAndLines(tempDir)\n assertThat(junitReport)\n .isEqualTo(\n \"\"\"\n \n \n \n \n –– Pkl Error ––\n uh oh\n \n 9 | throw("uh oh")\n ^^^^^^^^^^^^^^\n at test#facts["fail"][#1] (/tempDir/test.pkl, line xx)\n \n \n \n \n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `CliTestRunner duplicated JUnit reports`(@TempDir tempDir: Path) {\n val foo =\n \"\"\"\n module foo\n \n amends \"pkl:test\"\n\n facts {\n [\"foo\"] {\n 1 == 1\n }\n }\n \"\"\"\n .trimIndent()\n\n val bar =\n \"\"\"\n module foo\n \n amends \"pkl:test\"\n\n facts {\n [\"foo\"] {\n 1 == 1\n }\n }\n \"\"\"\n .trimIndent()\n val input = tempDir.resolve(\"test.pkl\").writeString(foo).toString()\n val input2 = tempDir.resolve(\"test.pkl\").writeString(bar).toString()\n val noopWriter = noopWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input.toUri(), input2.toUri()),\n settings = URI(\"pkl:settings\"),\n )\n val testOpts = CliTestOptions(junitDir = tempDir)\n val runner = CliTestRunner(opts, testOpts, noopWriter, noopWriter)\n assertThatCode { runner.run() }.hasMessageContaining(\"failed\")\n }\n\n @Test\n fun `CliTestRunner test per module`(@TempDir tempDir: Path) {\n val code1 =\n \"\"\"\n amends \"pkl:test\"\n\n facts {\n [\"foo\"] {\n true\n }\n }\n \"\"\"\n .trimIndent()\n\n val code2 =\n \"\"\"\n amends \"pkl:test\"\n\n facts {\n [\"bar\"] {\n true\n }\n }\n \"\"\"\n .trimIndent()\n val input1 = tempDir.resolve(\"test1.pkl\").writeString(code1).toString()\n val input2 = tempDir.resolve(\"test2.pkl\").writeString(code2).toString()\n val noopWriter = noopWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input1.toUri(), input2.toUri()),\n settings = URI(\"pkl:settings\"),\n )\n val testOpts = CliTestOptions(junitDir = tempDir)\n val runner = CliTestRunner(opts, testOpts, noopWriter, noopWriter)\n runner.run()\n\n assertThat(tempDir.resolve(\"test1.xml\")).isNotEmptyFile()\n assertThat(tempDir.resolve(\"test2.xml\")).isNotEmptyFile()\n }\n\n @Test\n fun `CliTestRunner test aggregate`(@TempDir tempDir: Path) {\n val code1 =\n \"\"\"\n amends \"pkl:test\"\n\n facts {\n [\"foo\"] {\n true\n }\n [\"bar\"] {\n 5 == 9\n }\n }\n \"\"\"\n .trimIndent()\n\n val code2 =\n \"\"\"\n amends \"pkl:test\"\n\n facts {\n [\"xxx\"] {\n false\n }\n [\"yyy\"] {\n false\n }\n [\"zzz\"] {\n true\n }\n }\n \"\"\"\n .trimIndent()\n val input1 = tempDir.resolve(\"test1.pkl\").writeString(code1).toString()\n val input2 = tempDir.resolve(\"test2.pkl\").writeString(code2).toString()\n val noopWriter = noopWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input1.toUri(), input2.toUri()),\n settings = URI(\"pkl:settings\"),\n powerAssertionsEnabled = true,\n )\n val testOpts = CliTestOptions(junitDir = tempDir, junitAggregateReports = true)\n val runner = CliTestRunner(opts, testOpts, noopWriter, noopWriter)\n assertThatCode { runner.run() }.hasMessageContaining(\"failed\")\n\n assertThat(tempDir.resolve(\"pkl-tests.xml\")).isNotEmptyFile()\n assertThat(tempDir.resolve(\"test1.xml\")).doesNotExist()\n assertThat(tempDir.resolve(\"test2.xml\")).doesNotExist()\n\n val junitReport = tempDir.resolve(\"pkl-tests.xml\").readString().stripFileAndLines(tempDir)\n\n assertThat(junitReport)\n .isEqualTo(\n \"\"\"\n \n \n \n \n \n 5 == 9 (/tempDir/test1.pkl, line xx)\n │\n false\n \n \n \n \n false (/tempDir/test2.pkl, line xx)\n \n \n \n false (/tempDir/test2.pkl, line xx)\n \n \n \n \n \n\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `CliTestRunner test aggregate suite name`(@TempDir tempDir: Path) {\n val code1 =\n \"\"\"\n amends \"pkl:test\"\n\n facts {\n [\"foo\"] {\n true\n }\n }\n \"\"\"\n .trimIndent()\n\n val code2 =\n \"\"\"\n amends \"pkl:test\"\n\n facts {\n [\"bar\"] {\n true\n }\n }\n \"\"\"\n .trimIndent()\n val input1 = tempDir.resolve(\"test1.pkl\").writeString(code1).toString()\n val input2 = tempDir.resolve(\"test2.pkl\").writeString(code2).toString()\n val noopWriter = noopWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input1.toUri(), input2.toUri()),\n settings = URI(\"pkl:settings\"),\n )\n val testOpts =\n CliTestOptions(\n junitDir = tempDir,\n junitAggregateReports = true,\n junitAggregateSuiteName = \"custom\",\n )\n val runner = CliTestRunner(opts, testOpts, noopWriter, noopWriter)\n runner.run()\n\n assertThat(tempDir.resolve(\"custom.xml\")).isNotEmptyFile()\n assertThat(tempDir.resolve(\"pkl-tests.xml\")).doesNotExist()\n assertThat(tempDir.resolve(\"test1.xml\")).doesNotExist()\n assertThat(tempDir.resolve(\"test2.xml\")).doesNotExist()\n }\n\n @Test\n fun `no source modules specified has same message as pkl eval`() {\n val e1 = assertThrows { CliTestRunner(CliBaseOptions(), CliTestOptions()).run() }\n val e2 = RootCommand().test(\"eval\")\n assertThat(e1).hasMessageContaining(\"missing argument \")\n assertThat(e1.message!!.replace(\"test\", \"eval\") + \"\\n\").isEqualTo(e2.stderr)\n }\n\n @Test\n fun `example length mismatch`(@TempDir tempDir: Path) {\n val code =\n \"\"\"\n amends \"pkl:test\"\n\n examples {\n [\"nums\"] {\n 1\n 2\n }\n }\n \"\"\"\n .trimIndent()\n val input = tempDir.resolve(\"test.pkl\").writeString(code).toString()\n tempDir\n .resolve(\"test.pkl-expected.pcf\")\n .writeString(\n \"\"\"\n examples {\n [\"nums\"] {\n 1\n }\n }\n \"\"\"\n .trimIndent()\n )\n val out = StringWriter()\n val err = StringWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input.toUri()),\n settings = URI(\"pkl:settings\"),\n powerAssertionsEnabled = true,\n )\n val testOpts = CliTestOptions()\n val runner = CliTestRunner(opts, testOpts, consoleWriter = out, errWriter = err)\n assertThatCode { runner.run() }.hasMessage(\"Tests failed.\")\n\n assertThat(out.toString().stripFileAndLines(tempDir))\n .isEqualToNormalizingNewlines(\n \"\"\"\n module test\n examples\n ✘ nums\n (/tempDir/test.pkl, line xx)\n Output mismatch: Expected \"nums\" to contain 1 examples, but found 2\n\n 0.0% tests pass [1/1 failed], 0.0% asserts pass [1/1 failed]\n\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `only written examples`(@TempDir tempDir: Path) {\n\n val code =\n \"\"\"\n amends \"pkl:test\"\n\n examples {\n [\"nums\"] {\n 1\n 2\n }\n }\n \"\"\"\n .trimIndent()\n val input = tempDir.resolve(\"test.pkl\").writeString(code).toString()\n val out = StringWriter()\n val err = StringWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input.toUri()),\n settings = URI(\"pkl:settings\"),\n powerAssertionsEnabled = true,\n )\n val testOpts = CliTestOptions()\n val runner = CliTestRunner(opts, testOpts, consoleWriter = out, errWriter = err)\n val exception = assertThrows { runner.run() }\n assertThat(exception.exitCode).isEqualTo(10)\n assertThat(out.toString())\n .isEqualTo(\n \"\"\"\n module test\n examples\n ✍️ nums\n\n 1 examples written\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `CliTestRunner locale independence test`(@TempDir tempDir: Path) {\n val originalLocale = Locale.getDefault()\n Locale.setDefault(Locale.GERMANY)\n\n try {\n val code =\n \"\"\"\n amends \"pkl:test\"\n\n facts {\n [\"localeTest\"] {\n 1 == 1\n }\n }\n \"\"\"\n .trimIndent()\n val input = tempDir.resolve(\"test.pkl\").writeString(code).toString()\n val out = StringWriter()\n val err = StringWriter()\n val opts =\n CliBaseOptions(\n sourceModules = listOf(input.toUri()),\n settings = URI(\"pkl:settings\"),\n powerAssertionsEnabled = true,\n )\n val testOpts = CliTestOptions()\n val runner = CliTestRunner(opts, testOpts, consoleWriter = out, errWriter = err)\n runner.run()\n\n assertThat(out.toString().stripFileAndLines(tempDir))\n .isEqualTo(\n \"\"\"\n module test\n facts\n ✔ localeTest\n\n 100.0% tests pass [1 passed], 100.0% asserts pass [1 passed]\n\n \"\"\"\n .trimIndent()\n )\n assertThat(err.toString()).isEqualTo(\"\")\n } finally {\n Locale.setDefault(originalLocale)\n }\n }\n\n private fun String.stripFileAndLines(tmpDir: Path): String {\n // handle platform differences in handling of file URIs\n // (file:/// on *nix vs. file:/ on Windows)\n return replace(tmpDir.toFile().toURI().toString(), \"/tempDir/\")\n .replace(tmpDir.toUri().toString(), \"/tempDir/\")\n .replace(Regex(\"line \\\\d+\"), \"line xx\")\n }\n\n private fun noopWriter(): Writer =\n object : Writer() {\n override fun close() {}\n\n override fun flush() {}\n\n override fun write(cbuf: CharArray, off: Int, len: Int) {}\n }\n}\n" }, { "path": "pkl-cli/src/test/kotlin/org/pkl/cli/repl/ReplMessagesTest.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli.repl\n\nimport org.assertj.core.api.Assertions.assertThat\nimport org.junit.jupiter.api.Test\nimport org.pkl.commons.toPath\nimport org.pkl.core.Loggers\nimport org.pkl.core.SecurityManagers\nimport org.pkl.core.StackFrameTransformers\nimport org.pkl.core.evaluatorSettings.TraceMode\nimport org.pkl.core.http.HttpClient\nimport org.pkl.core.module.ModuleKeyFactories\nimport org.pkl.core.repl.ReplRequest\nimport org.pkl.core.repl.ReplResponse\nimport org.pkl.core.repl.ReplServer\n\nclass ReplMessagesTest {\n private val server =\n ReplServer(\n SecurityManagers.defaultManager,\n HttpClient.dummyClient(),\n Loggers.stdErr(),\n listOf(ModuleKeyFactories.standardLibrary),\n listOf(),\n mapOf(),\n mapOf(),\n null,\n null,\n null,\n \"/\".toPath(),\n StackFrameTransformers.defaultTransformer,\n false,\n TraceMode.COMPACT,\n )\n\n @Test\n fun `run examples`() {\n val examples = ReplMessages.examples\n var startIndex = examples.indexOf(\"```\")\n while (startIndex != -1) {\n val endIndex = examples.indexOf(\"```\", startIndex + 3)\n assertThat(endIndex).isNotEqualTo(-1)\n val text =\n examples\n .substring(startIndex + 3, endIndex)\n .lines()\n .filterNot { it.contains(\":force\") }\n .joinToString(\"\\n\")\n val responses = server.handleRequest(ReplRequest.Eval(\"1\", text, true, true))\n assertThat(responses.size).isBetween(1, 9)\n assertThat(responses).hasOnlyElementsOfType(ReplResponse.EvalSuccess::class.java)\n startIndex = examples.indexOf(\"```\", endIndex + 3)\n }\n }\n\n @Test\n fun `handle single backtick`() {\n val responses = server.handleRequest(ReplRequest.Eval(\"1\", \"`\", true, true))\n assertThat(responses.size).isEqualTo(1)\n assertThat(responses).hasOnlyElementsOfType(ReplResponse.EvalError::class.java)\n }\n}\n" }, { "path": "pkl-cli/src/test/kotlin/org/pkl/cli/testExtensions.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.cli\n\nimport java.nio.charset.StandardCharsets\nimport java.nio.file.Path\nimport kotlin.io.path.createParentDirectories\nimport org.pkl.commons.writeString\n\nfun Path.writeFile(fileName: String, contents: String): Path {\n return resolve(fileName).apply {\n createParentDirectories()\n writeString(contents, StandardCharsets.UTF_8)\n }\n}\n\nfun Path.writeEmptyFile(fileName: String): Path = writeFile(fileName, \"\")\n" }, { "path": "pkl-codegen-java/gradle.lockfile", "content": "# This is a Gradle generated file for dependency locking.\n# Manual edits can break the build and are not advised.\n# This file is expected to be part of source control.\ncom.github.ajalt.clikt:clikt-core-jvm:5.0.3=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-core:5.0.3=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-jvm:5.0.3=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-markdown-jvm:5.0.3=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-markdown:5.0.3=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt:5.0.3=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.colormath:colormath-jvm:3.6.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.colormath:colormath:3.6.0=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-core-jvm:3.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-core:3.0.1=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-ffm-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-ffm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-graal-ffi-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-graal-ffi:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-jna-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-jna:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm:3.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-markdown-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-markdown:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant:3.0.1=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ben-manes.caffeine:caffeine:2.9.3=swiftExportClasspathResolvable\ncom.google.errorprone:error_prone_annotations:2.28.0=swiftExportClasspathResolvable\ncom.palantir.javapoet:javapoet:0.7.0=compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\nio.github.java-diff-utils:java-diff-utils:4.12=kotlinInternalAbiValidation\nio.leangen.geantyref:geantyref:1.3.16=testRuntimeClasspath\nio.opentelemetry:opentelemetry-api:1.41.0=swiftExportClasspathResolvable\nio.opentelemetry:opentelemetry-context:1.41.0=swiftExportClasspathResolvable\nnet.bytebuddy:byte-buddy:1.17.7=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\nnet.java.dev.jna:jna:5.14.0=runtimeClasspath,testRuntimeClasspath\norg.apiguardian:apiguardian-api:1.1.2=testCompileClasspath,testImplementationDependenciesMetadata\norg.assertj:assertj-core:3.27.6=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.bouncycastle:bcpg-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcpkix-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcprov-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcutil-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.checkerframework:checker-qual:3.43.0=swiftExportClasspathResolvable\norg.graalvm.polyglot:polyglot:25.0.0=runtimeClasspath,testRuntimeClasspath\norg.graalvm.sdk:collections:25.0.0=runtimeClasspath,testRuntimeClasspath\norg.graalvm.sdk:graal-sdk:25.0.0=runtimeClasspath,testRuntimeClasspath\norg.graalvm.sdk:nativeimage:25.0.0=runtimeClasspath,testRuntimeClasspath\norg.graalvm.sdk:word:25.0.0=runtimeClasspath,testRuntimeClasspath\norg.graalvm.truffle:truffle-api:25.0.0=runtimeClasspath,testRuntimeClasspath\norg.jetbrains.kotlin:abi-tools-api:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:abi-tools:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-build-tools-api:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-build-tools-impl:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-compiler-runner:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-client:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-klib-commonizer-embeddable:2.2.20=kotlinKlibCommonizerClasspath\norg.jetbrains.kotlin:kotlin-metadata-jvm:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-native-prebuilt:2.0.21=kotlinNativeBundleConfiguration\norg.jetbrains.kotlin:kotlin-reflect:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-script-runtime:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-scripting-common:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-compiler-impl-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-jvm:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-stdlib-jdk7:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib-jdk8:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,runtimeClasspath,swiftExportClasspathResolvable,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:swift-export-embeddable:2.2.20=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.8.0=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-bom:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core-jvm:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3=swiftExportClasspathResolvable\norg.jetbrains:annotations:13.0=compileClasspath,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,runtimeClasspath,swiftExportClasspathResolvable,testCompileClasspath,testRuntimeClasspath\norg.jetbrains:markdown-jvm:0.7.3=runtimeClasspath,testRuntimeClasspath\norg.jetbrains:markdown:0.7.3=runtimeClasspath,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-api:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-engine:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-params:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-commons:1.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-engine:1.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-launcher:1.14.0=testRuntimeClasspath\norg.junit:junit-bom:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.msgpack:msgpack-core:0.9.8=runtimeClasspath,testRuntimeClasspath\norg.opentest4j:opentest4j:1.3.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.organicdesign:Paguro:3.10.3=runtimeClasspath,testRuntimeClasspath\norg.snakeyaml:snakeyaml-engine:2.10=runtimeClasspath,testRuntimeClasspath\nempty=annotationProcessor,compileOnlyDependenciesMetadata,intransitiveDependenciesMetadata,kotlinCompilerPluginClasspath,kotlinNativeCompilerPluginClasspath,kotlinScriptDefExtensions,shadow,signatures,sourcesJar,testAnnotationProcessor,testApiDependenciesMetadata,testCompileOnlyDependenciesMetadata,testIntransitiveDependenciesMetadata,testKotlinScriptDefExtensions\n" }, { "path": "pkl-codegen-java/pkl-codegen-java.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nplugins {\n pklAllProjects\n pklKotlinLibrary\n pklPublishLibrary\n pklJavaExecutable\n}\n\ndependencies {\n // CliJavaCodeGeneratorOptions exposes CliBaseOptions\n api(projects.pklCommonsCli)\n\n implementation(projects.pklCommons)\n implementation(projects.pklCore)\n implementation(libs.javaPoet)\n\n testImplementation(projects.pklConfigJava)\n testImplementation(projects.pklCommonsTest)\n}\n\nexecutable {\n javaName = \"pkl-codegen-java\"\n documentationName = \"Pkl Codegen Java\"\n javaPublicationName = \"pkl-cli-codegen-java\"\n mainClass = \"org.pkl.codegen.java.Main\"\n website = \"https://pkl-lang.org/main/current/java-binding/codegen.html\"\n}\n\n// with `org.gradle.parallel=true` and without the line below, `test` strangely runs into:\n// java.lang.NoClassDefFoundError: Lorg/pkl/config/java/ConfigEvaluator;\n// perhaps somehow related to InMemoryJavaCompiler?\ntasks.test { mustRunAfter(\":pkl-config-java:testFatJar\") }\n\ntasks.jar { manifest { attributes += mapOf(\"Main-Class\" to \"org.pkl.codegen.java.Main\") } }\n\npublishing {\n publications {\n named(\"library\") {\n pom {\n url.set(\"https://github.com/apple/pkl/tree/main/pkl-codegen-java\")\n description.set(\n \"\"\"\n Java source code generator that generates corresponding Java classes for Pkl classes,\n simplifying consumption of Pkl configuration as statically typed Java objects.\n \"\"\"\n .trimIndent()\n )\n }\n }\n }\n}\n" }, { "path": "pkl-codegen-java/src/main/kotlin/org/pkl/codegen/java/CliJavaCodeGenerator.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.codegen.java\n\nimport java.io.IOException\nimport kotlin.io.path.createParentDirectories\nimport org.pkl.commons.cli.CliCommand\nimport org.pkl.commons.cli.CliException\nimport org.pkl.commons.writeString\nimport org.pkl.core.Closeables\nimport org.pkl.core.ModuleSource\n\n/** API for the Java code generator CLI. */\nclass CliJavaCodeGenerator(private val options: CliJavaCodeGeneratorOptions) :\n CliCommand(options.base) {\n\n override fun doRun() {\n val builder = evaluatorBuilder()\n try {\n builder.build().use { evaluator ->\n for (moduleUri in resolvedSourceModules) {\n val schema = evaluator.evaluateSchema(ModuleSource.uri(moduleUri))\n val codeGenerator = JavaCodeGenerator(schema, options.toJavaCodeGeneratorOptions())\n try {\n for ((fileName, fileContents) in codeGenerator.output) {\n val outputFile = options.outputDir.resolve(fileName)\n try {\n outputFile.createParentDirectories().writeString(fileContents)\n } catch (e: IOException) {\n throw CliException(\"I/O error writing file `$outputFile`.\\nCause: ${e.message}\")\n }\n }\n } catch (e: JavaCodeGeneratorException) {\n throw CliException(e.message!!)\n }\n }\n }\n } finally {\n Closeables.closeQuietly(builder.moduleKeyFactories)\n Closeables.closeQuietly(builder.resourceReaders)\n }\n }\n}\n" }, { "path": "pkl-codegen-java/src/main/kotlin/org/pkl/codegen/java/CliJavaCodeGeneratorOptions.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.codegen.java\n\nimport java.nio.file.Path\nimport org.pkl.commons.cli.CliBaseOptions\n\n/** Configuration options for [CliJavaCodeGenerator]. */\ndata class CliJavaCodeGeneratorOptions(\n /** Base options shared between CLI commands. */\n val base: CliBaseOptions,\n\n /** The directory where generated source code is placed. */\n val outputDir: Path,\n\n /** The characters to use for indenting generated source code. */\n val indent: String = \" \",\n\n /** Whether to add a `@Generated` annotation to the types to be generated. */\n val addGeneratedAnnotation: Boolean = false,\n\n /**\n * Whether to generate public getter methods and private/protected fields instead of public\n * fields.\n */\n val generateGetters: Boolean = false,\n\n /** Whether to preserve Pkl doc comments by generating corresponding Javadoc comments. */\n val generateJavadoc: Boolean = false,\n\n /** Whether to generate config classes for use with Spring Boot. */\n val generateSpringBootConfig: Boolean = false,\n\n /**\n * Fully qualified name of the annotation type to use for annotating constructor parameters with\n * their name.\n *\n * The specified annotation type must have a `value` parameter of type [java.lang.String] or the\n * generated code may not compile.\n *\n * If set to `null`, constructor parameters are not annotated. The default value is `null` if\n * [generateSpringBootConfig] is `true` and `\"org.pkl.config.java.mapper.Named\"` otherwise.\n */\n val paramsAnnotation: String? =\n if (generateSpringBootConfig) null else \"org.pkl.config.java.mapper.Named\",\n\n /**\n * Fully qualified name of the annotation type to use for annotating non-null types.\n *\n * The specified annotation type must have a [java.lang.annotation.Target] of\n * [java.lang.annotation.ElementType.TYPE_USE] or the generated code may not compile. If set to\n * `null`, [org.pkl.config.java.mapper.NonNull] will be used.\n */\n val nonNullAnnotation: String? = null,\n\n /** Whether to generate classes that implement [java.io.Serializable]. */\n val implementSerializable: Boolean = false,\n\n /**\n * A rename mapping for class names.\n *\n * When you need to have Java class or package names different from the default names derived from\n * Pkl module names, you can define a rename mapping, where the key is a prefix of the original\n * Pkl module name, and the value is the desired replacement.\n */\n val renames: Map = emptyMap(),\n) {\n @Suppress(\"DeprecatedCallableAddReplaceWith\")\n @Deprecated(\"deprecated without replacement\")\n fun toJavaCodegenOptions() = toJavaCodeGeneratorOptions()\n\n internal fun toJavaCodeGeneratorOptions() =\n JavaCodeGeneratorOptions(\n indent,\n addGeneratedAnnotation,\n generateGetters,\n generateJavadoc,\n generateSpringBootConfig,\n paramsAnnotation,\n nonNullAnnotation,\n implementSerializable,\n renames,\n )\n}\n" }, { "path": "pkl-codegen-java/src/main/kotlin/org/pkl/codegen/java/JavaCodeGenerator.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n@file:Suppress(\"unused\")\n\npackage org.pkl.codegen.java\n\nimport com.palantir.javapoet.*\nimport java.io.StringWriter\nimport java.lang.Deprecated\nimport java.util.*\nimport java.util.regex.Pattern\nimport javax.lang.model.element.Modifier\nimport kotlin.AssertionError\nimport kotlin.Boolean\nimport kotlin.Int\nimport kotlin.Long\nimport kotlin.RuntimeException\nimport kotlin.String\nimport kotlin.Suppress\nimport kotlin.Unit\nimport kotlin.apply\nimport kotlin.let\nimport kotlin.takeIf\nimport kotlin.to\nimport org.pkl.commons.NameMapper\nimport org.pkl.core.*\nimport org.pkl.core.util.CodeGeneratorUtils\nimport org.pkl.core.util.IoUtils\n\nclass JavaCodeGeneratorException(message: String) : RuntimeException(message)\n\n@kotlin.Deprecated(\"renamed to JavaCodeGeneratorOptions\", ReplaceWith(\"JavaCodeGeneratorOptions\"))\ntypealias JavaCodegenOptions = JavaCodeGeneratorOptions\n\ndata class JavaCodeGeneratorOptions(\n /** The characters to use for indenting generated Java code. */\n val indent: String = \" \",\n\n /** Adds the `org.pkl.config.java.Generated` annotation to the classes to be generated. */\n val addGeneratedAnnotation: Boolean = false,\n\n /**\n * Whether to generate public getter methods and protected final fields instead of public final\n * fields.\n */\n val generateGetters: Boolean = false,\n\n /** Whether to preserve Pkl doc comments by generating corresponding Javadoc comments. */\n val generateJavadoc: Boolean = false,\n\n /** Whether to generate config classes for use with Spring Boot. */\n val generateSpringBootConfig: Boolean = false,\n\n /**\n * Fully qualified name of the annotation type to use for annotating constructor parameters with\n * their name.\n *\n * The specified annotation type must have a `value` parameter of type [java.lang.String] or the\n * generated code may not compile.\n *\n * If set to `null`, constructor parameters are not annotated. The default value is `null` if\n * [generateSpringBootConfig] is `true` and `\"org.pkl.config.java.mapper.Named\"` otherwise.\n */\n val paramsAnnotation: String? =\n if (generateSpringBootConfig) null else \"org.pkl.config.java.mapper.Named\",\n\n /**\n * Fully qualified name of the annotation type to use for annotating non-null types.\n *\n * The specified annotation type must have a [java.lang.annotation.Target] of\n * [java.lang.annotation.ElementType.TYPE_USE] or the generated code may not compile. If set to\n * `null`, [org.pkl.config.java.mapper.NonNull] will be used.\n */\n val nonNullAnnotation: String? = null,\n\n /** Whether to generate classes that implement [java.io.Serializable]. */\n val implementSerializable: Boolean = false,\n\n /**\n * A mapping from Pkl module name prefixes to their replacements.\n *\n * Can be used when the class or package name in the generated source code should be different\n * from the corresponding name derived from the Pkl module declaration .\n */\n val renames: Map = emptyMap(),\n)\n\n/** Entrypoint for the Java code generator API. */\nclass JavaCodeGenerator(\n private val schema: ModuleSchema,\n private val codegenOptions: JavaCodeGeneratorOptions,\n) {\n\n companion object {\n private val OBJECT = ClassName.get(Object::class.java)\n private val STRING = ClassName.get(String::class.java)\n private val DURATION = ClassName.get(Duration::class.java)\n private val DURATION_UNIT = ClassName.get(DurationUnit::class.java)\n private val DATA_SIZE = ClassName.get(DataSize::class.java)\n private val DATASIZE_UNIT = ClassName.get(DataSizeUnit::class.java)\n private val PAIR = ClassName.get(Pair::class.java)\n private val COLLECTION = ClassName.get(Collection::class.java)\n private val LIST = ClassName.get(List::class.java)\n private val SET = ClassName.get(Set::class.java)\n private val MAP = ClassName.get(Map::class.java)\n private val PMODULE = ClassName.get(PModule::class.java)\n private val PCLASS = ClassName.get(PClass::class.java)\n private val PATTERN = ClassName.get(Pattern::class.java)\n private val URI = ClassName.get(java.net.URI::class.java)\n private val VERSION = ClassName.get(Version::class.java)\n\n private const val PROPERTY_PREFIX: String = \"org.pkl.config.java.mapper.\"\n\n private fun toClassName(fqn: String): ClassName {\n val index = fqn.lastIndexOf(\".\")\n if (index == -1) {\n throw JavaCodeGeneratorException(\n \"\"\"\n Annotation `$fqn` is not a valid Java class.\n The name of the annotation should be the canonical Java name of the class, for example, `com.example.Foo`.\n \"\"\"\n .trimIndent()\n )\n }\n val packageName = fqn.substring(0, index)\n val classParts = fqn.substring(index + 1).split('$')\n return if (classParts.size == 1) {\n ClassName.get(packageName, classParts.first())\n } else {\n ClassName.get(packageName, classParts.first(), *classParts.drop(1).toTypedArray())\n }\n }\n }\n\n val output: Map\n get() {\n return mapOf(javaFileName to javaFile, propertyFileName to propertiesFile)\n }\n\n private val propertyFileName: String\n get() =\n \"resources/META-INF/org/pkl/config/java/mapper/classes/${IoUtils.encodePath(schema.moduleName)}.properties\"\n\n private val propertiesFile: String\n get() {\n val props = Properties()\n props[\"$PROPERTY_PREFIX${schema.moduleClass.qualifiedName}\"] =\n schema.moduleClass.toJavaPoetName().reflectionName()\n for (pClass in schema.classes.values) {\n props[\"$PROPERTY_PREFIX${pClass.qualifiedName}\"] = pClass.toJavaPoetName().reflectionName()\n }\n return StringWriter()\n .apply { props.store(this, \"Java mappings for Pkl module `${schema.moduleName}`\") }\n .toString()\n }\n\n private val nonNullAnnotation: AnnotationSpec\n get() {\n val annotation = codegenOptions.nonNullAnnotation\n val className =\n if (annotation == null) {\n ClassName.get(\"org.pkl.config.java.mapper\", \"NonNull\")\n } else {\n toClassName(annotation)\n }\n return AnnotationSpec.builder(className).build()\n }\n\n private val javaFileName: String\n get() {\n val (packageName, className) = nameMapper.map(schema.moduleName)\n val dirPath = packageName.replace('.', '/')\n return if (dirPath.isEmpty()) {\n \"java/$className.java\"\n } else {\n \"java/$dirPath/$className.java\"\n }\n }\n\n val javaFile: String\n get() {\n if (schema.moduleUri.scheme == \"pkl\") {\n throw JavaCodeGeneratorException(\n \"Cannot generate Java code for a Pkl standard library module (`${schema.moduleUri}`).\"\n )\n }\n\n val pModuleClass = schema.moduleClass\n val moduleClass = generateTypeSpec(pModuleClass, schema)\n\n for (pClass in schema.classes.values) {\n moduleClass.addType(generateTypeSpec(pClass, schema).build())\n }\n\n for (typeAlias in schema.typeAliases.values) {\n val stringLiterals = mutableSetOf()\n if (CodeGeneratorUtils.isRepresentableAsEnum(typeAlias.aliasedType, stringLiterals)) {\n moduleClass.addType(generateEnumTypeSpec(typeAlias, stringLiterals).build())\n }\n }\n // generate static append method for module classes w/o parent class; reuse in subclasses and\n // nested classes\n if (pModuleClass.superclass!!.info == PClassInfo.Module) {\n val modifier =\n if (pModuleClass.isOpen || pModuleClass.isAbstract) Modifier.PROTECTED\n else Modifier.PRIVATE\n moduleClass.addMethod(appendPropertyMethod().addModifiers(modifier).build())\n }\n\n val (packageName, _) = nameMapper.map(schema.moduleName)\n\n return JavaFile.builder(packageName, moduleClass.build())\n .indent(codegenOptions.indent)\n .build()\n .toString()\n }\n\n private fun generateTypeSpec(pClass: PClass, schema: ModuleSchema): TypeSpec.Builder {\n val isModuleClass = pClass == schema.moduleClass\n val javaPoetClassName = pClass.toJavaPoetName()\n val superclass =\n pClass.superclass?.takeIf { it.info != PClassInfo.Typed && it.info != PClassInfo.Module }\n val superProperties =\n superclass?.let { renameIfReservedWord(it.allProperties) }?.filterValues { !it.isHidden }\n ?: mapOf()\n val properties = renameIfReservedWord(pClass.properties).filterValues { !it.isHidden }\n val allProperties = superProperties + properties\n\n fun PClass.Property.isRegex(): Boolean =\n (this.type as? PType.Class)?.pClass?.info == PClassInfo.Regex\n\n fun addCtorParameter(\n builder: MethodSpec.Builder,\n propJavaName: String,\n property: PClass.Property,\n ) {\n val paramBuilder = ParameterSpec.builder(property.type.toJavaPoetName(), propJavaName)\n if (paramsAnnotationName != null) {\n paramBuilder.addAnnotation(\n AnnotationSpec.builder(paramsAnnotationName)\n .addMember(\"value\", \"\\$S\", property.simpleName)\n .build()\n )\n }\n builder.addParameter(paramBuilder.build())\n }\n\n fun generateConstructor(isInstantiable: Boolean): MethodSpec {\n val builder =\n MethodSpec.constructorBuilder()\n // choose most restrictive access modifier possible\n .addModifiers(\n when {\n isInstantiable -> Modifier.PUBLIC\n pClass.isAbstract || pClass.isOpen -> Modifier.PROTECTED\n else -> Modifier.PRIVATE\n }\n )\n\n if (superProperties.isNotEmpty()) {\n for ((name, property) in superProperties) {\n if (properties.containsKey(name)) continue\n addCtorParameter(builder, name, property)\n }\n // $W inserts space or newline (automatic line wrapping)\n val callArgsStr = superProperties.keys.joinToString(\",\\$W\")\n // use kotlin interpolation rather than javapoet $L interpolation\n // as otherwise the $W won't get processed\n builder.addStatement(\"super($callArgsStr)\")\n }\n\n for ((name, property) in properties) {\n addCtorParameter(builder, name, property)\n builder.addStatement(\"this.\\$N = \\$N\", name, name)\n }\n\n return builder.build()\n }\n\n fun generateEqualsMethod(): MethodSpec {\n val builder =\n MethodSpec.methodBuilder(\"equals\")\n .addModifiers(Modifier.PUBLIC)\n .addAnnotation(Override::class.java)\n .addParameter(Object::class.java, \"obj\")\n .returns(Boolean::class.java)\n .addStatement(\"if (this == obj) return true\")\n .addStatement(\"if (obj == null) return false\")\n // generating this.getClass() instead of class literal avoids a SpotBugs warning\n .addStatement(\"if (this.getClass() != obj.getClass()) return false\")\n .addStatement(\"\\$T other = (\\$T) obj\", javaPoetClassName, javaPoetClassName)\n\n for ((propertyName, property) in allProperties) {\n val accessor = if (property.isRegex()) \"\\$N.pattern()\" else \"\\$N\"\n builder.addStatement(\n \"if (!\\$T.equals(this.$accessor, other.$accessor)) return false\",\n Objects::class.java,\n propertyName,\n propertyName,\n )\n }\n\n builder.addStatement(\"return true\")\n return builder.build()\n }\n\n fun generateHashCodeMethod(): MethodSpec {\n val builder =\n MethodSpec.methodBuilder(\"hashCode\")\n .addModifiers(Modifier.PUBLIC)\n .addAnnotation(Override::class.java)\n .returns(Int::class.java)\n .addStatement(\"int result = 1\")\n\n for ((propertyName, property) in allProperties) {\n val accessor = if (property.isRegex()) \"this.\\$N.pattern()\" else \"this.\\$N\"\n builder.addStatement(\n \"result = 31 * result + \\$T.hashCode($accessor)\",\n Objects::class.java,\n propertyName,\n )\n }\n\n builder.addStatement(\"return result\")\n return builder.build()\n }\n\n fun generateToStringMethod(): MethodSpec {\n val builder =\n MethodSpec.methodBuilder(\"toString\")\n .addModifiers(Modifier.PUBLIC)\n .addAnnotation(Override::class.java)\n .returns(String::class.java)\n\n var builderSize = 50\n val appendBuilder = CodeBlock.builder()\n for ((propertyName, property) in allProperties) {\n builderSize += 50\n if (property.type.isBytesClass) {\n appendBuilder.addStatement(\n \"appendProperty(builder, \\$S, \\$T.toString(this.\\$N))\",\n propertyName,\n Arrays::class.java,\n propertyName,\n )\n } else {\n appendBuilder.addStatement(\n \"appendProperty(builder, \\$S, this.\\$N)\",\n propertyName,\n propertyName,\n )\n }\n }\n\n builder\n .addStatement(\n \"\\$T builder = new \\$T(\\$L)\",\n StringBuilder::class.java,\n StringBuilder::class.java,\n builderSize,\n )\n .addStatement(\"builder.append(\\$T.class.getSimpleName()).append(\\\" {\\\")\", javaPoetClassName)\n .addCode(appendBuilder.build())\n // not using $S here because it generates `\"\\n\" + \"{\"`\n // with a line break in the generated code after `+`\n .addStatement(\"builder.append(\\\"\\\\n}\\\")\")\n .addStatement(\"return builder.toString()\")\n\n return builder.build()\n }\n\n // do the minimum work necessary to avoid (most) java compile errors\n // generating idiomatic Javadoc would require parsing doc comments, converting member links,\n // etc.\n fun renderAsJavadoc(docComment: String): String {\n val escaped = docComment.replace(\"*/\", \"*/\")\n return if (escaped[escaped.length - 1] != '\\n') escaped + '\\n' else escaped\n }\n\n fun generateDeprecation(\n annotations: Collection,\n hasJavadoc: Boolean,\n addAnnotation: (Class<*>) -> Unit,\n addJavadoc: (String) -> Unit,\n ) {\n annotations\n .firstOrNull { it.classInfo == PClassInfo.Deprecated }\n ?.let { deprecation ->\n addAnnotation(Deprecated::class.java)\n if (codegenOptions.generateJavadoc) {\n (deprecation[\"message\"] as String?)?.let {\n if (hasJavadoc) {\n addJavadoc(\"\\n\")\n }\n addJavadoc(renderAsJavadoc(\"@deprecated $it\"))\n }\n }\n }\n }\n\n fun generateField(propertyName: String, property: PClass.Property): FieldSpec {\n val builder = FieldSpec.builder(property.type.toJavaPoetName(), propertyName)\n\n val docComment = property.docComment\n val hasJavadoc =\n docComment != null && codegenOptions.generateJavadoc && !codegenOptions.generateGetters\n if (hasJavadoc) {\n builder.addJavadoc(renderAsJavadoc(docComment!!))\n }\n\n if (codegenOptions.generateGetters) {\n builder.addModifiers(\n if (pClass.isAbstract || pClass.isOpen) Modifier.PROTECTED else Modifier.PRIVATE\n )\n } else {\n generateDeprecation(\n property.annotations,\n hasJavadoc,\n { builder.addAnnotation(it) },\n { builder.addJavadoc(it) },\n )\n builder.addModifiers(Modifier.PUBLIC)\n }\n builder.addModifiers(Modifier.FINAL)\n\n return builder.build()\n }\n\n @Suppress(\"DuplicatedCode\")\n fun generateGetter(\n propertyName: String,\n property: PClass.Property,\n isOverridden: Boolean,\n ): MethodSpec {\n val propertyType = property.type\n val isBooleanProperty =\n propertyType is PType.Class && propertyType.pClass.info == PClassInfo.Boolean\n val methodName =\n (if (isBooleanProperty) \"is\" else \"get\") +\n // can use original name here (property.name rather than propertyName)\n // because getter name cannot possibly conflict with reserved words\n property.simpleName.replaceFirstChar { it.titlecaseChar() }\n\n val builder =\n MethodSpec.methodBuilder(methodName)\n .addModifiers(Modifier.PUBLIC)\n .returns(propertyType.toJavaPoetName())\n .addStatement(\"return \\$N\", propertyName)\n if (isOverridden) {\n builder.addAnnotation(Override::class.java)\n }\n\n val docComment = property.docComment\n val hasJavadoc = docComment != null && codegenOptions.generateJavadoc\n if (hasJavadoc) {\n builder.addJavadoc(renderAsJavadoc(docComment!!))\n }\n\n generateDeprecation(\n property.annotations,\n hasJavadoc,\n { builder.addAnnotation(it) },\n { builder.addJavadoc(it) },\n )\n\n return builder.build()\n }\n\n fun generateWithMethod(propertyName: String, property: PClass.Property): MethodSpec {\n val methodName = \"with\" + property.simpleName.replaceFirstChar { it.titlecaseChar() }\n\n val methodBuilder =\n MethodSpec.methodBuilder(methodName)\n .addModifiers(Modifier.PUBLIC)\n .addParameter(property.type.toJavaPoetName(), propertyName)\n .returns(javaPoetClassName)\n\n generateDeprecation(\n property.annotations,\n false,\n { methodBuilder.addAnnotation(it) },\n { methodBuilder.addJavadoc(it) },\n )\n\n val codeBuilder = CodeBlock.builder()\n codeBuilder.add(\"return new \\$T(\", javaPoetClassName)\n var firstProperty = true\n for (name in superProperties.keys) {\n if (name in properties) continue\n if (firstProperty) {\n firstProperty = false\n codeBuilder.add(\"\\$N\", name)\n } else {\n codeBuilder.add(\", \\$N\", name)\n }\n }\n for (name in properties.keys) {\n if (firstProperty) {\n firstProperty = false\n codeBuilder.add(\"\\$N\", name)\n } else {\n codeBuilder.add(\", \\$N\", name)\n }\n }\n codeBuilder.add(\");\\n\")\n\n methodBuilder.addCode(codeBuilder.build())\n return methodBuilder.build()\n }\n\n fun generateSpringBootAnnotations(builder: TypeSpec.Builder) {\n if (isModuleClass) {\n builder.addAnnotation(\n ClassName.get(\"org.springframework.boot.context.properties\", \"ConfigurationProperties\")\n )\n } else {\n // not very efficient to repeat computing module property base types for every class\n val modulePropertiesWithMatchingType =\n schema.moduleClass.allProperties.values.filter { property ->\n var propertyType = property.type\n while (propertyType is PType.Constrained || propertyType is PType.Nullable) {\n if (propertyType is PType.Constrained) {\n propertyType = propertyType.baseType\n } else if (propertyType is PType.Nullable) {\n propertyType = propertyType.baseType\n }\n }\n propertyType is PType.Class && propertyType.pClass == pClass\n }\n if (modulePropertiesWithMatchingType.size == 1) {\n // exactly one module property has this type -> make it available for direct injection\n // (potential improvement: make type available for direct injection if it occurs exactly\n // once in property tree)\n builder.addAnnotation(\n AnnotationSpec.builder(\n ClassName.get(\n \"org.springframework.boot.context.properties\",\n \"ConfigurationProperties\",\n )\n )\n // use \"value\" instead of \"prefix\" to entice JavaPoet to generate a single-line\n // annotation\n // that can easily be filtered out by JavaCodeGeneratorTest.`spring boot config`\n .addMember(\"value\", \"\\$S\", modulePropertiesWithMatchingType.first().simpleName)\n .build()\n )\n }\n }\n }\n\n @Suppress(\"DuplicatedCode\")\n fun generateClass(): TypeSpec.Builder {\n val builder =\n TypeSpec.classBuilder(javaPoetClassName.simpleName()).addModifiers(Modifier.PUBLIC)\n if (codegenOptions.addGeneratedAnnotation) {\n val name = ClassName.get(\"org.pkl.config.java\", \"Generated\")\n val generated = AnnotationSpec.builder(name).build()\n builder.addAnnotation(generated)\n }\n\n // stateless final module classes are non-instantiable by choice\n val isInstantiable =\n !(pClass.isAbstract || (isModuleClass && !pClass.isOpen && allProperties.isEmpty()))\n\n if (codegenOptions.implementSerializable && isInstantiable) {\n builder.addSuperinterface(java.io.Serializable::class.java)\n builder.addField(generateSerialVersionUIDField())\n }\n\n val docComment = pClass.docComment\n val hasJavadoc = docComment != null && codegenOptions.generateJavadoc\n if (hasJavadoc) {\n builder.addJavadoc(renderAsJavadoc(docComment!!))\n }\n\n generateDeprecation(\n pClass.annotations,\n hasJavadoc,\n { builder.addAnnotation(it) },\n { builder.addJavadoc(it) },\n )\n\n if (!isModuleClass) {\n builder.addModifiers(Modifier.STATIC)\n }\n\n if (pClass.isAbstract) {\n builder.addModifiers(Modifier.ABSTRACT)\n } else if (!pClass.isOpen) {\n builder.addModifiers(Modifier.FINAL)\n }\n\n if (codegenOptions.generateSpringBootConfig) {\n generateSpringBootAnnotations(builder)\n }\n\n builder.addMethod(generateConstructor(isInstantiable))\n\n superclass?.let { builder.superclass(it.toJavaPoetName()) }\n\n // generate fields, plus getter methods and either setters or `with` methods in alternating\n // order\n // `with` methods also need to be generated for superclass properties so that return type is\n // self type\n for ((name, property) in allProperties) {\n if (name in properties) {\n builder.addField(generateField(name, property))\n if (codegenOptions.generateGetters) {\n val isOverridden = name in superProperties\n builder.addMethod(generateGetter(name, property, isOverridden))\n }\n }\n if (isInstantiable) {\n builder.addMethod(generateWithMethod(name, property))\n }\n }\n\n if (isInstantiable) {\n builder\n .addMethod(generateEqualsMethod())\n .addMethod(generateHashCodeMethod())\n .addMethod(generateToStringMethod())\n }\n\n return builder\n }\n\n return generateClass()\n }\n\n private fun generateSerialVersionUIDField(): FieldSpec {\n return FieldSpec.builder(Long::class.java, \"serialVersionUID\", Modifier.PRIVATE)\n .addModifiers(Modifier.STATIC, Modifier.FINAL)\n .initializer(\"0L\")\n .build()\n }\n\n private fun generateEnumTypeSpec(\n typeAlias: TypeAlias,\n stringLiterals: Set,\n ): TypeSpec.Builder {\n val enumConstantToPklNames =\n stringLiterals\n .groupingBy { literal ->\n CodeGeneratorUtils.toEnumConstantName(literal)\n ?: throw JavaCodeGeneratorException(\n \"Cannot generate Java enum class for Pkl type alias `${typeAlias.displayName}` \" +\n \"because string literal type \\\"$literal\\\" cannot be converted to a valid enum constant name.\"\n )\n }\n .reduce { enumConstantName, firstLiteral, secondLiteral ->\n throw JavaCodeGeneratorException(\n \"Cannot generate Java enum class for Pkl type alias `${typeAlias.displayName}` \" +\n \"because string literal types \\\"$firstLiteral\\\" and \\\"$secondLiteral\\\" \" +\n \"would both be converted to enum constant name `$enumConstantName`.\"\n )\n }\n\n val builder =\n TypeSpec.enumBuilder(typeAlias.simpleName)\n .addModifiers(Modifier.PUBLIC)\n .addField(String::class.java, \"value\", Modifier.PRIVATE)\n .addMethod(\n MethodSpec.constructorBuilder()\n .addModifiers(Modifier.PRIVATE)\n .addParameter(String::class.java, \"value\")\n .addStatement(\"this.value = value\")\n .build()\n )\n .addMethod(\n MethodSpec.methodBuilder(\"toString\")\n .addModifiers(Modifier.PUBLIC)\n .addAnnotation(Override::class.java)\n .returns(String::class.java)\n .addStatement(\"return this.value\")\n .build()\n )\n\n for ((enumConstantName, pklName) in enumConstantToPklNames) {\n builder.addEnumConstant(\n enumConstantName,\n TypeSpec.anonymousClassBuilder(\"\\$S\", pklName).build(),\n )\n }\n\n return builder\n }\n\n private val paramsAnnotationName: ClassName? =\n codegenOptions.paramsAnnotation?.let { toClassName(it) }\n\n private fun appendPropertyMethod() =\n MethodSpec.methodBuilder(\"appendProperty\")\n .addModifiers(Modifier.STATIC)\n .addParameter(StringBuilder::class.java, \"builder\")\n .addParameter(String::class.java, \"name\")\n .addParameter(Object::class.java, \"value\")\n .addStatement(\"builder.append(\\\"\\\\n \\\").append(name).append(\\\" = \\\")\")\n .addStatement(\n \"\\$T lines = \\$T.toString(value).split(\\\"\\\\n\\\")\",\n ArrayTypeName.of(String::class.java),\n Objects::class.java,\n )\n .addStatement(\"builder.append(lines[0])\")\n .beginControlFlow(\"for (int i = 1; i < lines.length; i++)\")\n .addStatement(\"builder.append(\\\"\\\\n \\\").append(lines[i])\")\n .endControlFlow()\n\n private fun PClass.toJavaPoetName(): ClassName {\n val (packageName, moduleClassName) = nameMapper.map(moduleName)\n return if (isModuleClass) {\n ClassName.get(packageName, moduleClassName)\n } else {\n ClassName.get(packageName, moduleClassName, simpleName)\n }\n }\n\n // generated type is a nested enum class\n private fun TypeAlias.toJavaPoetName(): ClassName {\n val (packageName, moduleClassName) = nameMapper.map(moduleName)\n return ClassName.get(packageName, moduleClassName, simpleName)\n }\n\n /** Generate `List` if `Foo` is `abstract` or `open`, to allow subclassing. */\n private fun PType.toJavaPoetTypeArgumentName(): TypeName {\n val baseName = toJavaPoetName(boxed = true)\n return if (this is PType.Class && (pClass.isAbstract || pClass.isOpen)) {\n WildcardTypeName.subtypeOf(baseName)\n } else {\n baseName\n }\n }\n\n private val PType.isBytesClass: Boolean\n get() = this is PType.Class && this.pClass.info == PClassInfo.Bytes\n\n private fun PType.toJavaPoetName(nullable: Boolean = false, boxed: Boolean = false): TypeName =\n when (this) {\n PType.UNKNOWN -> OBJECT.nullableIf(nullable)\n PType.NOTHING -> TypeName.VOID\n is PType.StringLiteral -> STRING.nullableIf(nullable)\n is PType.Class -> {\n // if in doubt, spell it out\n when (val classInfo = pClass.info) {\n PClassInfo.Any -> OBJECT\n PClassInfo.Typed,\n PClassInfo.Dynamic -> OBJECT.nullableIf(nullable)\n PClassInfo.Boolean -> TypeName.BOOLEAN.boxIf(boxed).nullableIf(nullable)\n PClassInfo.String -> STRING.nullableIf(nullable)\n // seems more useful to generate `double` than `java.lang.Number`\n PClassInfo.Number -> TypeName.DOUBLE.boxIf(boxed).nullableIf(nullable)\n PClassInfo.Int -> TypeName.LONG.boxIf(boxed).nullableIf(nullable)\n PClassInfo.Float -> TypeName.DOUBLE.boxIf(boxed).nullableIf(nullable)\n PClassInfo.Duration -> DURATION.nullableIf(nullable)\n PClassInfo.DataSize -> DATA_SIZE.nullableIf(nullable)\n PClassInfo.Bytes -> ArrayTypeName.of(TypeName.BYTE)\n PClassInfo.Pair ->\n ParameterizedTypeName.get(\n PAIR,\n if (typeArguments.isEmpty()) {\n OBJECT\n } else {\n typeArguments[0].toJavaPoetTypeArgumentName()\n },\n if (typeArguments.isEmpty()) {\n OBJECT\n } else {\n typeArguments[1].toJavaPoetTypeArgumentName()\n },\n )\n .nullableIf(nullable)\n PClassInfo.Collection ->\n ParameterizedTypeName.get(\n COLLECTION,\n if (typeArguments.isEmpty()) {\n OBJECT\n } else {\n typeArguments[0].toJavaPoetTypeArgumentName()\n },\n )\n .nullableIf(nullable)\n PClassInfo.List,\n PClassInfo.Listing -> {\n ParameterizedTypeName.get(\n LIST,\n if (typeArguments.isEmpty()) {\n OBJECT\n } else {\n typeArguments[0].toJavaPoetTypeArgumentName()\n },\n )\n .nullableIf(nullable)\n }\n PClassInfo.Set ->\n ParameterizedTypeName.get(\n SET,\n if (typeArguments.isEmpty()) {\n OBJECT\n } else {\n typeArguments[0].toJavaPoetTypeArgumentName()\n },\n )\n .nullableIf(nullable)\n PClassInfo.Map,\n PClassInfo.Mapping ->\n ParameterizedTypeName.get(\n MAP,\n if (typeArguments.isEmpty()) {\n OBJECT\n } else {\n typeArguments[0].toJavaPoetTypeArgumentName()\n },\n if (typeArguments.isEmpty()) {\n OBJECT\n } else {\n typeArguments[1].toJavaPoetTypeArgumentName()\n },\n )\n .nullableIf(nullable)\n PClassInfo.Module -> PMODULE.nullableIf(nullable)\n PClassInfo.Class -> PCLASS.nullableIf(nullable)\n PClassInfo.Regex -> PATTERN.nullableIf(nullable)\n PClassInfo.Version -> VERSION.nullableIf(nullable)\n else ->\n when {\n !classInfo.isStandardLibraryClass -> pClass.toJavaPoetName().nullableIf(nullable)\n else ->\n throw JavaCodeGeneratorException(\n \"Standard library class `${pClass.qualifiedName}` is not supported by Java code generator. \" +\n \"If you think this is an omission, please let us know.\"\n )\n }\n }\n }\n is PType.Nullable -> baseType.toJavaPoetName(nullable = true, boxed = true)\n is PType.Constrained -> baseType.toJavaPoetName(nullable = nullable, boxed = boxed)\n is PType.Alias ->\n when (typeAlias.qualifiedName) {\n \"pkl.base#NonNull\" -> OBJECT.nullableIf(nullable)\n \"pkl.base#Int8\" -> TypeName.BYTE.boxIf(boxed).nullableIf(nullable)\n \"pkl.base#Int16\",\n \"pkl.base#UInt8\" -> TypeName.SHORT.boxIf(boxed).nullableIf(nullable)\n \"pkl.base#Int32\",\n \"pkl.base#UInt16\" -> TypeName.INT.boxIf(boxed).nullableIf(nullable)\n \"pkl.base#UInt\",\n \"pkl.base#UInt32\" -> TypeName.LONG.boxIf(boxed).nullableIf(nullable)\n \"pkl.base#DurationUnit\" -> DURATION_UNIT.nullableIf(nullable)\n \"pkl.base#DataSizeUnit\" -> DATASIZE_UNIT.nullableIf(nullable)\n \"pkl.base#Uri\" -> URI.nullableIf(nullable)\n else -> {\n if (CodeGeneratorUtils.isRepresentableAsEnum(aliasedType, null)) {\n if (typeAlias.isStandardLibraryMember) {\n throw JavaCodeGeneratorException(\n \"Standard library typealias `${typeAlias.qualifiedName}` is not supported by Java code generator. \" +\n \"If you think this is an omission, please let us know.\"\n )\n } else {\n // reference generated enum class\n typeAlias.toJavaPoetName().nullableIf(nullable)\n }\n } else {\n // inline type alias\n aliasedType.toJavaPoetName(nullable)\n }\n }\n }\n is PType.Function ->\n throw JavaCodeGeneratorException(\n \"Pkl function types are not supported by the Java code generator.\"\n )\n is PType.Union ->\n if (CodeGeneratorUtils.isRepresentableAsString(this)) STRING.nullableIf(nullable)\n else\n throw JavaCodeGeneratorException(\n \"Pkl union types are not supported by the Java code generator.\"\n )\n else ->\n // should never encounter PType.TypeVariableNode because it can only occur in stdlib classes\n throw AssertionError(\"Encountered unexpected PType subclass: $this\")\n }\n\n private fun TypeName.nullableIf(isNullable: Boolean): TypeName =\n if (isPrimitive && isNullable) box()\n else if (isPrimitive || isNullable) this else annotated(nonNullAnnotation)\n\n private fun TypeName.boxIf(shouldBox: Boolean): TypeName = if (shouldBox) box() else this\n\n private fun renameIfReservedWord(map: Map): Map {\n return map.mapKeys { (key, _) ->\n if (key in javaReservedWords) {\n generateSequence(\"_$key\") { \"_$it\" }.first { it !in map.keys }\n } else key\n }\n }\n\n private val nameMapper = NameMapper(codegenOptions.renames)\n}\n\ninternal val javaReservedWords =\n setOf(\n \"_\", // java 9+\n \"abstract\",\n \"assert\",\n \"boolean\",\n \"break\",\n \"byte\",\n \"case\",\n \"catch\",\n \"char\",\n \"class\",\n \"const\",\n \"continue\",\n \"default\",\n \"double\",\n \"do\",\n \"else\",\n \"enum\",\n \"extends\",\n \"false\",\n \"final\",\n \"finally\",\n \"float\",\n \"for\",\n \"goto\",\n \"if\",\n \"implements\",\n \"import\",\n \"instanceof\",\n \"int\",\n \"interface\",\n \"long\",\n \"native\",\n \"new\",\n \"null\",\n \"package\",\n \"private\",\n \"protected\",\n \"public\",\n \"return\",\n \"short\",\n \"static\",\n \"strictfp\",\n \"super\",\n \"switch\",\n \"synchronized\",\n \"this\",\n \"throw\",\n \"throws\",\n \"transient\",\n \"true\",\n \"try\",\n \"void\",\n \"volatile\",\n \"while\",\n )\n" }, { "path": "pkl-codegen-java/src/main/kotlin/org/pkl/codegen/java/Main.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n@file:JvmName(\"Main\")\n\npackage org.pkl.codegen.java\n\nimport com.github.ajalt.clikt.core.main\nimport com.github.ajalt.clikt.parameters.options.*\nimport com.github.ajalt.clikt.parameters.types.path\nimport java.nio.file.Path\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.cliMain\nimport org.pkl.commons.cli.commands.ModulesCommand\nimport org.pkl.commons.cli.commands.installCommonOptions\nimport org.pkl.commons.toPath\nimport org.pkl.core.Release\n\n/** Main method for the Java code generator CLI. */\ninternal fun main(args: Array) {\n cliMain { PklJavaCodegenCommand().main(args) }\n}\n\ninternal val helpLink = \"${Release.current().documentation.homepage}java-binding/codegen.html#cli\"\n\nclass PklJavaCodegenCommand : ModulesCommand(name = \"pkl-codegen-java\", helpLink) {\n private val defaults = CliJavaCodeGeneratorOptions(CliBaseOptions(), \"\".toPath())\n\n private val outputDir: Path by\n option(\n names = arrayOf(\"-o\", \"--output-dir\"),\n metavar = \"path\",\n help = \"The directory where generated source code is placed.\",\n )\n .path()\n .default(defaults.outputDir)\n\n private val indent: String by\n option(\n names = arrayOf(\"--indent\"),\n metavar = \"chars\",\n help = \"The characters to use for indenting generated source code.\",\n )\n .default(defaults.indent)\n\n private val addGeneratedAnnotation: Boolean by\n option(\n names = arrayOf(\"--add-generated-annotation\"),\n help = \"Whether to add a @Generated annotation to the types to be generated.\",\n )\n .flag()\n\n private val generateGetters: Boolean by\n option(\n names = arrayOf(\"--generate-getters\"),\n help =\n \"Whether to generate public getter methods and \" +\n \"private final fields instead of public final fields.\",\n )\n .flag()\n\n private val generateJavadoc: Boolean by\n option(\n names = arrayOf(\"--generate-javadoc\"),\n help = \"Whether to preserve Pkl doc comments by generating corresponding Javadoc comments.\",\n )\n .flag()\n\n private val generateSpringBoot: Boolean by\n option(\n names = arrayOf(\"--generate-spring-boot\"),\n help = \"Whether to generate config classes for use with Spring Boot.\",\n )\n .flag()\n\n private val paramsAnnotation: String by\n option(\n names = arrayOf(\"--params-annotation\"),\n help =\n \"Fully qualified name of the annotation type to use for annotating constructor parameters with their name.\",\n )\n .defaultLazy(\n \"`none` if `--generate-spring-boot` is set, `org.pkl.config.java.mapper.Named` otherwise\"\n ) {\n if (generateSpringBoot) \"none\" else \"org.pkl.config.java.mapper.Named\"\n }\n\n private val nonNullAnnotation: String? by\n option(\n names = arrayOf(\"--non-null-annotation\"),\n help =\n \"\"\"\n Fully qualified name of the annotation type to use for annotating non-null types.\n The specified annotation type must be annotated with `@java.lang.annotation.Target(ElementType.TYPE_USE)`\n or the generated code may not compile.\n \"\"\"\n .trimIndent(),\n )\n\n private val implementSerializable: Boolean by\n option(\n names = arrayOf(\"--implement-serializable\"),\n help = \"Whether to generate classes that implement java.io.Serializable.\",\n )\n .flag()\n\n private val renames: Map by\n option(\n names = arrayOf(\"--rename\"),\n metavar = \"old_name=new_name\",\n help =\n \"\"\"\n Replace a prefix in the names of the generated Java classes (repeatable).\n By default, the names of generated classes are derived from the Pkl module names.\n With this option, you can override or modify the default names, renaming entire\n classes or just their packages.\n \"\"\"\n .trimIndent(),\n )\n .associate()\n\n override val helpString: String = \"Generate Java classes and interfaces from Pkl module(s)\"\n\n override fun run() {\n val options =\n CliJavaCodeGeneratorOptions(\n base = baseOptions.baseOptions(modules, projectOptions),\n outputDir = outputDir,\n indent = indent,\n addGeneratedAnnotation = addGeneratedAnnotation,\n generateGetters = generateGetters,\n generateJavadoc = generateJavadoc,\n generateSpringBootConfig = generateSpringBoot,\n paramsAnnotation = if (paramsAnnotation == \"none\") null else paramsAnnotation,\n nonNullAnnotation = nonNullAnnotation,\n implementSerializable = implementSerializable,\n renames = renames,\n )\n CliJavaCodeGenerator(options).run()\n }\n\n init {\n installCommonOptions()\n }\n}\n" }, { "path": "pkl-codegen-java/src/test/kotlin/org/pkl/codegen/java/CliJavaCodeGeneratorTest.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.codegen.java\n\nimport java.nio.file.Path\nimport kotlin.io.path.listDirectoryEntries\nimport org.assertj.core.api.Assertions.assertThat\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.io.TempDir\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.readString\n\nclass CliJavaCodeGeneratorTest {\n\n private val dollar = \"$\"\n\n @Test\n fun `module inheritance`(@TempDir tempDir: Path) {\n val module1 =\n PklModule(\n \"org.mod1\",\n \"\"\"\n open module org.mod1\n\n pigeon: Person\n\n class Person {\n name: String\n age: Int\n }\n \"\"\",\n )\n\n val module2 =\n PklModule(\n \"org.mod2\",\n \"\"\"\n module org.mod2\n\n extends \"mod1.pkl\"\n\n parrot: Person\n \"\"\",\n )\n\n val module1File = module1.writeToDisk(tempDir.resolve(\"org/mod1.pkl\"))\n val module2File = module2.writeToDisk(tempDir.resolve(\"org/mod2.pkl\"))\n val outputDir = tempDir.resolve(\"output\")\n\n val generator =\n CliJavaCodeGenerator(\n CliJavaCodeGeneratorOptions(\n CliBaseOptions(listOf(module1File.toUri(), module2File.toUri())),\n outputDir,\n )\n )\n\n generator.run()\n\n val javaDir = outputDir.resolve(\"java\")\n\n val moduleJavaFiles = javaDir.resolve(\"org\").listDirectoryEntries()\n assertThat(moduleJavaFiles.map { it.fileName.toString() })\n .containsExactlyInAnyOrder(\"Mod1.java\", \"Mod2.java\")\n\n val module1JavaFile = javaDir.resolve(\"org/Mod1.java\")\n assertContains(\n \"\"\"\n |public class Mod1 {\n | public final @NonNull Person pigeon;\n \"\"\",\n module1JavaFile.readString(),\n )\n\n val module2JavaFile = javaDir.resolve(\"org/Mod2.java\")\n assertContains(\n \"\"\"\n |public final class Mod2 extends Mod1 {\n | public final Mod1. @NonNull Person parrot;\n \"\"\",\n module2JavaFile.readString(),\n )\n val resourcesDir = outputDir.resolve(\"resources/META-INF/org/pkl/config/java/mapper/classes/\")\n\n val module1PropertiesFile = resourcesDir.resolve(\"org.mod1.properties\")\n\n val module1PropertiesString = module1PropertiesFile.readString()\n // use two assertions because java.util.Properties doesn't guarantee order\n assertContains(\n \"\"\"org.pkl.config.java.mapper.org.mod1\\#Person=org.Mod1${dollar}Person\"\"\",\n module1PropertiesString,\n )\n assertContains(\n \"\"\"org.pkl.config.java.mapper.org.mod1\\#ModuleClass=org.Mod1\"\"\",\n module1PropertiesString,\n )\n\n val module2PropertiesFile = resourcesDir.resolve(\"org.mod2.properties\")\n\n assertContains(\n \"\"\"org.pkl.config.java.mapper.org.mod2\\#ModuleClass=org.Mod2\"\"\",\n module2PropertiesFile.readString(),\n )\n }\n\n @Test\n fun `class name clashes`(@TempDir tempDir: Path) {\n val module1 =\n PklModule(\n \"org.mod1\",\n \"\"\"\n module org.mod1\n\n class Person {\n name: String\n }\n \"\"\",\n )\n\n val module2 =\n PklModule(\n \"org.mod2\",\n \"\"\"\n module org.mod2\n\n import \"mod1.pkl\"\n\n person1: mod1.Person\n person2: Person\n\n class Person {\n age: Int\n }\n \"\"\",\n )\n\n val module1PklFile = module1.writeToDisk(tempDir.resolve(\"org/mod1.pkl\"))\n val module2PklFile = module2.writeToDisk(tempDir.resolve(\"org/mod2.pkl\"))\n val outputDir = tempDir.resolve(\"output\")\n\n val generator =\n CliJavaCodeGenerator(\n CliJavaCodeGeneratorOptions(\n CliBaseOptions(listOf(module1PklFile.toUri(), module2PklFile.toUri())),\n outputDir,\n )\n )\n\n generator.run()\n\n val module2JavaFile = outputDir.resolve(\"java/org/Mod2.java\")\n assertContains(\n \"\"\"\n |public final class Mod2 {\n | public final Mod1. @NonNull Person person1;\n |\n | public final @NonNull Person person2;\n \"\"\",\n module2JavaFile.readString(),\n )\n }\n\n @Test\n fun `custom package names`(@TempDir tempDir: Path) {\n val module1 =\n PklModule(\n \"org.foo.Module1\",\n \"\"\"\n module org.foo.Module1\n\n class Person {\n name: String\n }\n \"\"\",\n )\n\n val module2 =\n PklModule(\n \"org.bar.Module2\",\n \"\"\"\n module org.bar.Module2\n \n import \"../../org/foo/Module1.pkl\"\n\n class Group {\n owner: Module1.Person\n name: String\n }\n \"\"\",\n )\n\n val module3 =\n PklModule(\n \"org.baz.Module3\",\n \"\"\"\n module org.baz.Module3\n \n import \"../../org/bar/Module2.pkl\"\n\n class Supergroup {\n owner: Module2.Group\n }\n \"\"\",\n )\n\n val module1PklFile = module1.writeToDisk(tempDir.resolve(\"org/foo/Module1.pkl\"))\n val module2PklFile = module2.writeToDisk(tempDir.resolve(\"org/bar/Module2.pkl\"))\n val module3PklFile = module3.writeToDisk(tempDir.resolve(\"org/baz/Module3.pkl\"))\n val outputDir = tempDir.resolve(\"output\")\n\n val generator =\n CliJavaCodeGenerator(\n CliJavaCodeGeneratorOptions(\n CliBaseOptions(listOf(module1PklFile, module2PklFile, module3PklFile).map { it.toUri() }),\n outputDir,\n renames = mapOf(\"org.foo\" to \"com.foo.x\", \"org.baz\" to \"com.baz.a.b\"),\n )\n )\n\n generator.run()\n\n val module1JavaFile = outputDir.resolve(\"java/com/foo/x/Module1.java\")\n module1JavaFile.readString().let {\n assertContains(\"package com.foo.x;\", it)\n\n assertContains(\"public final class Module1 {\", it)\n\n assertContains(\n \"\"\"\n | public static final class Person {\n | public final @NonNull String name;\n \"\"\",\n it,\n )\n }\n\n val module2JavaFile = outputDir.resolve(\"java/org/bar/Module2.java\")\n module2JavaFile.readString().let {\n assertContains(\"package org.bar;\", it)\n\n assertContains(\"import com.foo.x.Module1;\", it)\n\n assertContains(\"public final class Module2 {\", it)\n\n assertContains(\n \"\"\"\n | public static final class Group {\n | public final Module1. @NonNull Person owner;\n \"\"\",\n it,\n )\n }\n\n val module3JavaFile = outputDir.resolve(\"java/com/baz/a/b/Module3.java\")\n module3JavaFile.readString().let {\n assertContains(\"package com.baz.a.b;\", it)\n\n assertContains(\"import org.bar.Module2;\", it)\n\n assertContains(\"public final class Module3 {\", it)\n\n assertContains(\n \"\"\"\n | public static final class Supergroup {\n | public final Module2. @NonNull Group owner;\n \"\"\",\n it,\n )\n }\n }\n\n private fun assertContains(part: String, code: String) {\n val trimmedPart = part.trim().trimMargin()\n if (!code.contains(trimmedPart)) {\n // check for equality to get better error output (ide diff dialog)\n assertThat(code).isEqualTo(trimmedPart)\n }\n }\n}\n" }, { "path": "pkl-codegen-java/src/test/kotlin/org/pkl/codegen/java/InMemoryJavaCompiler.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.codegen.java\n\nimport java.io.ByteArrayOutputStream\nimport java.io.InputStream\nimport java.io.OutputStream\nimport java.net.URI\nimport javax.tools.*\n\nclass CompilationFailedException(msg: String) : RuntimeException(msg)\n\nobject InMemoryJavaCompiler {\n fun compile(sourceFiles: Map): Map> {\n val compiler = ToolProvider.getSystemJavaCompiler()\n val diagnosticsCollector = DiagnosticCollector()\n val fileManager =\n InMemoryFileManager(compiler.getStandardFileManager(diagnosticsCollector, null, null))\n val sourceObjects =\n sourceFiles\n .filter { (filename, _) -> filename.endsWith(\".java\") }\n .map { (filename, contents) -> ReadableSourceFileObject(filename, contents) }\n val task = compiler.getTask(null, fileManager, diagnosticsCollector, null, null, sourceObjects)\n val result = task.call()\n if (!result) {\n throw CompilationFailedException(\n buildString {\n appendLine(\"Compilation failed. Error(s):\")\n for (diagnostic in diagnosticsCollector.diagnostics) {\n appendLine(diagnostic.getMessage(null))\n }\n }\n )\n }\n val loader = ClassFileObjectLoader(fileManager.outputFiles)\n return fileManager.outputFiles.mapValues { loader.loadClass(it.key) }\n }\n}\n\nprivate class ClassFileObjectLoader(val fileObjects: Map) :\n ClassLoader(ClassFileObjectLoader::class.java.classLoader) {\n\n override fun findClass(name: String): Class<*> {\n val obj = fileObjects[name]\n if (obj == null || obj.kind != JavaFileObject.Kind.CLASS) {\n throw ClassNotFoundException(name)\n }\n val array = obj.out.toByteArray()\n return defineClass(name, array, 0, array.size)\n }\n}\n\nprivate class ReadableSourceFileObject(path: String, private val contents: String) :\n SimpleJavaFileObject(URI(path), JavaFileObject.Kind.SOURCE) {\n\n override fun openInputStream(): InputStream = contents.byteInputStream()\n\n override fun getCharContent(ignoreEncodingErrors: Boolean): CharSequence = contents\n}\n\nprivate class WritableBinaryFileObject(className: String, kind: JavaFileObject.Kind) :\n SimpleJavaFileObject(URI(\"/${className.replace(\".\", \"/\")}.${kind.extension}\"), kind) {\n val out = ByteArrayOutputStream()\n\n override fun openOutputStream(): OutputStream = out\n}\n\nprivate class InMemoryFileManager(delegate: JavaFileManager) :\n ForwardingJavaFileManager(delegate) {\n\n val outputFiles = mutableMapOf()\n\n override fun getJavaFileForOutput(\n location: JavaFileManager.Location,\n className: String,\n kind: JavaFileObject.Kind,\n sibling: FileObject,\n ): JavaFileObject {\n\n return WritableBinaryFileObject(className, kind).also { outputFiles[className] = it }\n }\n}\n" }, { "path": "pkl-codegen-java/src/test/kotlin/org/pkl/codegen/java/JavaCodeGeneratorTest.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.codegen.java\n\nimport java.io.*\nimport java.nio.file.Path\nimport java.util.function.Consumer\nimport java.util.regex.Pattern\nimport org.assertj.core.api.AbstractAssert\nimport org.assertj.core.api.Assertions.assertThat\nimport org.assertj.core.api.Assertions.assertThatCode\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertAll\nimport org.junit.jupiter.api.assertDoesNotThrow\nimport org.junit.jupiter.api.assertThrows\nimport org.junit.jupiter.api.io.TempDir\nimport org.junit.jupiter.params.ParameterizedTest\nimport org.junit.jupiter.params.provider.ValueSource\nimport org.pkl.core.*\nimport org.pkl.core.ModuleSource.path\nimport org.pkl.core.ModuleSource.text\nimport org.pkl.core.util.IoUtils\n\nclass JavaCodeGeneratorTest {\n companion object {\n private const val MAPPER_PREFIX = \"resources/META-INF/org/pkl/config/java/mapper/classes\"\n\n private val simpleClass: Class<*> by lazy {\n generateJavaCode(\n \"\"\"\n module my.mod\n\n class Simple {\n str: String\n list: List\n }\n \"\"\"\n .trimIndent()\n )\n .compile()\n .getValue(\"my.Mod\\$Simple\")\n }\n\n private val propertyTypesSources: JavaSourceCode by lazy {\n generateJavaCode(\n \"\"\"\n module my.mod\n\n class PropertyTypes {\n boolean: Boolean\n int: Int\n float: Float\n string: String\n duration: Duration\n durationUnit: DurationUnit\n dataSize: DataSize\n dataSizeUnit: DataSizeUnit\n nullable: String?\n nullable2: String?\n pair: Pair\n pair2: Pair\n coll: Collection\n coll2: Collection\n list: List\n list2: List\n set: Set\n set2: Set\n map: Map\n map2: Map\n container: Mapping\n container2: Mapping\n other: Other\n regex: Regex\n any: Any\n nonNull: NonNull\n enum: Direction\n bytes: Bytes\n }\n\n class Other {\n name: String\n }\n\n typealias Direction = \"north\"|\"east\"|\"south\"|\"west\"\n \"\"\"\n )\n }\n\n private val propertyTypesClasses: Map> by lazy {\n propertyTypesSources.compile()\n }\n\n private fun generateJavaCode(\n pklCode: String,\n options: JavaCodeGeneratorOptions = JavaCodeGeneratorOptions(),\n ): JavaSourceCode {\n val module = Evaluator.preconfigured().evaluateSchema(text(pklCode))\n val generator = JavaCodeGenerator(module, options)\n return JavaSourceCode(generator.javaFile)\n }\n }\n\n @TempDir lateinit var tempDir: Path\n\n @Test\n fun testEquals() {\n val ctor = simpleClass.constructors.first()\n val instance1 = ctor.newInstance(\"foo\", listOf(1, 2, 3))\n val instance2 = ctor.newInstance(\"foo\", listOf(1, 2, 3))\n val instance3 = ctor.newInstance(\"foo\", listOf(1, 3, 2))\n val instance4 = ctor.newInstance(\"bar\", listOf(1, 2, 3))\n\n assertThat(instance1).isEqualTo(instance1).isEqualTo(instance2)\n assertThat(instance2).isEqualTo(instance1)\n assertThat(instance3).isNotEqualTo(instance1)\n assertThat(instance4).isNotEqualTo(instance1)\n }\n\n @Test\n fun testHashCode() {\n val ctor = simpleClass.constructors.first()\n val instance1 = ctor.newInstance(\"foo\", listOf(1, 2, 3))\n val instance2 = ctor.newInstance(\"foo\", listOf(1, 2, 3))\n val instance3 = ctor.newInstance(\"foo\", listOf(1, 3, 2))\n val instance4 = ctor.newInstance(\"bar\", listOf(1, 2, 3))\n\n assertThat(instance1.hashCode()).isEqualTo(instance1.hashCode()).isEqualTo(instance2.hashCode())\n assertThat(instance3.hashCode()).isNotEqualTo(instance1.hashCode())\n assertThat(instance4.hashCode()).isNotEqualTo(instance1.hashCode())\n }\n\n @Test\n fun testToString() {\n val (_, propertyTypes) = instantiateOtherAndPropertyTypes()\n\n assertThat(propertyTypes.toString())\n .isEqualTo(\n \"\"\"\n PropertyTypes {\n _boolean = true\n _int = 42\n _float = 42.3\n string = string\n duration = 5.min\n durationUnit = min\n dataSize = 3.gb\n dataSizeUnit = gb\n nullable = idea\n nullable2 = null\n pair = Pair(1, 2)\n pair2 = Pair(pigeon, Other {\n name = pigeon\n })\n coll = [1, 2, 3]\n coll2 = [Other {\n name = pigeon\n }, Other {\n name = pigeon\n }]\n list = [1, 2, 3]\n list2 = [Other {\n name = pigeon\n }, Other {\n name = pigeon\n }]\n set = [1, 2, 3]\n set2 = [Other {\n name = pigeon\n }]\n map = {1=one, 2=two}\n map2 = {one=Other {\n name = pigeon\n }, two=Other {\n name = pigeon\n }}\n container = {1=one, 2=two}\n container2 = {one=Other {\n name = pigeon\n }, two=Other {\n name = pigeon\n }}\n other = Other {\n name = pigeon\n }\n regex = (i?)\\w*\n any = Other {\n name = pigeon\n }\n nonNull = Other {\n name = pigeon\n }\n _enum = north\n bytes = [1, 2, 3, 4]\n }\n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `deprecated property with message`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n class ClassWithDeprecatedProperty {\n @Deprecated { message = \"property deprecation message\" } \n deprecatedProperty: Int = 1337\n }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(generateJavadoc = true),\n )\n assertThat(javaCode)\n .contains(\n \"\"\"\n | public static final class ClassWithDeprecatedProperty {\n | /**\n | * @deprecated property deprecation message\n | */\n | @Deprecated\n | public final long deprecatedProperty;\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | /**\n | * @deprecated property deprecation message\n | */\n | @Deprecated\n | public ClassWithDeprecatedProperty withDeprecatedProperty(long deprecatedProperty) {\n | return new ClassWithDeprecatedProperty(deprecatedProperty);\n | }\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `deprecated property's getter with message`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n class ClassWithDeprecatedProperty {\n @Deprecated { message = \"property deprecation message\" } \n deprecatedProperty: Int = 1337\n }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(generateGetters = true, generateJavadoc = true),\n )\n assertThat(javaCode)\n .contains(\n \"\"\"\n | public static final class ClassWithDeprecatedProperty {\n | private final long deprecatedProperty;\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | /**\n | * @deprecated property deprecation message\n | */\n | @Deprecated\n | public long getDeprecatedProperty() {\n | return deprecatedProperty;\n | }\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | /**\n | * @deprecated property deprecation message\n | */\n | @Deprecated\n | public ClassWithDeprecatedProperty withDeprecatedProperty(long deprecatedProperty) {\n | return new ClassWithDeprecatedProperty(deprecatedProperty);\n | }\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `deprecated class with message`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n @Deprecated { message = \"class deprecation message\" }\n class DeprecatedClass {\n propertyOfDeprecatedClass: Int = 42\n }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(generateJavadoc = true),\n )\n assertThat(javaCode)\n .contains(\n \"\"\"\n | /**\n | * @deprecated class deprecation message\n | */\n | @Deprecated\n | public static final class DeprecatedClass {\n \"\"\"\n .trimMargin()\n )\n }\n\n @ParameterizedTest\n @ValueSource(booleans = [false, true])\n fun `deprecated module class with message`(generateJavadoc: Boolean) {\n val javaCode =\n generateJavaCode(\n \"\"\"\n @Deprecated{ message = \"module class deprecation message\" }\n module DeprecatedModule\n \n propertyInDeprecatedModuleClass : Int = 42\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(generateJavadoc = generateJavadoc),\n )\n\n assertThat(javaCode)\n .contains(\n \"\"\"\n |@Deprecated\n |public final class DeprecatedModule {\n \"\"\"\n .trimMargin()\n )\n\n if (generateJavadoc) {\n assertThat(javaCode)\n .contains(\n \"\"\"\n |/**\n | * @deprecated module class deprecation message\n | */\n \"\"\"\n .trimMargin()\n )\n } else {\n assertThat(javaCode).doesNotContain(\"* @deprecated\")\n }\n }\n\n @ParameterizedTest\n @ValueSource(booleans = [false, true])\n fun `deprecated property`(generateJavadoc: Boolean) {\n val javaCode =\n generateJavaCode(\n \"\"\"\n class ClassWithDeprecatedProperty {\n @Deprecated\n deprecatedProperty: Int = 1337\n }\n \"\"\"\n .trimIndent(),\n // no message, so no Javadoc, regardless of flag\n JavaCodeGeneratorOptions(generateJavadoc = generateJavadoc),\n )\n\n assertThat(javaCode)\n .contains(\n \"\"\"\n | public static final class ClassWithDeprecatedProperty {\n | @Deprecated\n | public final long deprecatedProperty;\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | @Deprecated\n | public ClassWithDeprecatedProperty withDeprecatedProperty(long deprecatedProperty) {\n | return new ClassWithDeprecatedProperty(deprecatedProperty);\n | }\n \"\"\"\n .trimMargin()\n )\n .doesNotContain(\"* @deprecated\")\n }\n\n @Test\n fun `deprecated property's getter`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n class ClassWithDeprecatedProperty {\n @Deprecated\n deprecatedProperty: Int = 1337\n }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(generateGetters = true),\n )\n\n assertThat(javaCode)\n .contains(\n \"\"\"\n | public static final class ClassWithDeprecatedProperty {\n | private final long deprecatedProperty;\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | @Deprecated\n | public long getDeprecatedProperty() {\n | return deprecatedProperty;\n | }\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | @Deprecated\n | public ClassWithDeprecatedProperty withDeprecatedProperty(long deprecatedProperty) {\n | return new ClassWithDeprecatedProperty(deprecatedProperty);\n | }\n \"\"\"\n .trimMargin()\n )\n .doesNotContain(\"* @deprecated\")\n }\n\n @Test\n fun `deprecated class`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n @Deprecated\n class DeprecatedClass {\n propertyOfDeprecatedClass: Int = 42\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode)\n .contains(\n \"\"\"\n | @Deprecated\n | public static final class DeprecatedClass {\n \"\"\"\n .trimMargin()\n )\n .doesNotContain(\"* @deprecated\")\n }\n\n @Test\n fun `deprecated module class`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n @Deprecated\n module DeprecatedModule\n \n propertyInDeprecatedModuleClass : Int = 42\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode)\n .contains(\n \"\"\"\n |@Deprecated\n |public final class DeprecatedModule {\n \"\"\"\n .trimMargin()\n )\n .doesNotContain(\"* @deprecated\")\n }\n\n @Test\n fun `deprecation with message and doc comment on the same property`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n /// Documenting deprecatedProperty\n @Deprecated { message = \"property is deprecated\" }\n deprecatedProperty: Int\n \"\"\",\n JavaCodeGeneratorOptions(generateJavadoc = true),\n )\n\n assertThat(javaCode)\n .contains(\n \"\"\"\n | /**\n | * Documenting deprecatedProperty\n | *\n | * @deprecated property is deprecated\n | */\n | @Deprecated\n | public final long deprecatedProperty;\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun properties() {\n val (other, propertyTypes) = instantiateOtherAndPropertyTypes()\n\n assertThat(readProperty(other, \"name\")).isEqualTo(\"pigeon\")\n assertThat(readProperty(propertyTypes, \"_boolean\")).isEqualTo(true)\n assertThat(readProperty(propertyTypes, \"_int\")).isEqualTo(42L)\n assertThat(readProperty(propertyTypes, \"_float\")).isEqualTo(42.3)\n assertThat(readProperty(propertyTypes, \"string\")).isEqualTo(\"string\")\n assertThat(readProperty(propertyTypes, \"duration\"))\n .isEqualTo(Duration(5.0, DurationUnit.MINUTES))\n assertThat(readProperty(propertyTypes, \"dataSize\"))\n .isEqualTo(DataSize(3.0, DataSizeUnit.GIGABYTES))\n assertThat(readProperty(propertyTypes, \"nullable\")).isEqualTo(\"idea\")\n assertThat(readProperty(propertyTypes, \"nullable2\")).isEqualTo(null as String?)\n assertThat(readProperty(propertyTypes, \"list\")).isEqualTo(listOf(1, 2, 3))\n assertThat(readProperty(propertyTypes, \"list2\")).isEqualTo(listOf(other, other))\n assertThat(readProperty(propertyTypes, \"set\")).isEqualTo(setOf(1, 2, 3))\n assertThat(readProperty(propertyTypes, \"set2\")).isEqualTo(setOf(other))\n assertThat(readProperty(propertyTypes, \"map\")).isEqualTo(mapOf(1 to \"one\", 2 to \"two\"))\n assertThat(readProperty(propertyTypes, \"map2\")).isEqualTo(mapOf(\"one\" to other, \"two\" to other))\n assertThat(readProperty(propertyTypes, \"container\")).isEqualTo(mapOf(1 to \"one\", 2 to \"two\"))\n assertThat(readProperty(propertyTypes, \"container2\"))\n .isEqualTo(mapOf(\"one\" to other, \"two\" to other))\n assertThat(readProperty(propertyTypes, \"other\")).isEqualTo(other)\n assertThat(readProperty(propertyTypes, \"regex\")).isInstanceOf(Pattern::class.java)\n assertThat(readProperty(propertyTypes, \"any\")).isEqualTo(other)\n assertThat(readProperty(propertyTypes, \"nonNull\")).isEqualTo(other)\n assertThat(readProperty(propertyTypes, \"bytes\")).isEqualTo(byteArrayOf(1, 2, 3, 4))\n }\n\n private fun readProperty(obj: Any, property: String): Any? =\n obj::class.java.getField(property).get(obj)\n\n @Test\n fun `properties 2`() {\n assertThat(propertyTypesSources).isEqualToResourceFile(\"PropertyTypes.jva\")\n }\n\n @Test\n fun `enum constant names`() {\n val cases =\n listOf(\n \"camelCasedName\" to \"CAMEL_CASED_NAME\",\n \"hyphenated-name\" to \"HYPHENATED_NAME\",\n \"EnQuad\\u2000EmSpace\\u2003IdeographicSpace\\u3000\" to \"EN_QUAD_EM_SPACE_IDEOGRAPHIC_SPACE_\",\n \"ᾊᾨ\" to \"ᾊᾨ\",\n \"0-digit\" to \"_0_DIGIT\",\n \"digit-1\" to \"DIGIT_1\",\n \"42\" to \"_42\",\n \"àœü\" to \"ÀŒÜ\",\n \"日本-つくば\" to \"日本_つくば\",\n )\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n typealias MyTypeAlias = ${cases.joinToString(\" | \") { \"\\\"${it.first}\\\"\" }}\n \"\"\"\n .trimIndent()\n )\n val javaClass = javaCode.compile().getValue(\"my.Mod\\$MyTypeAlias\")\n\n assertThat(javaClass.enumConstants.size)\n .isEqualTo(cases.size) // make sure zip doesn't drop cases\n\n assertAll(\n \"generated enum constants have correct names\",\n javaClass.declaredFields.zip(cases) { field, (_, kotlinName) ->\n {\n assertThat(field.name).isEqualTo(kotlinName)\n Unit\n }\n },\n )\n\n assertAll(\n \"toString() returns Pkl name\",\n javaClass.enumConstants.zip(cases) { enumConstant, (pklName, _) ->\n { assertThat(enumConstant.toString()).isEqualTo(pklName) }\n },\n )\n }\n\n @Test\n fun `conflicting enum constant names`() {\n val exception =\n assertThrows {\n generateJavaCode(\n \"\"\"\n module my.mod\n typealias MyTypeAlias = \"foo-bar\" | \"foo bar\"\n \"\"\"\n .trimIndent()\n )\n }\n\n assertThat(exception)\n .hasMessageContainingAll(\"both be converted to enum constant name\", \"FOO_BAR\")\n }\n\n @Test\n fun `empty enum constant name`() {\n val exception =\n assertThrows {\n generateJavaCode(\n \"\"\"\n module my.mod\n typealias MyTypeAlias = \"foo\" | \"\" | \"bar\"\n \"\"\"\n .trimIndent()\n )\n }\n\n assertThat(exception).hasMessageContaining(\"cannot be converted\")\n }\n\n @Test\n fun `inconvertible enum constant name`() {\n val exception =\n assertThrows {\n generateJavaCode(\n \"\"\"\n module my.mod\n typealias MyTypeAlias = \"foo\" | \"✅\" | \"bar\"\n \"\"\"\n .trimIndent()\n )\n }\n assertThat(exception).hasMessageContainingAll(\"✅\", \"cannot be converted\")\n }\n\n @Test\n fun `recursive types`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n class Foo {\n other: Int\n bar: Bar\n }\n class Bar {\n foo: Foo\n other: String\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n | public static final class Foo {\n | public final long other;\n |\n | public final @NonNull Bar bar;\n |\n | public Foo(@Named(\"other\") long other, @Named(\"bar\") @NonNull Bar bar) {\n | this.other = other;\n | this.bar = bar;\n | }\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public static final class Bar {\n | public final @NonNull Foo foo;\n |\n | public final @NonNull String other;\n |\n | public Bar(@Named(\"foo\") @NonNull Foo foo, @Named(\"other\") @NonNull String other) {\n | this.foo = foo;\n | this.other = other;\n | }\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun inheritance() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n abstract class Foo {\n one: Int\n }\n open class None extends Foo {}\n open class Bar extends None {\n two: String?\n }\n class Baz extends Bar {\n three: Duration\n }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(generateGetters = true),\n )\n\n assertThat(javaCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n | public abstract static class Foo {\n | protected final long one;\n |\n | protected Foo(@Named(\"one\") long one) {\n | this.one = one;\n | }\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public static class None extends Foo {\n | public None(@Named(\"one\") long one) {\n | super(one);\n | }\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public static class Bar extends None {\n | protected final String two;\n |\n | public Bar(@Named(\"one\") long one, @Named(\"two\") String two) {\n | super(one);\n | this.two = two;\n | }\n \"\"\"\n .trimMargin()\n )\n .isEqualToResourceFile(\"Inheritance.jva\")\n }\n\n @Test\n fun `stateless classes`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n class Foo\n abstract class Bar\n class Baz extends Bar\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode)\n .contains(\n \"\"\"\n | public static final class Foo {\n | public Foo() {\n | }\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public abstract static class Bar {\n | protected Bar() {\n | }\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public static final class Baz extends Bar {\n | public Baz() {\n | }\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `stateless module classes`() {\n var javaCode = generateJavaCode(\"module my.mod\")\n assertThat(javaCode)\n .contains(\n \"\"\"\n |public final class Mod {\n | private Mod() {\n | }\n \"\"\"\n .trimMargin()\n )\n\n javaCode = generateJavaCode(\"abstract module my.mod\")\n assertThat(javaCode)\n .contains(\n \"\"\"\n |public abstract class Mod {\n | protected Mod() {\n | }\n \"\"\"\n .trimMargin()\n )\n\n javaCode = generateJavaCode(\"open module my.mod\")\n assertThat(javaCode)\n .contains(\n \"\"\"\n |public class Mod {\n | public Mod() {\n | }\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `reserved words`() {\n val props = javaReservedWords.joinToString(\"\\n\") { \"`$it`: Int\" }\n\n val fooClass =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n class Foo {\n $props\n }\n \"\"\"\n .trimIndent()\n )\n .compile()\n .getValue(\"my.Mod\\$Foo\")\n\n assertThat(fooClass.declaredFields).allSatisfy(Consumer { it.name.startsWith(\"_\") })\n }\n\n @Test\n fun generatedAnnotation() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n class GeneratedAnnotation {\n test: Boolean = true\n }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(addGeneratedAnnotation = true),\n )\n\n assertThat(javaCode).compilesSuccessfully().isEqualToResourceFile(\"GeneratedAnnotation.jva\")\n }\n\n @Test\n fun getters() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n class GenerateGetters {\n urgent: Boolean = true\n url: String = \"https://apple.com\"\n diskSize: DataSize = 4.mb\n ETA: Duration = 3.s\n package: String\n }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(generateGetters = true),\n )\n\n assertThat(javaCode).compilesSuccessfully().isEqualToResourceFile(\"GenerateGetters.jva\")\n }\n\n @Test\n fun `'with' methods`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n abstract class Foo {\n x: Int\n }\n class Bar extends Foo {\n y: String\n }\n \"\"\"\n )\n\n assertThat(javaCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n | public Bar withX(long x) {\n | return new Bar(x, y);\n | }\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public Bar withY(@NonNull String y) {\n | return new Bar(x, y);\n | }\n \"\"\"\n .trimMargin()\n )\n .doesNotContain(\"public Foo withX\") // because `Foo` is abstract\n }\n\n @Test\n fun `module class`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n \n pigeon: String\n parrot: String\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode)\n .contains(\n \"\"\"\n |public final class Mod {\n | public final @NonNull String pigeon;\n |\n | public final @NonNull String parrot;\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `hidden properties`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n hidden pigeon1: String\n parrot1: String\n\n class Persons {\n hidden pigeon2: String\n parrot2: String\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode)\n .doesNotContain(\"final String pigeon1\")\n .contains(\"final @NonNull String parrot1\")\n .doesNotContain(\"final String pigeon2\")\n .contains(\"final @NonNull String parrot2\")\n }\n\n @Test\n fun javadoc() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n /// module comment.\n /// *emphasized* `code`.\n module my.mod\n\n /// module property comment.\n /// *emphasized* `code`.\n pigeon: Person\n\n /// class comment.\n /// *emphasized* `code`.\n class Person {\n /// class property comment.\n /// *emphasized* `code`.\n name: String\n }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(generateJavadoc = true),\n )\n\n assertThat(javaCode).compilesSuccessfully().isEqualToResourceFile(\"Javadoc.jva\")\n }\n\n @Test\n fun `javadoc 2`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n /// module property comment.\n /// can contain /* and */ characters.\n pigeon: Person\n\n class Person {\n /// class property comment.\n /// can contain /* and */ characters.\n name: String\n }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(generateGetters = true, generateJavadoc = true),\n )\n\n assertThat(javaCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n | /**\n | * module property comment.\n | * can contain /* and */ characters.\n | */\n | public @NonNull Person getPigeon() {\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | /**\n | * class property comment.\n | * can contain /* and */ characters.\n | */\n | public @NonNull String getName() {\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `pkl_base type aliases`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module mod\n\n uint8: UInt8\n uint16: UInt16\n uint32: UInt32\n uint: UInt\n int8: Int8\n int16: Int16\n int32: Int32\n uri: Uri\n\n pair: Pair\n list: List\n set: Set\n map: Map\n listing: Listing\n mapping: Mapping\n nullable: UInt16?\n\n class Foo {\n uint8: UInt8\n uint16: UInt16\n uint32: UInt32\n uint: UInt\n int8: Int8\n int16: Int16\n int32: Int32\n uri: Uri\n list: List\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n |public final class Mod {\n | public final short uint8;\n |\n | public final int uint16;\n |\n | public final long uint32;\n |\n | public final long uint;\n |\n | public final byte int8;\n |\n | public final short int16;\n |\n | public final int int32;\n |\n | public final @NonNull URI uri;\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public final @NonNull Pair<@NonNull Short, @NonNull Integer> pair;\n |\n | public final @NonNull List<@NonNull Long> list;\n |\n | public final @NonNull Set<@NonNull Long> set;\n |\n | public final @NonNull Map<@NonNull Byte, @NonNull Short> map;\n |\n | public final @NonNull List<@NonNull Integer> listing;\n |\n | public final @NonNull Map<@NonNull URI, @NonNull Short> mapping;\n |\n | public final Integer nullable;\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public static final class Foo {\n | public final short uint8;\n |\n | public final int uint16;\n |\n | public final long uint32;\n |\n | public final long uint;\n |\n | public final byte int8;\n |\n | public final short int16;\n |\n | public final int int32;\n |\n | public final @NonNull URI uri;\n |\n | public final @NonNull List<@NonNull Long> list;\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `nullable properties`() {\n var javaCode =\n generateJavaCode(\n \"\"\"\n module mod\n \n foo: String\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(nonNullAnnotation = \"com.example.Annotations\\$NonNull\"),\n )\n\n assertThat(javaCode)\n .contains(\"import com.example.Annotations;\")\n .contains(\"public final @Annotations.NonNull String foo;\")\n\n javaCode =\n generateJavaCode(\n \"\"\"\n module mod\n \n foo: Int\n bar: Int?\n baz: Any\n qux: String\n foo2: List?\n bar2: List\n baz2: List\n qux2: List\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode)\n .contains(\n \"\"\"\n |public final class Mod {\n | public final long foo;\n |\n | public final Long bar;\n |\n | public final Object baz;\n |\n | public final @NonNull String qux;\n |\n | public final List<@NonNull String> foo2;\n |\n | public final @NonNull List bar2;\n |\n | public final @NonNull List<@NonNull String> baz2;\n |\n | public final @NonNull List<@NonNull Long> qux2;\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `user defined type aliases`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module mod\n\n typealias Simple = String\n typealias Constrained = String(length >= 3)\n typealias Parameterized = List\n typealias Recursive1 = Parameterized(nonEmpty)\n typealias Recursive2 = List\n\n simple: Simple\n constrained: Constrained\n parameterized: Parameterized\n recursive1: Recursive1\n recursive2: Recursive2\n\n class Foo {\n simple: Simple\n constrained: Constrained\n parameterized: Parameterized\n recursive1: Recursive1\n recursive2: Recursive2\n }\n \"\"\"\n )\n\n assertThat(javaCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n |public final class Mod {\n | public final @NonNull String simple;\n |\n | public final @NonNull String constrained;\n |\n | public final @NonNull List<@NonNull Long> parameterized;\n |\n | public final @NonNull List<@NonNull Long> recursive1;\n |\n | public final @NonNull List<@NonNull String> recursive2;\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public static final class Foo {\n | public final @NonNull String simple;\n |\n | public final @NonNull String constrained;\n |\n | public final @NonNull List<@NonNull Long> parameterized;\n |\n | public final @NonNull List<@NonNull Long> recursive1;\n |\n | public final @NonNull List<@NonNull String> recursive2;\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `generic type aliases`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module mod\n\n class Person { name: String }\n\n typealias List2 = List\n typealias Map2 = Map\n typealias StringMap = Map\n typealias MMap = Map\n\n res1: List2\n res2: List2>\n res3: Map2\n res4: StringMap\n res5: MMap\n\n res6: List2\n res7: Map2\n res8: StringMap\n res9: MMap\n\n class Foo {\n res1: List2\n res2: List2>\n res3: Map2\n res4: StringMap\n res5: MMap\n\n res6: List2\n res7: Map2\n res8: StringMap\n res9: MMap\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n |public final class Mod {\n | public final @NonNull List<@NonNull Long> res1;\n |\n | public final @NonNull List<@NonNull List<@NonNull String>> res2;\n |\n | public final @NonNull Map<@NonNull Long, @NonNull String> res3;\n |\n | public final @NonNull Map<@NonNull String, @NonNull Duration> res4;\n |\n | public final @NonNull Map res5;\n |\n | public final @NonNull List<@NonNull Object> res6;\n |\n | public final @NonNull Map<@NonNull Object, @NonNull Object> res7;\n |\n | public final @NonNull Map<@NonNull String, @NonNull Object> res8;\n |\n | public final @NonNull Map<@NonNull Object, @NonNull Object> res9;\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public static final class Foo {\n | public final @NonNull List<@NonNull Long> res1;\n |\n | public final @NonNull List<@NonNull List<@NonNull String>> res2;\n |\n | public final @NonNull Map<@NonNull Long, @NonNull String> res3;\n |\n | public final @NonNull Map<@NonNull String, @NonNull Duration> res4;\n |\n | public final @NonNull Map res5;\n |\n | public final @NonNull List<@NonNull Object> res6;\n |\n | public final @NonNull Map<@NonNull Object, @NonNull Object> res7;\n |\n | public final @NonNull Map<@NonNull String, @NonNull Object> res8;\n |\n | public final @NonNull Map<@NonNull Object, @NonNull Object> res9;\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `union of string literals`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module mod\n\n x: \"Pigeon\"|\"Barn Owl\"|\"Parrot\"\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode).compilesSuccessfully().contains(\"public final @NonNull String x;\")\n }\n\n @Test\n fun `other union type`() {\n val e =\n assertThrows {\n generateJavaCode(\n \"\"\"\n module mod\n\n x: \"Pigeon\"|Int|\"Parrot\"\n \"\"\"\n .trimIndent()\n )\n }\n assertThat(e).hasMessageContaining(\"Pkl union types are not supported\")\n }\n\n @Test\n fun `stringy type`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module mod\n\n v1: \"RELEASE\"\n v2: \"RELEASE\"|String\n v3: String|\"RELEASE\"\n v4: \"RELEASE\"|String|\"LATEST\"\n v5: Version|String|\"LATEST\"\n v6: (Version|String)|(\"LATEST\"|String)\n \n typealias Version = \"RELEASE\"|String|\"LATEST\"\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode)\n .contains(\"public final @NonNull String v1;\")\n .contains(\"public final @NonNull String v2;\")\n .contains(\"public final @NonNull String v3;\")\n .contains(\"public final @NonNull String v4;\")\n .contains(\"public final @NonNull String v5;\")\n .contains(\"public final @NonNull String v6;\")\n }\n\n @Test\n fun `stringy type alias`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module mod\n\n typealias Version1 = \"RELEASE\"|String\n typealias Version2 = String|\"RELEASE\"\n typealias Version3 = \"RELEASE\"|String|\"LATEST\"\n typealias Version4 = Version3|String|\"LATEST\"\n typealias Version5 = (Version4|String)|(\"LATEST\"|String)\n typealias Version6 = Version5\n \n v1: Version1\n v2: Version2\n v3: Version3\n v4: Version4\n v5: Version5\n v6: Version6\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode)\n .contains(\"public final @NonNull String v1;\")\n .contains(\"public final @NonNull String v2;\")\n .contains(\"public final @NonNull String v3;\")\n .contains(\"public final @NonNull String v4;\")\n .contains(\"public final @NonNull String v5;\")\n .contains(\"public final @NonNull String v6;\")\n }\n\n @Test\n fun `custom constructor parameter annotation`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n name: String\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(paramsAnnotation = \"org.project.MyAnnotation\"),\n )\n\n assertThat(javaCode)\n .contains(\"import org.project.MyAnnotation;\")\n .contains(\"public Mod(@MyAnnotation(\\\"name\\\") @NonNull String name)\")\n }\n\n @Test\n fun `no constructor parameter annotation`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n name: String\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(paramsAnnotation = null),\n )\n\n assertThat(javaCode).contains(\"public Mod(@NonNull String name)\")\n }\n\n @Test\n fun `spring boot config`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n server: Server\n\n class Server {\n port: Int\n urls: Listing\n }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(generateSpringBootConfig = true),\n )\n\n assertThat(javaCode)\n .contains(\n \"\"\"\n |@ConfigurationProperties\n |public final class Mod {\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public final @NonNull Server server;\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | @ConfigurationProperties(\"server\")\n | public static final class Server {\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public final long port;\n |\n | public final @NonNull List<@NonNull URI> urls;\n \"\"\"\n .trimMargin()\n )\n .doesNotContain(\"@ConstructorBinding\")\n .doesNotContain(\"@Named\")\n\n // not worthwhile to add spring & spring boot dependency just so that this test can compile\n // their annotations\n val javaCodeWithoutSpringAnnotations =\n javaCode.deleteLines { it.contains(\"ConfigurationProperties\") }\n assertThat(javaCodeWithoutSpringAnnotations).compilesSuccessfully()\n }\n\n @Test\n fun `import module`() {\n val library =\n PklModule(\n \"library\",\n \"\"\"\n module library\n\n class Person { name: String; age: Int }\n \n pigeon: Person\n \"\"\"\n .trimIndent(),\n )\n\n val client =\n PklModule(\n \"client\",\n \"\"\"\n module client\n \n import \"library.pkl\"\n \n lib: library\n \n parrot: library.Person\n \"\"\"\n .trimIndent(),\n )\n\n val javaSourceFiles = generateFiles(library, client)\n assertDoesNotThrow { InMemoryJavaCompiler.compile(javaSourceFiles.mapValues { it.value.text }) }\n\n val javaClientCode =\n javaSourceFiles.entries.find { (fileName, _) -> fileName.endsWith(\"Client.java\") }!!.value\n assertThat(javaClientCode)\n .contains(\n \"\"\"\n |public final class Client {\n | public final @NonNull Library lib;\n |\n | public final Library. @NonNull Person parrot;\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `extend module`() {\n val base =\n PklModule(\n \"base\",\n \"\"\"\n open module base\n \n open class Person { name: String }\n \n pigeon: Person\n \"\"\"\n .trimIndent(),\n )\n\n val derived =\n PklModule(\n \"derived\",\n \"\"\"\n module derived\n extends \"base.pkl\"\n \n class Person2 extends Person { age: Int }\n \n person1: Person\n person2: Person2\n \"\"\"\n .trimIndent(),\n )\n\n val javaSourceFiles = generateFiles(base, derived)\n assertDoesNotThrow { InMemoryJavaCompiler.compile(javaSourceFiles.mapValues { it.value.text }) }\n\n val javaDerivedCode =\n javaSourceFiles.entries.find { (filename, _) -> filename.endsWith(\"Derived.java\") }!!.value\n assertThat(javaDerivedCode)\n .contains(\n \"\"\"\n |public final class Derived extends Base {\n | public final Base. @NonNull Person person1;\n |\n | public final @NonNull Person2 person2;\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `empty module`() {\n val javaCode = generateJavaCode(\"module mod\")\n assertThat(javaCode).contains(\"public final class Mod {\")\n }\n\n @Test\n fun `extend module that only contains type aliases`() {\n val base =\n PklModule(\n \"base\",\n \"\"\"\n abstract module base\n \n typealias Version = \"LATEST\"|String\n \"\"\"\n .trimIndent(),\n )\n\n val derived =\n PklModule(\n \"derived\",\n \"\"\"\n module derived\n \n extends \"base.pkl\"\n \n v: Version = \"1.2.3\"\n \"\"\"\n .trimIndent(),\n )\n\n val javaSourceFiles = generateFiles(base, derived)\n assertDoesNotThrow { InMemoryJavaCompiler.compile(javaSourceFiles.mapValues { it.value.text }) }\n\n val javaDerivedCode =\n javaSourceFiles.entries.find { (filename, _) -> filename.endsWith(\"Derived.java\") }!!.value\n assertThat(javaDerivedCode)\n .contains(\n \"\"\"\n |public final class Derived extends Base {\n | public final @NonNull String v;\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `generated properties files`() {\n val pklModule =\n PklModule(\n \"Mod.pkl\",\n \"\"\"\n module org.pkl.Mod\n \n foo: Foo\n \n bar: Bar\n \n class Foo {\n prop: String\n }\n \n class Bar {\n prop: Int\n }\n \"\"\"\n .trimIndent(),\n )\n val generated = generateFiles(pklModule)\n val expectedPropertyFile =\n \"resources/META-INF/org/pkl/config/java/mapper/classes/org.pkl.Mod.properties\"\n assertThat(generated).containsKey(expectedPropertyFile)\n val generatedFile = generated[expectedPropertyFile]!!\n assertThat(generatedFile)\n .contains(\"org.pkl.config.java.mapper.org.pkl.Mod\\\\#ModuleClass=org.pkl.Mod\")\n .contains(\"org.pkl.config.java.mapper.org.pkl.Mod\\\\#Foo=org.pkl.Mod\\$Foo\")\n .contains(\"org.pkl.config.java.mapper.org.pkl.Mod\\\\#Bar=org.pkl.Mod\\$Bar\")\n }\n\n @Test\n fun `generated properties files with normalized java name`() {\n val pklModule =\n PklModule(\n \"mod.pkl\",\n \"\"\"\n module my.mod\n \n foo: Foo\n \n bar: Bar\n \n class Foo {\n prop: String\n }\n \n class Bar {\n prop: Int\n }\n \"\"\"\n .trimIndent(),\n )\n val generated = generateFiles(pklModule)\n val expectedPropertyFile =\n \"resources/META-INF/org/pkl/config/java/mapper/classes/my.mod.properties\"\n assertThat(generated).containsKey(expectedPropertyFile)\n val generatedFile = generated[expectedPropertyFile]!!\n assertThat(generatedFile)\n .contains(\"org.pkl.config.java.mapper.my.mod\\\\#ModuleClass=my.Mod\")\n .contains(\"org.pkl.config.java.mapper.my.mod\\\\#Foo=my.Mod\\$Foo\")\n .contains(\"org.pkl.config.java.mapper.my.mod\\\\#Bar=my.Mod\\$Bar\")\n }\n\n @Test\n fun `generates serializable classes`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module mod\n \n class BigStruct {\n boolean: Boolean\n int: Int\n float: Float\n string: String\n duration: Duration\n dataSize: DataSize\n pair: Pair\n pair2: Pair\n coll: Collection\n coll2: Collection\n list: List\n list2: List\n set: Set\n set2: Set\n map: Map\n map2: Map\n container: Mapping\n container2: Mapping\n other: SmallStruct\n regex: Regex\n nonNull: NonNull\n enum: Direction\n }\n \n class SmallStruct {\n name: String\n }\n \n typealias Direction = \"north\"|\"east\"|\"south\"|\"west\"\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(implementSerializable = true),\n )\n\n assertThat(javaCode)\n .contains(\"implements Serializable\")\n .contains(\"private static final long serialVersionUID = 0L;\")\n\n val classes = javaCode.compile()\n\n val smallStructCtor = classes.getValue(\"Mod\\$SmallStruct\").constructors.first()\n val smallStruct = smallStructCtor.newInstance(\"pigeon\")\n\n val enumClass = classes.getValue(\"Mod\\$Direction\")\n val enumValue = enumClass.enumConstants.first()\n\n val bigStructCtor = classes.getValue(\"Mod\\$BigStruct\").constructors.first()\n val bigStruct =\n bigStructCtor.newInstance(\n true,\n 42L,\n 42.3,\n \"string\",\n Duration(5.0, DurationUnit.MINUTES),\n DataSize(3.0, DataSizeUnit.GIGABYTES),\n Pair(1, 2),\n Pair(\"pigeon\", smallStruct),\n listOf(1, 2, 3),\n listOf(smallStruct, smallStruct),\n listOf(1, 2, 3),\n listOf(smallStruct, smallStruct),\n setOf(1, 2, 3),\n setOf(smallStruct, smallStruct),\n mapOf(1 to \"one\", 2 to \"two\"),\n mapOf(\"one\" to smallStruct, \"two\" to smallStruct),\n mapOf(1 to \"one\", 2 to \"two\"),\n mapOf(\"one\" to smallStruct, \"two\" to smallStruct),\n smallStruct,\n Pattern.compile(\"(i?)\\\\w*\"),\n smallStruct,\n enumValue,\n )\n\n fun confirmSerDe(instance: Any) {\n var restoredInstance: Any? = null\n\n assertThatCode {\n // serialize\n val baos = ByteArrayOutputStream()\n val oos = ObjectOutputStream(baos)\n oos.writeObject(instance)\n oos.flush()\n\n // deserialize\n val bais = ByteArrayInputStream(baos.toByteArray())\n val ois =\n object : ObjectInputStream(bais) {\n override fun resolveClass(desc: ObjectStreamClass?): Class<*> {\n return Class.forName(desc!!.name, false, instance.javaClass.classLoader)\n }\n }\n restoredInstance = ois.readObject()\n }\n .doesNotThrowAnyException()\n\n assertThat(restoredInstance!!).isEqualTo(instance)\n }\n\n confirmSerDe(enumValue)\n confirmSerDe(smallStruct)\n confirmSerDe(bigStruct)\n }\n\n @Test\n fun `non-instantiable classes aren't made serializable`() {\n var javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n abstract class Foo { str: String }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(implementSerializable = true),\n )\n\n assertThat(javaCode).doesNotContain(\"Serializable\")\n\n javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(implementSerializable = true),\n )\n\n assertThat(javaCode).doesNotContain(\"Serializable\")\n }\n\n @Test\n fun `generates serializable module classes`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module Person\n name: String\n address: Address\n class Address { city: String }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(implementSerializable = true),\n )\n\n assertThat(javaCode)\n .contains(\n \"\"\"\n |public final class Person implements Serializable {\n | private static final long serialVersionUID = 0L;\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | public static final class Address implements Serializable {\n | private static final long serialVersionUID = 0L;\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `override property type`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n open class Foo\n\n class TheFoo extends Foo {\n fooProp: String\n }\n\n open class OpenClass {\n prop: Foo\n }\n\n class TheClass extends OpenClass {\n prop: TheFoo\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(javaCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n | public static final class TheClass extends OpenClass {\n | public final @NonNull TheFoo prop;\n |\n | public TheClass(@Named(\"prop\") @NonNull TheFoo prop) {\n | super(prop);\n | this.prop = prop;\n | }\n |\n | public TheClass withProp(@NonNull TheFoo prop) {\n | return new TheClass(prop);\n | }\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `override property type, with getters`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n open class Foo\n\n class TheFoo extends Foo {\n fooProp: String\n }\n\n open class OpenClass {\n prop: Foo\n }\n\n class TheClass extends OpenClass {\n prop: TheFoo\n }\n \"\"\"\n .trimIndent(),\n JavaCodeGeneratorOptions(generateGetters = true),\n )\n\n assertThat(javaCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n | public static final class TheClass extends OpenClass {\n | private final @NonNull TheFoo prop;\n |\n | public TheClass(@Named(\"prop\") @NonNull TheFoo prop) {\n | super(prop);\n | this.prop = prop;\n | }\n |\n | @Override\n | public @NonNull TheFoo getProp() {\n | return prop;\n | }\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `override names in a standalone module`() {\n val files =\n JavaCodeGeneratorOptions(\n renames = mapOf(\"a.b.c.\" to \"x.y.z.\", \"d.e.f.AnotherModule\" to \"u.v.w.RenamedModule\")\n )\n .generateFiles(\n \"MyModule.pkl\" to\n \"\"\"\n module a.b.c.MyModule\n \n foo: String = \"abc\"\n \"\"\"\n .trimIndent(),\n \"AnotherModule.pkl\" to\n \"\"\"\n module d.e.f.AnotherModule\n \n bar: Int = 123\n \"\"\"\n .trimIndent(),\n )\n .toMutableMap()\n\n files.validateContents(\n \"java/x/y/z/MyModule.java\" to listOf(\"package x.y.z;\", \"public final class MyModule {\"),\n \"$MAPPER_PREFIX/a.b.c.MyModule.properties\" to\n listOf(\"org.pkl.config.java.mapper.a.b.c.MyModule\\\\#ModuleClass=x.y.z.MyModule\"),\n // ---\n \"java/u/v/w/RenamedModule.java\" to\n listOf(\"package u.v.w;\", \"public final class RenamedModule {\"),\n \"$MAPPER_PREFIX/d.e.f.AnotherModule.properties\" to\n listOf(\"org.pkl.config.java.mapper.d.e.f.AnotherModule\\\\#ModuleClass=u.v.w.RenamedModule\"),\n )\n }\n\n @Test\n fun `override names based on the longest prefix`() {\n val files =\n JavaCodeGeneratorOptions(\n renames = mapOf(\"com.foo.bar.\" to \"x.\", \"com.foo.\" to \"y.\", \"com.\" to \"z.\", \"\" to \"w.\")\n )\n .generateFiles(\n \"com/foo/bar/Module1\" to\n \"\"\"\n module com.foo.bar.Module1\n \n bar: String\n \"\"\"\n .trimIndent(),\n \"com/Module2\" to\n \"\"\"\n module com.Module2\n \n com: String\n \"\"\"\n .trimIndent(),\n \"org/baz/Module3\" to\n \"\"\"\n module org.baz.Module3\n \n baz: String\n \"\"\"\n .trimIndent(),\n )\n\n files.validateContents(\n \"java/x/Module1.java\" to listOf(\"package x;\", \"public final class Module1 {\"),\n \"$MAPPER_PREFIX/com.foo.bar.Module1.properties\" to\n listOf(\"org.pkl.config.java.mapper.com.foo.bar.Module1\\\\#ModuleClass=x.Module1\"),\n // ---\n \"java/z/Module2.java\" to listOf(\"package z;\", \"public final class Module2 {\"),\n \"$MAPPER_PREFIX/com.Module2.properties\" to\n listOf(\"org.pkl.config.java.mapper.com.Module2\\\\#ModuleClass=z.Module2\"),\n // ---\n \"java/w/org/baz/Module3.java\" to listOf(\"package w.org.baz;\", \"public final class Module3 {\"),\n \"$MAPPER_PREFIX/org.baz.Module3.properties\" to\n listOf(\"org.pkl.config.java.mapper.org.baz.Module3\\\\#ModuleClass=w.org.baz.Module3\"),\n )\n }\n\n @Test\n fun `override names in multiple modules using each other`() {\n val files =\n JavaCodeGeneratorOptions(\n renames =\n mapOf(\n \"org.foo.\" to \"com.foo.x.\",\n \"org.bar.Module2\" to \"org.bar.RenamedModule\",\n \"org.baz.\" to \"com.baz.a.b.\",\n )\n )\n .generateFiles(\n \"org/foo/Module1\" to\n \"\"\"\n module org.foo.Module1\n \n class Person {\n name: String\n }\n \"\"\"\n .trimIndent(),\n \"org/bar/Module2\" to\n \"\"\"\n module org.bar.Module2\n \n import \"../../org/foo/Module1.pkl\"\n\n class Group {\n owner: Module1.Person\n name: String\n }\n \"\"\"\n .trimIndent(),\n \"org/baz/Module3\" to\n \"\"\"\n module org.baz.Module3\n \n import \"../../org/bar/Module2.pkl\"\n\n class Supergroup {\n owner: Module2.Group\n }\n \"\"\"\n .trimIndent(),\n )\n\n files.validateContents(\n \"java/com/foo/x/Module1.java\" to listOf(\"package com.foo.x;\", \"public final class Module1 {\"),\n \"$MAPPER_PREFIX/org.foo.Module1.properties\" to\n listOf(\n \"org.pkl.config.java.mapper.org.foo.Module1\\\\#ModuleClass=com.foo.x.Module1\",\n \"org.pkl.config.java.mapper.org.foo.Module1\\\\#Person=com.foo.x.Module1${'$'}Person\",\n ),\n // ---\n \"java/org/bar/RenamedModule.java\" to\n listOf(\n \"package org.bar;\",\n \"import com.foo.x.Module1;\",\n \"public final class RenamedModule {\",\n \"public final Module1. @NonNull Person owner;\",\n ),\n \"$MAPPER_PREFIX/org.bar.Module2.properties\" to\n listOf(\n \"org.pkl.config.java.mapper.org.bar.Module2\\\\#ModuleClass=org.bar.RenamedModule\",\n \"org.pkl.config.java.mapper.org.bar.Module2\\\\#Group=org.bar.RenamedModule${'$'}Group\",\n ),\n // ---\n \"java/com/baz/a/b/Module3.java\" to\n listOf(\n \"package com.baz.a.b;\",\n \"import org.bar.RenamedModule;\",\n \"public final class Module3 {\",\n \"public final RenamedModule. @NonNull Group owner;\",\n ),\n \"$MAPPER_PREFIX/org.baz.Module3.properties\" to\n listOf(\n \"org.pkl.config.java.mapper.org.baz.Module3\\\\#ModuleClass=com.baz.a.b.Module3\",\n \"org.pkl.config.java.mapper.org.baz.Module3\\\\#Supergroup=com.baz.a.b.Module3${'$'}Supergroup\",\n ),\n )\n }\n\n @Test\n fun `do not capitalize names of renamed classes`() {\n val files =\n JavaCodeGeneratorOptions(\n renames = mapOf(\"a.b.c.MyModule\" to \"x.y.z.renamed_module\", \"d.e.f.\" to \"u.v.w.\")\n )\n .generateFiles(\n \"MyModule.pkl\" to\n \"\"\"\n module a.b.c.MyModule\n \n foo: String = \"abc\"\n \"\"\"\n .trimIndent(),\n \"lower_module.pkl\" to\n \"\"\"\n module d.e.f.lower_module \n \n bar: Int = 123\n \"\"\"\n .trimIndent(),\n )\n\n files.validateContents(\n \"java/x/y/z/renamed_module.java\" to\n listOf(\"package x.y.z;\", \"public final class renamed_module {\"),\n \"$MAPPER_PREFIX/a.b.c.MyModule.properties\" to\n listOf(\"org.pkl.config.java.mapper.a.b.c.MyModule\\\\#ModuleClass=x.y.z.renamed_module\"),\n // ---\n \"java/u/v/w/Lower_module.java\" to\n listOf(\"package u.v.w;\", \"public final class Lower_module {\"),\n \"$MAPPER_PREFIX/d.e.f.lower_module.properties\" to\n listOf(\"org.pkl.config.java.mapper.d.e.f.lower_module\\\\#ModuleClass=u.v.w.Lower_module\"),\n )\n }\n\n @Test\n fun `equals,hashCode,toString work correctly for class that doesn't declare properties`() {\n val javaCode =\n generateJavaCode(\n \"\"\"\n module my.mod\n\n open class Foo {\n name: String\n }\n \n class Bar extends Foo {}\n \"\"\"\n .trimIndent()\n )\n\n val classes = javaCode.compile()\n val fooClass = classes.getValue(\"my.Mod\\$Foo\")\n val foo1 = fooClass.getDeclaredConstructor(String::class.java).newInstance(\"name1\")\n val barClass = classes.getValue(\"my.Mod\\$Bar\")\n val bar1 = barClass.getDeclaredConstructor(String::class.java).newInstance(\"name1\")\n val anotherBar1 = barClass.getDeclaredConstructor(String::class.java).newInstance(\"name1\")\n val bar2 = barClass.getDeclaredConstructor(String::class.java).newInstance(\"name2\")\n\n assertThat(bar1)\n .isEqualTo(bar1)\n .isEqualTo(anotherBar1)\n .isNotEqualTo(bar2)\n .isNotEqualTo(foo1)\n .hasSameHashCodeAs(bar1)\n .hasSameHashCodeAs(anotherBar1)\n assertThat(bar1.toString())\n .isEqualTo(\n \"\"\"\n Bar {\n name = name1\n }\n \"\"\"\n .trimIndent()\n )\n }\n\n private fun Map.validateContents(\n @Suppress(\"RemoveRedundantQualifierName\") vararg assertions: kotlin.Pair>\n ) {\n val files = toMutableMap()\n\n for ((fileName, lines) in assertions) {\n assertThat(files).containsKey(fileName)\n assertThat(files.remove(fileName)).describedAs(\"Contents of $fileName\").contains(lines)\n }\n\n assertThat(files).isEmpty()\n }\n\n private fun JavaCodeGeneratorOptions.generateFiles(\n vararg pklModules: PklModule\n ): Map {\n val pklFiles = pklModules.map { it.writeToDisk(tempDir.resolve(\"pkl/${it.name}.pkl\")) }\n val evaluator = Evaluator.preconfigured()\n return pklFiles.fold(mapOf()) { acc, pklFile ->\n val pklSchema = evaluator.evaluateSchema(path(pklFile))\n val generator = JavaCodeGenerator(pklSchema, this)\n acc + generator.output\n }\n }\n\n private fun JavaCodeGeneratorOptions.generateFiles(\n @Suppress(\"RemoveRedundantQualifierName\") vararg pklModules: kotlin.Pair\n ): Map =\n generateFiles(*pklModules.map { (name, text) -> PklModule(name, text) }.toTypedArray())\n\n private fun generateFiles(vararg pklModules: PklModule): Map =\n JavaCodeGeneratorOptions().generateFiles(*pklModules).mapValues { JavaSourceCode(it.value) }\n\n private fun instantiateOtherAndPropertyTypes(): kotlin.Pair {\n val otherCtor = propertyTypesClasses.getValue(\"my.Mod\\$Other\").constructors.first()\n val other = otherCtor.newInstance(\"pigeon\")\n\n val enumClass = propertyTypesClasses.getValue(\"my.Mod\\$Direction\")\n val enumValue = enumClass.enumConstants.first()\n\n val propertyTypesCtor =\n propertyTypesClasses.getValue(\"my.Mod\\$PropertyTypes\").constructors.first()\n val propertyTypes =\n propertyTypesCtor.newInstance(\n true,\n 42,\n 42.3,\n \"string\",\n Duration(5.0, DurationUnit.MINUTES),\n DurationUnit.MINUTES,\n DataSize(3.0, DataSizeUnit.GIGABYTES),\n DataSizeUnit.GIGABYTES,\n \"idea\",\n (null as String?),\n Pair(1, 2),\n Pair(\"pigeon\", other),\n listOf(1, 2, 3),\n listOf(other, other),\n listOf(1, 2, 3),\n listOf(other, other),\n setOf(1, 2, 3),\n setOf(other, other),\n mapOf(1 to \"one\", 2 to \"two\"),\n mapOf(\"one\" to other, \"two\" to other),\n mapOf(1 to \"one\", 2 to \"two\"),\n mapOf(\"one\" to other, \"two\" to other),\n other,\n Pattern.compile(\"(i?)\\\\w*\"),\n other,\n other,\n enumValue,\n byteArrayOf(1, 2, 3, 4),\n )\n\n return other to propertyTypes\n }\n\n private fun assertThat(actual: JavaSourceCode): JavaSourceCodeAssert =\n JavaSourceCodeAssert(actual)\n\n private data class JavaSourceCode(val text: String) {\n fun compile(): Map> =\n InMemoryJavaCompiler.compile(mapOf(\"/org/Mod.java\" to text))\n\n fun deleteLines(predicate: (String) -> Boolean): JavaSourceCode =\n JavaSourceCode(text.lines().filterNot(predicate).joinToString(\"\\n\"))\n }\n\n private class JavaSourceCodeAssert(actual: JavaSourceCode) :\n AbstractAssert(actual, JavaSourceCodeAssert::class.java) {\n fun contains(expected: String): JavaSourceCodeAssert {\n if (!actual.text.contains(expected)) {\n // check for equality to get better error output (IDE diff dialog)\n assertThat(actual.text).isEqualTo(expected)\n }\n return this\n }\n\n fun doesNotContain(expected: String): JavaSourceCodeAssert {\n assertThat(actual.text).doesNotContain(expected)\n return this\n }\n\n fun compilesSuccessfully(): JavaSourceCodeAssert {\n assertThatCode { actual.compile() }.doesNotThrowAnyException()\n return this\n }\n\n fun isEqualTo(expected: String): JavaSourceCodeAssert {\n assertThat(actual.text).isEqualTo(expected)\n return this\n }\n\n fun isEqualToResourceFile(fileName: String): JavaSourceCodeAssert {\n isEqualTo(IoUtils.readClassPathResourceAsString(javaClass, fileName))\n return this\n }\n }\n}\n" }, { "path": "pkl-codegen-java/src/test/kotlin/org/pkl/codegen/java/PklModule.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.codegen.java\n\nimport java.nio.file.Path\nimport kotlin.io.path.createParentDirectories\nimport org.pkl.commons.writeString\n\ndata class PklModule(val name: String, val content: String) {\n fun writeToDisk(path: Path): Path {\n return path.createParentDirectories().writeString(content)\n }\n}\n" }, { "path": "pkl-codegen-java/src/test/resources/org/pkl/codegen/java/GenerateGetters.jva", "content": "package my;\n\nimport java.lang.Object;\nimport java.lang.Override;\nimport java.lang.String;\nimport java.lang.StringBuilder;\nimport java.util.Objects;\nimport org.pkl.config.java.mapper.Named;\nimport org.pkl.config.java.mapper.NonNull;\nimport org.pkl.core.DataSize;\nimport org.pkl.core.Duration;\n\npublic final class Mod {\n private Mod() {\n }\n\n private static void appendProperty(StringBuilder builder, String name, Object value) {\n builder.append(\"\\n \").append(name).append(\" = \");\n String[] lines = Objects.toString(value).split(\"\\n\");\n builder.append(lines[0]);\n for (int i = 1; i < lines.length; i++) {\n builder.append(\"\\n \").append(lines[i]);\n }\n }\n\n public static final class GenerateGetters {\n private final boolean urgent;\n\n private final @NonNull String url;\n\n private final @NonNull DataSize diskSize;\n\n private final @NonNull Duration ETA;\n\n private final @NonNull String _package;\n\n public GenerateGetters(@Named(\"urgent\") boolean urgent, @Named(\"url\") @NonNull String url,\n @Named(\"diskSize\") @NonNull DataSize diskSize, @Named(\"ETA\") @NonNull Duration ETA,\n @Named(\"package\") @NonNull String _package) {\n this.urgent = urgent;\n this.url = url;\n this.diskSize = diskSize;\n this.ETA = ETA;\n this._package = _package;\n }\n\n public boolean isUrgent() {\n return urgent;\n }\n\n public GenerateGetters withUrgent(boolean urgent) {\n return new GenerateGetters(urgent, url, diskSize, ETA, _package);\n }\n\n public @NonNull String getUrl() {\n return url;\n }\n\n public GenerateGetters withUrl(@NonNull String url) {\n return new GenerateGetters(urgent, url, diskSize, ETA, _package);\n }\n\n public @NonNull DataSize getDiskSize() {\n return diskSize;\n }\n\n public GenerateGetters withDiskSize(@NonNull DataSize diskSize) {\n return new GenerateGetters(urgent, url, diskSize, ETA, _package);\n }\n\n public @NonNull Duration getETA() {\n return ETA;\n }\n\n public GenerateGetters withETA(@NonNull Duration ETA) {\n return new GenerateGetters(urgent, url, diskSize, ETA, _package);\n }\n\n public @NonNull String getPackage() {\n return _package;\n }\n\n public GenerateGetters withPackage(@NonNull String _package) {\n return new GenerateGetters(urgent, url, diskSize, ETA, _package);\n }\n\n @Override\n public boolean equals(Object obj) {\n if (this == obj) return true;\n if (obj == null) return false;\n if (this.getClass() != obj.getClass()) return false;\n GenerateGetters other = (GenerateGetters) obj;\n if (!Objects.equals(this.urgent, other.urgent)) return false;\n if (!Objects.equals(this.url, other.url)) return false;\n if (!Objects.equals(this.diskSize, other.diskSize)) return false;\n if (!Objects.equals(this.ETA, other.ETA)) return false;\n if (!Objects.equals(this._package, other._package)) return false;\n return true;\n }\n\n @Override\n public int hashCode() {\n int result = 1;\n result = 31 * result + Objects.hashCode(this.urgent);\n result = 31 * result + Objects.hashCode(this.url);\n result = 31 * result + Objects.hashCode(this.diskSize);\n result = 31 * result + Objects.hashCode(this.ETA);\n result = 31 * result + Objects.hashCode(this._package);\n return result;\n }\n\n @Override\n public String toString() {\n StringBuilder builder = new StringBuilder(300);\n builder.append(GenerateGetters.class.getSimpleName()).append(\" {\");\n appendProperty(builder, \"urgent\", this.urgent);\n appendProperty(builder, \"url\", this.url);\n appendProperty(builder, \"diskSize\", this.diskSize);\n appendProperty(builder, \"ETA\", this.ETA);\n appendProperty(builder, \"_package\", this._package);\n builder.append(\"\\n}\");\n return builder.toString();\n }\n }\n}\n" }, { "path": "pkl-codegen-java/src/test/resources/org/pkl/codegen/java/GeneratedAnnotation.jva", "content": "package my;\n\nimport java.lang.Object;\nimport java.lang.Override;\nimport java.lang.String;\nimport java.lang.StringBuilder;\nimport java.util.Objects;\nimport org.pkl.config.java.Generated;\nimport org.pkl.config.java.mapper.Named;\n\n@Generated\npublic final class Mod {\n private Mod() {\n }\n\n private static void appendProperty(StringBuilder builder, String name, Object value) {\n builder.append(\"\\n \").append(name).append(\" = \");\n String[] lines = Objects.toString(value).split(\"\\n\");\n builder.append(lines[0]);\n for (int i = 1; i < lines.length; i++) {\n builder.append(\"\\n \").append(lines[i]);\n }\n }\n\n @Generated\n public static final class GeneratedAnnotation {\n public final boolean test;\n\n public GeneratedAnnotation(@Named(\"test\") boolean test) {\n this.test = test;\n }\n\n public GeneratedAnnotation withTest(boolean test) {\n return new GeneratedAnnotation(test);\n }\n\n @Override\n public boolean equals(Object obj) {\n if (this == obj) return true;\n if (obj == null) return false;\n if (this.getClass() != obj.getClass()) return false;\n GeneratedAnnotation other = (GeneratedAnnotation) obj;\n if (!Objects.equals(this.test, other.test)) return false;\n return true;\n }\n\n @Override\n public int hashCode() {\n int result = 1;\n result = 31 * result + Objects.hashCode(this.test);\n return result;\n }\n\n @Override\n public String toString() {\n StringBuilder builder = new StringBuilder(100);\n builder.append(GeneratedAnnotation.class.getSimpleName()).append(\" {\");\n appendProperty(builder, \"test\", this.test);\n builder.append(\"\\n}\");\n return builder.toString();\n }\n }\n}\n" }, { "path": "pkl-codegen-java/src/test/resources/org/pkl/codegen/java/Inheritance.jva", "content": "package my;\n\nimport java.lang.Object;\nimport java.lang.Override;\nimport java.lang.String;\nimport java.lang.StringBuilder;\nimport java.util.Objects;\nimport org.pkl.config.java.mapper.Named;\nimport org.pkl.config.java.mapper.NonNull;\nimport org.pkl.core.Duration;\n\npublic final class Mod {\n private Mod() {\n }\n\n private static void appendProperty(StringBuilder builder, String name, Object value) {\n builder.append(\"\\n \").append(name).append(\" = \");\n String[] lines = Objects.toString(value).split(\"\\n\");\n builder.append(lines[0]);\n for (int i = 1; i < lines.length; i++) {\n builder.append(\"\\n \").append(lines[i]);\n }\n }\n\n public abstract static class Foo {\n protected final long one;\n\n protected Foo(@Named(\"one\") long one) {\n this.one = one;\n }\n\n public long getOne() {\n return one;\n }\n }\n\n public static class None extends Foo {\n public None(@Named(\"one\") long one) {\n super(one);\n }\n\n public None withOne(long one) {\n return new None(one);\n }\n\n @Override\n public boolean equals(Object obj) {\n if (this == obj) return true;\n if (obj == null) return false;\n if (this.getClass() != obj.getClass()) return false;\n None other = (None) obj;\n if (!Objects.equals(this.one, other.one)) return false;\n return true;\n }\n\n @Override\n public int hashCode() {\n int result = 1;\n result = 31 * result + Objects.hashCode(this.one);\n return result;\n }\n\n @Override\n public String toString() {\n StringBuilder builder = new StringBuilder(100);\n builder.append(None.class.getSimpleName()).append(\" {\");\n appendProperty(builder, \"one\", this.one);\n builder.append(\"\\n}\");\n return builder.toString();\n }\n }\n\n public static class Bar extends None {\n protected final String two;\n\n public Bar(@Named(\"one\") long one, @Named(\"two\") String two) {\n super(one);\n this.two = two;\n }\n\n public Bar withOne(long one) {\n return new Bar(one, two);\n }\n\n public String getTwo() {\n return two;\n }\n\n public Bar withTwo(String two) {\n return new Bar(one, two);\n }\n\n @Override\n public boolean equals(Object obj) {\n if (this == obj) return true;\n if (obj == null) return false;\n if (this.getClass() != obj.getClass()) return false;\n Bar other = (Bar) obj;\n if (!Objects.equals(this.one, other.one)) return false;\n if (!Objects.equals(this.two, other.two)) return false;\n return true;\n }\n\n @Override\n public int hashCode() {\n int result = 1;\n result = 31 * result + Objects.hashCode(this.one);\n result = 31 * result + Objects.hashCode(this.two);\n return result;\n }\n\n @Override\n public String toString() {\n StringBuilder builder = new StringBuilder(150);\n builder.append(Bar.class.getSimpleName()).append(\" {\");\n appendProperty(builder, \"one\", this.one);\n appendProperty(builder, \"two\", this.two);\n builder.append(\"\\n}\");\n return builder.toString();\n }\n }\n\n public static final class Baz extends Bar {\n private final @NonNull Duration three;\n\n public Baz(@Named(\"one\") long one, @Named(\"two\") String two,\n @Named(\"three\") @NonNull Duration three) {\n super(one, two);\n this.three = three;\n }\n\n public Baz withOne(long one) {\n return new Baz(one, two, three);\n }\n\n public Baz withTwo(String two) {\n return new Baz(one, two, three);\n }\n\n public @NonNull Duration getThree() {\n return three;\n }\n\n public Baz withThree(@NonNull Duration three) {\n return new Baz(one, two, three);\n }\n\n @Override\n public boolean equals(Object obj) {\n if (this == obj) return true;\n if (obj == null) return false;\n if (this.getClass() != obj.getClass()) return false;\n Baz other = (Baz) obj;\n if (!Objects.equals(this.one, other.one)) return false;\n if (!Objects.equals(this.two, other.two)) return false;\n if (!Objects.equals(this.three, other.three)) return false;\n return true;\n }\n\n @Override\n public int hashCode() {\n int result = 1;\n result = 31 * result + Objects.hashCode(this.one);\n result = 31 * result + Objects.hashCode(this.two);\n result = 31 * result + Objects.hashCode(this.three);\n return result;\n }\n\n @Override\n public String toString() {\n StringBuilder builder = new StringBuilder(200);\n builder.append(Baz.class.getSimpleName()).append(\" {\");\n appendProperty(builder, \"one\", this.one);\n appendProperty(builder, \"two\", this.two);\n appendProperty(builder, \"three\", this.three);\n builder.append(\"\\n}\");\n return builder.toString();\n }\n }\n}\n" }, { "path": "pkl-codegen-java/src/test/resources/org/pkl/codegen/java/Javadoc.jva", "content": "package my;\n\nimport java.lang.Object;\nimport java.lang.Override;\nimport java.lang.String;\nimport java.lang.StringBuilder;\nimport java.util.Objects;\nimport org.pkl.config.java.mapper.Named;\nimport org.pkl.config.java.mapper.NonNull;\n\n/**\n * module comment.\n * *emphasized* `code`.\n */\npublic final class Mod {\n /**\n * module property comment.\n * *emphasized* `code`.\n */\n public final @NonNull Person pigeon;\n\n public Mod(@Named(\"pigeon\") @NonNull Person pigeon) {\n this.pigeon = pigeon;\n }\n\n public Mod withPigeon(@NonNull Person pigeon) {\n return new Mod(pigeon);\n }\n\n @Override\n public boolean equals(Object obj) {\n if (this == obj) return true;\n if (obj == null) return false;\n if (this.getClass() != obj.getClass()) return false;\n Mod other = (Mod) obj;\n if (!Objects.equals(this.pigeon, other.pigeon)) return false;\n return true;\n }\n\n @Override\n public int hashCode() {\n int result = 1;\n result = 31 * result + Objects.hashCode(this.pigeon);\n return result;\n }\n\n @Override\n public String toString() {\n StringBuilder builder = new StringBuilder(100);\n builder.append(Mod.class.getSimpleName()).append(\" {\");\n appendProperty(builder, \"pigeon\", this.pigeon);\n builder.append(\"\\n}\");\n return builder.toString();\n }\n\n private static void appendProperty(StringBuilder builder, String name, Object value) {\n builder.append(\"\\n \").append(name).append(\" = \");\n String[] lines = Objects.toString(value).split(\"\\n\");\n builder.append(lines[0]);\n for (int i = 1; i < lines.length; i++) {\n builder.append(\"\\n \").append(lines[i]);\n }\n }\n\n /**\n * class comment.\n * *emphasized* `code`.\n */\n public static final class Person {\n /**\n * class property comment.\n * *emphasized* `code`.\n */\n public final @NonNull String name;\n\n public Person(@Named(\"name\") @NonNull String name) {\n this.name = name;\n }\n\n public Person withName(@NonNull String name) {\n return new Person(name);\n }\n\n @Override\n public boolean equals(Object obj) {\n if (this == obj) return true;\n if (obj == null) return false;\n if (this.getClass() != obj.getClass()) return false;\n Person other = (Person) obj;\n if (!Objects.equals(this.name, other.name)) return false;\n return true;\n }\n\n @Override\n public int hashCode() {\n int result = 1;\n result = 31 * result + Objects.hashCode(this.name);\n return result;\n }\n\n @Override\n public String toString() {\n StringBuilder builder = new StringBuilder(100);\n builder.append(Person.class.getSimpleName()).append(\" {\");\n appendProperty(builder, \"name\", this.name);\n builder.append(\"\\n}\");\n return builder.toString();\n }\n }\n}\n" }, { "path": "pkl-codegen-java/src/test/resources/org/pkl/codegen/java/PropertyTypes.jva", "content": "package my;\n\nimport java.lang.Object;\nimport java.lang.Override;\nimport java.lang.String;\nimport java.lang.StringBuilder;\nimport java.util.Arrays;\nimport java.util.Collection;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.Objects;\nimport java.util.Set;\nimport java.util.regex.Pattern;\nimport org.pkl.config.java.mapper.Named;\nimport org.pkl.config.java.mapper.NonNull;\nimport org.pkl.core.DataSize;\nimport org.pkl.core.DataSizeUnit;\nimport org.pkl.core.Duration;\nimport org.pkl.core.DurationUnit;\nimport org.pkl.core.Pair;\n\npublic final class Mod {\n private Mod() {\n }\n\n private static void appendProperty(StringBuilder builder, String name, Object value) {\n builder.append(\"\\n \").append(name).append(\" = \");\n String[] lines = Objects.toString(value).split(\"\\n\");\n builder.append(lines[0]);\n for (int i = 1; i < lines.length; i++) {\n builder.append(\"\\n \").append(lines[i]);\n }\n }\n\n public static final class PropertyTypes {\n public final boolean _boolean;\n\n public final long _int;\n\n public final double _float;\n\n public final @NonNull String string;\n\n public final @NonNull Duration duration;\n\n public final @NonNull DurationUnit durationUnit;\n\n public final @NonNull DataSize dataSize;\n\n public final @NonNull DataSizeUnit dataSizeUnit;\n\n public final String nullable;\n\n public final String nullable2;\n\n public final @NonNull Pair pair;\n\n public final @NonNull Pair<@NonNull String, @NonNull Other> pair2;\n\n public final @NonNull Collection coll;\n\n public final @NonNull Collection<@NonNull Other> coll2;\n\n public final @NonNull List list;\n\n public final @NonNull List<@NonNull Other> list2;\n\n public final @NonNull Set set;\n\n public final @NonNull Set<@NonNull Other> set2;\n\n public final @NonNull Map map;\n\n public final @NonNull Map<@NonNull String, @NonNull Other> map2;\n\n public final @NonNull Map container;\n\n public final @NonNull Map<@NonNull String, @NonNull Other> container2;\n\n public final @NonNull Other other;\n\n public final @NonNull Pattern regex;\n\n public final Object any;\n\n public final @NonNull Object nonNull;\n\n public final @NonNull Direction _enum;\n\n public final byte[] bytes;\n\n public PropertyTypes(@Named(\"boolean\") boolean _boolean, @Named(\"int\") long _int,\n @Named(\"float\") double _float, @Named(\"string\") @NonNull String string,\n @Named(\"duration\") @NonNull Duration duration,\n @Named(\"durationUnit\") @NonNull DurationUnit durationUnit,\n @Named(\"dataSize\") @NonNull DataSize dataSize,\n @Named(\"dataSizeUnit\") @NonNull DataSizeUnit dataSizeUnit,\n @Named(\"nullable\") String nullable, @Named(\"nullable2\") String nullable2,\n @Named(\"pair\") @NonNull Pair pair,\n @Named(\"pair2\") @NonNull Pair<@NonNull String, @NonNull Other> pair2,\n @Named(\"coll\") @NonNull Collection coll,\n @Named(\"coll2\") @NonNull Collection<@NonNull Other> coll2,\n @Named(\"list\") @NonNull List list,\n @Named(\"list2\") @NonNull List<@NonNull Other> list2, @Named(\"set\") @NonNull Set set,\n @Named(\"set2\") @NonNull Set<@NonNull Other> set2,\n @Named(\"map\") @NonNull Map map,\n @Named(\"map2\") @NonNull Map<@NonNull String, @NonNull Other> map2,\n @Named(\"container\") @NonNull Map container,\n @Named(\"container2\") @NonNull Map<@NonNull String, @NonNull Other> container2,\n @Named(\"other\") @NonNull Other other, @Named(\"regex\") @NonNull Pattern regex,\n @Named(\"any\") Object any, @Named(\"nonNull\") @NonNull Object nonNull,\n @Named(\"enum\") @NonNull Direction _enum, @Named(\"bytes\") byte[] bytes) {\n this._boolean = _boolean;\n this._int = _int;\n this._float = _float;\n this.string = string;\n this.duration = duration;\n this.durationUnit = durationUnit;\n this.dataSize = dataSize;\n this.dataSizeUnit = dataSizeUnit;\n this.nullable = nullable;\n this.nullable2 = nullable2;\n this.pair = pair;\n this.pair2 = pair2;\n this.coll = coll;\n this.coll2 = coll2;\n this.list = list;\n this.list2 = list2;\n this.set = set;\n this.set2 = set2;\n this.map = map;\n this.map2 = map2;\n this.container = container;\n this.container2 = container2;\n this.other = other;\n this.regex = regex;\n this.any = any;\n this.nonNull = nonNull;\n this._enum = _enum;\n this.bytes = bytes;\n }\n\n public PropertyTypes withBoolean(boolean _boolean) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withInt(long _int) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withFloat(double _float) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withString(@NonNull String string) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withDuration(@NonNull Duration duration) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withDurationUnit(@NonNull DurationUnit durationUnit) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withDataSize(@NonNull DataSize dataSize) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withDataSizeUnit(@NonNull DataSizeUnit dataSizeUnit) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withNullable(String nullable) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withNullable2(String nullable2) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withPair(@NonNull Pair pair) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withPair2(@NonNull Pair<@NonNull String, @NonNull Other> pair2) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withColl(@NonNull Collection coll) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withColl2(@NonNull Collection<@NonNull Other> coll2) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withList(@NonNull List list) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withList2(@NonNull List<@NonNull Other> list2) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withSet(@NonNull Set set) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withSet2(@NonNull Set<@NonNull Other> set2) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withMap(@NonNull Map map) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withMap2(@NonNull Map<@NonNull String, @NonNull Other> map2) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withContainer(@NonNull Map container) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withContainer2(@NonNull Map<@NonNull String, @NonNull Other> container2) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withOther(@NonNull Other other) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withRegex(@NonNull Pattern regex) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withAny(Object any) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withNonNull(@NonNull Object nonNull) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withEnum(@NonNull Direction _enum) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n public PropertyTypes withBytes(byte[] bytes) {\n return new PropertyTypes(_boolean, _int, _float, string, duration, durationUnit, dataSize, dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map, map2, container, container2, other, regex, any, nonNull, _enum, bytes);\n }\n\n @Override\n public boolean equals(Object obj) {\n if (this == obj) return true;\n if (obj == null) return false;\n if (this.getClass() != obj.getClass()) return false;\n PropertyTypes other = (PropertyTypes) obj;\n if (!Objects.equals(this._boolean, other._boolean)) return false;\n if (!Objects.equals(this._int, other._int)) return false;\n if (!Objects.equals(this._float, other._float)) return false;\n if (!Objects.equals(this.string, other.string)) return false;\n if (!Objects.equals(this.duration, other.duration)) return false;\n if (!Objects.equals(this.durationUnit, other.durationUnit)) return false;\n if (!Objects.equals(this.dataSize, other.dataSize)) return false;\n if (!Objects.equals(this.dataSizeUnit, other.dataSizeUnit)) return false;\n if (!Objects.equals(this.nullable, other.nullable)) return false;\n if (!Objects.equals(this.nullable2, other.nullable2)) return false;\n if (!Objects.equals(this.pair, other.pair)) return false;\n if (!Objects.equals(this.pair2, other.pair2)) return false;\n if (!Objects.equals(this.coll, other.coll)) return false;\n if (!Objects.equals(this.coll2, other.coll2)) return false;\n if (!Objects.equals(this.list, other.list)) return false;\n if (!Objects.equals(this.list2, other.list2)) return false;\n if (!Objects.equals(this.set, other.set)) return false;\n if (!Objects.equals(this.set2, other.set2)) return false;\n if (!Objects.equals(this.map, other.map)) return false;\n if (!Objects.equals(this.map2, other.map2)) return false;\n if (!Objects.equals(this.container, other.container)) return false;\n if (!Objects.equals(this.container2, other.container2)) return false;\n if (!Objects.equals(this.other, other.other)) return false;\n if (!Objects.equals(this.regex.pattern(), other.regex.pattern())) return false;\n if (!Objects.equals(this.any, other.any)) return false;\n if (!Objects.equals(this.nonNull, other.nonNull)) return false;\n if (!Objects.equals(this._enum, other._enum)) return false;\n if (!Objects.equals(this.bytes, other.bytes)) return false;\n return true;\n }\n\n @Override\n public int hashCode() {\n int result = 1;\n result = 31 * result + Objects.hashCode(this._boolean);\n result = 31 * result + Objects.hashCode(this._int);\n result = 31 * result + Objects.hashCode(this._float);\n result = 31 * result + Objects.hashCode(this.string);\n result = 31 * result + Objects.hashCode(this.duration);\n result = 31 * result + Objects.hashCode(this.durationUnit);\n result = 31 * result + Objects.hashCode(this.dataSize);\n result = 31 * result + Objects.hashCode(this.dataSizeUnit);\n result = 31 * result + Objects.hashCode(this.nullable);\n result = 31 * result + Objects.hashCode(this.nullable2);\n result = 31 * result + Objects.hashCode(this.pair);\n result = 31 * result + Objects.hashCode(this.pair2);\n result = 31 * result + Objects.hashCode(this.coll);\n result = 31 * result + Objects.hashCode(this.coll2);\n result = 31 * result + Objects.hashCode(this.list);\n result = 31 * result + Objects.hashCode(this.list2);\n result = 31 * result + Objects.hashCode(this.set);\n result = 31 * result + Objects.hashCode(this.set2);\n result = 31 * result + Objects.hashCode(this.map);\n result = 31 * result + Objects.hashCode(this.map2);\n result = 31 * result + Objects.hashCode(this.container);\n result = 31 * result + Objects.hashCode(this.container2);\n result = 31 * result + Objects.hashCode(this.other);\n result = 31 * result + Objects.hashCode(this.regex.pattern());\n result = 31 * result + Objects.hashCode(this.any);\n result = 31 * result + Objects.hashCode(this.nonNull);\n result = 31 * result + Objects.hashCode(this._enum);\n result = 31 * result + Objects.hashCode(this.bytes);\n return result;\n }\n\n @Override\n public String toString() {\n StringBuilder builder = new StringBuilder(1450);\n builder.append(PropertyTypes.class.getSimpleName()).append(\" {\");\n appendProperty(builder, \"_boolean\", this._boolean);\n appendProperty(builder, \"_int\", this._int);\n appendProperty(builder, \"_float\", this._float);\n appendProperty(builder, \"string\", this.string);\n appendProperty(builder, \"duration\", this.duration);\n appendProperty(builder, \"durationUnit\", this.durationUnit);\n appendProperty(builder, \"dataSize\", this.dataSize);\n appendProperty(builder, \"dataSizeUnit\", this.dataSizeUnit);\n appendProperty(builder, \"nullable\", this.nullable);\n appendProperty(builder, \"nullable2\", this.nullable2);\n appendProperty(builder, \"pair\", this.pair);\n appendProperty(builder, \"pair2\", this.pair2);\n appendProperty(builder, \"coll\", this.coll);\n appendProperty(builder, \"coll2\", this.coll2);\n appendProperty(builder, \"list\", this.list);\n appendProperty(builder, \"list2\", this.list2);\n appendProperty(builder, \"set\", this.set);\n appendProperty(builder, \"set2\", this.set2);\n appendProperty(builder, \"map\", this.map);\n appendProperty(builder, \"map2\", this.map2);\n appendProperty(builder, \"container\", this.container);\n appendProperty(builder, \"container2\", this.container2);\n appendProperty(builder, \"other\", this.other);\n appendProperty(builder, \"regex\", this.regex);\n appendProperty(builder, \"any\", this.any);\n appendProperty(builder, \"nonNull\", this.nonNull);\n appendProperty(builder, \"_enum\", this._enum);\n appendProperty(builder, \"bytes\", Arrays.toString(this.bytes));\n builder.append(\"\\n}\");\n return builder.toString();\n }\n }\n\n public static final class Other {\n public final @NonNull String name;\n\n public Other(@Named(\"name\") @NonNull String name) {\n this.name = name;\n }\n\n public Other withName(@NonNull String name) {\n return new Other(name);\n }\n\n @Override\n public boolean equals(Object obj) {\n if (this == obj) return true;\n if (obj == null) return false;\n if (this.getClass() != obj.getClass()) return false;\n Other other = (Other) obj;\n if (!Objects.equals(this.name, other.name)) return false;\n return true;\n }\n\n @Override\n public int hashCode() {\n int result = 1;\n result = 31 * result + Objects.hashCode(this.name);\n return result;\n }\n\n @Override\n public String toString() {\n StringBuilder builder = new StringBuilder(100);\n builder.append(Other.class.getSimpleName()).append(\" {\");\n appendProperty(builder, \"name\", this.name);\n builder.append(\"\\n}\");\n return builder.toString();\n }\n }\n\n public enum Direction {\n NORTH(\"north\"),\n\n EAST(\"east\"),\n\n SOUTH(\"south\"),\n\n WEST(\"west\");\n\n private String value;\n\n private Direction(String value) {\n this.value = value;\n }\n\n @Override\n public String toString() {\n return this.value;\n }\n }\n}\n" }, { "path": "pkl-codegen-kotlin/gradle.lockfile", "content": "# This is a Gradle generated file for dependency locking.\n# Manual edits can break the build and are not advised.\n# This file is expected to be part of source control.\ncom.github.ajalt.clikt:clikt-core-jvm:5.0.3=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-core:5.0.3=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-jvm:5.0.3=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-markdown-jvm:5.0.3=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-markdown:5.0.3=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt:5.0.3=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.colormath:colormath-jvm:3.6.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.colormath:colormath:3.6.0=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-core-jvm:3.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-core:3.0.1=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-ffm-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-ffm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-graal-ffi-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-graal-ffi:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-jna-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-jna:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm:3.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-markdown-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-markdown:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant:3.0.1=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ben-manes.caffeine:caffeine:2.9.3=swiftExportClasspathResolvable\ncom.google.errorprone:error_prone_annotations:2.28.0=swiftExportClasspathResolvable\ncom.squareup:kotlinpoet:1.6.0=compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\nio.github.java-diff-utils:java-diff-utils:4.12=kotlinInternalAbiValidation\nio.opentelemetry:opentelemetry-api:1.41.0=swiftExportClasspathResolvable\nio.opentelemetry:opentelemetry-context:1.41.0=swiftExportClasspathResolvable\nnet.bytebuddy:byte-buddy:1.17.7=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\nnet.java.dev.jna:jna:5.14.0=runtimeClasspath,testRuntimeClasspath\norg.apiguardian:apiguardian-api:1.1.2=testCompileClasspath,testImplementationDependenciesMetadata\norg.assertj:assertj-core:3.27.6=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.bouncycastle:bcpg-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcpkix-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcprov-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcutil-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.checkerframework:checker-qual:3.43.0=swiftExportClasspathResolvable\norg.graalvm.polyglot:polyglot:25.0.0=runtimeClasspath,testRuntimeClasspath\norg.graalvm.sdk:collections:25.0.0=runtimeClasspath,testRuntimeClasspath\norg.graalvm.sdk:graal-sdk:25.0.0=runtimeClasspath,testRuntimeClasspath\norg.graalvm.sdk:nativeimage:25.0.0=runtimeClasspath,testRuntimeClasspath\norg.graalvm.sdk:word:25.0.0=runtimeClasspath,testRuntimeClasspath\norg.graalvm.truffle:truffle-api:25.0.0=runtimeClasspath,testRuntimeClasspath\norg.jetbrains.kotlin:abi-tools-api:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:abi-tools:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-build-tools-api:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-build-tools-impl:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-compiler-runner:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-client:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-klib-commonizer-embeddable:2.2.20=kotlinKlibCommonizerClasspath\norg.jetbrains.kotlin:kotlin-metadata-jvm:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-native-prebuilt:2.0.21=kotlinNativeBundleConfiguration\norg.jetbrains.kotlin:kotlin-reflect:2.2.20=compileClasspath,implementationDependenciesMetadata,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,runtimeClasspath,swiftExportClasspathResolvable,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-script-runtime:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-scripting-common:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-scripting-compiler-impl-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-scripting-jsr223:2.2.20=testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-scripting-jvm-host:2.2.20=testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-scripting-jvm:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib-jdk7:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib-jdk8:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,runtimeClasspath,swiftExportClasspathResolvable,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:swift-export-embeddable:2.2.20=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.8.0=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable,testRuntimeClasspath\norg.jetbrains.kotlinx:kotlinx-serialization-bom:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core-jvm:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3=swiftExportClasspathResolvable\norg.jetbrains:annotations:13.0=compileClasspath,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,runtimeClasspath,swiftExportClasspathResolvable,testCompileClasspath,testRuntimeClasspath\norg.jetbrains:markdown-jvm:0.7.3=runtimeClasspath,testRuntimeClasspath\norg.jetbrains:markdown:0.7.3=runtimeClasspath,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-api:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-engine:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-params:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-commons:1.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-engine:1.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-launcher:1.14.0=testRuntimeClasspath\norg.junit:junit-bom:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.msgpack:msgpack-core:0.9.8=runtimeClasspath,testRuntimeClasspath\norg.opentest4j:opentest4j:1.3.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.organicdesign:Paguro:3.10.3=runtimeClasspath,testRuntimeClasspath\norg.snakeyaml:snakeyaml-engine:2.10=runtimeClasspath,testRuntimeClasspath\nempty=annotationProcessor,compileOnlyDependenciesMetadata,intransitiveDependenciesMetadata,kotlinCompilerPluginClasspath,kotlinNativeCompilerPluginClasspath,kotlinScriptDefExtensions,shadow,signatures,sourcesJar,testAnnotationProcessor,testApiDependenciesMetadata,testCompileOnlyDependenciesMetadata,testIntransitiveDependenciesMetadata,testKotlinScriptDefExtensions\n" }, { "path": "pkl-codegen-kotlin/pkl-codegen-kotlin.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nplugins {\n pklAllProjects\n pklKotlinLibrary\n pklPublishLibrary\n pklJavaExecutable\n}\n\npublishing {\n publications {\n named(\"library\") {\n pom {\n url.set(\"https://github.com/apple/pkl/tree/main/pkl-codegen-kotlin\")\n description.set(\n \"\"\"\n Kotlin source code generator that generates corresponding Kotlin classes for Pkl classes,\n simplifying consumption of Pkl configuration as statically typed Kotlin objects.\n \"\"\"\n .trimIndent()\n )\n }\n }\n }\n}\n\ntasks.jar { manifest { attributes += mapOf(\"Main-Class\" to \"org.pkl.codegen.kotlin.Main\") } }\n\ndependencies {\n implementation(projects.pklCommons)\n api(projects.pklCommonsCli)\n api(projects.pklCore)\n\n implementation(libs.kotlinPoet) {\n exclude(group = \"org.jetbrains.kotlin\", module = \"kotlin-reflect\")\n exclude(group = \"org.jetbrains.kotlin\", module = \"kotlin-stdlib-jdk8\")\n }\n implementation(libs.kotlinReflect)\n\n testImplementation(projects.pklConfigKotlin)\n testImplementation(projects.pklCommonsTest)\n testRuntimeOnly(libs.kotlinScripting)\n}\n\nexecutable {\n javaName = \"pkl-codegen-kotlin\"\n documentationName = \"Pkl Codegen Kotlin\"\n javaPublicationName = \"pkl-cli-codegen-kotlin\"\n mainClass = \"org.pkl.codegen.kotlin.Main\"\n website = \"https://pkl-lang.org/main/current/kotlin-binding/codegen.html\"\n}\n" }, { "path": "pkl-codegen-kotlin/src/main/kotlin/org/pkl/codegen/kotlin/CliKotlinCodeGenerator.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.codegen.kotlin\n\nimport java.io.IOException\nimport kotlin.io.path.createParentDirectories\nimport org.pkl.commons.cli.CliCommand\nimport org.pkl.commons.cli.CliException\nimport org.pkl.commons.writeString\nimport org.pkl.core.Closeables\nimport org.pkl.core.ModuleSource\n\n/** API for the Kotlin code generator CLI. */\nclass CliKotlinCodeGenerator(private val options: CliKotlinCodeGeneratorOptions) :\n CliCommand(options.base) {\n\n override fun doRun() {\n val builder = evaluatorBuilder()\n\n try {\n builder.build().use { evaluator ->\n for (moduleUri in resolvedSourceModules) {\n val schema = evaluator.evaluateSchema(ModuleSource.uri(moduleUri))\n val codeGenerator = KotlinCodeGenerator(schema, options.toKotlinCodeGeneratorOptions())\n try {\n for ((fileName, fileContents) in codeGenerator.output) {\n val outputFile = options.outputDir.resolve(fileName)\n try {\n outputFile.createParentDirectories().writeString(fileContents)\n } catch (e: IOException) {\n throw CliException(\"I/O error writing file `$outputFile`.\\nCause: ${e.message}\")\n }\n }\n } catch (e: KotlinCodeGeneratorException) {\n throw CliException(e.message!!)\n }\n }\n }\n } finally {\n Closeables.closeQuietly(builder.moduleKeyFactories)\n Closeables.closeQuietly(builder.resourceReaders)\n }\n }\n}\n" }, { "path": "pkl-codegen-kotlin/src/main/kotlin/org/pkl/codegen/kotlin/CliKotlinCodeGeneratorOptions.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.codegen.kotlin\n\nimport java.nio.file.Path\nimport org.pkl.commons.cli.CliBaseOptions\n\n/** Configuration options for [CliKotlinCodeGenerator]. */\ndata class CliKotlinCodeGeneratorOptions(\n /** Base options shared between CLI commands. */\n val base: CliBaseOptions,\n\n /** The directory where generated source code is placed. */\n val outputDir: Path,\n\n /** The characters to use for indenting generated source code. */\n val indent: String = \" \",\n\n /** Whether to preserve Pkl doc comments by generating corresponding KDoc comments. */\n val generateKdoc: Boolean = false,\n\n /** Whether to generate config classes for use with Spring Boot. */\n val generateSpringBootConfig: Boolean = false,\n\n /** Whether generated classes should implement [java.io.Serializable]. */\n val implementSerializable: Boolean = false,\n\n /** Whether to add the `@Generated` annotation to types */\n val addGeneratedAnnotation: Boolean = false,\n\n /**\n * A rename mapping for class names.\n *\n * When you need to have Kotlin class or package names different from the default names derived\n * from Pkl module names, you can define a rename mapping, where the key is a prefix of the\n * original Pkl module name, and the value is the desired replacement.\n */\n val renames: Map = emptyMap(),\n) {\n @Suppress(\"DeprecatedCallableAddReplaceWith\")\n @Deprecated(\"deprecated without replacement\")\n fun toKotlinCodegenOptions(): KotlinCodeGeneratorOptions = toKotlinCodeGeneratorOptions()\n\n internal fun toKotlinCodeGeneratorOptions(): KotlinCodeGeneratorOptions =\n KotlinCodeGeneratorOptions(\n indent,\n generateKdoc,\n generateSpringBootConfig,\n implementSerializable,\n addGeneratedAnnotation,\n renames,\n )\n}\n" }, { "path": "pkl-codegen-kotlin/src/main/kotlin/org/pkl/codegen/kotlin/KotlinCodeGenerator.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n@file:Suppress(\"unused\")\n\npackage org.pkl.codegen.kotlin\n\nimport com.squareup.kotlinpoet.*\nimport com.squareup.kotlinpoet.ParameterizedTypeName.Companion.parameterizedBy\nimport java.io.StringWriter\nimport java.util.*\nimport org.pkl.commons.NameMapper\nimport org.pkl.core.*\nimport org.pkl.core.util.CodeGeneratorUtils\nimport org.pkl.core.util.IoUtils\n\n@Deprecated(\"renamed to KotlinCodeGeneratorOptions\", ReplaceWith(\"KotlinCodeGeneratorOptions\"))\ntypealias KotlinCodegenOptions = KotlinCodeGeneratorOptions\n\ndata class KotlinCodeGeneratorOptions(\n /** The characters to use for indenting generated Kotlin code. */\n val indent: String = \" \",\n\n /** Whether to preserve Pkl doc comments by generating corresponding KDoc comments. */\n val generateKdoc: Boolean = false,\n\n /** Whether to generate config classes for use with Spring Boot. */\n val generateSpringBootConfig: Boolean = false,\n\n /** Whether to generate classes that implement [java.io.Serializable]. */\n val implementSerializable: Boolean = false,\n\n /** Whether to add the `@Generated` to generated types. */\n val addGeneratedAnnotation: Boolean = false,\n\n /**\n * A mapping from Pkl module name prefixes to their replacements.\n *\n * Can be used when the class or package name in the generated source code should be different\n * from the corresponding name derived from the Pkl module declaration .\n */\n val renames: Map = emptyMap(),\n)\n\nclass KotlinCodeGeneratorException(message: String) : RuntimeException(message)\n\n/** Entrypoint for the Kotlin code generator API. */\nclass KotlinCodeGenerator(\n /** The schema for the module to generate */\n private val moduleSchema: ModuleSchema,\n\n /** The options to use for the code generator */\n private val options: KotlinCodeGeneratorOptions,\n) {\n companion object {\n private val STRING = String::class.asClassName()\n private val ANY_NULL = ANY.copy(nullable = true)\n private val NOTHING = Nothing::class.asClassName()\n @Suppress(\"RemoveRedundantQualifierName\")\n private val KOTLIN_PAIR = kotlin.Pair::class.asClassName()\n private val COLLECTION = Collection::class.asClassName()\n private val LIST = List::class.asClassName()\n private val SET = Set::class.asClassName()\n private val MAP = Map::class.asClassName()\n private val DURATION = Duration::class.asClassName()\n private val DURATION_UNIT = DurationUnit::class.asClassName()\n private val DATA_SIZE = DataSize::class.asClassName()\n private val DATA_SIZE_UNIT = DataSizeUnit::class.asClassName()\n private val PMODULE = PModule::class.asClassName()\n private val PCLASS = PClass::class.asClassName()\n private val REGEX = Regex::class.asClassName()\n private val URI = java.net.URI::class.asClassName()\n private val VERSION = Version::class.asClassName()\n\n private const val PROPERTY_PREFIX: String = \"org.pkl.config.java.mapper.\"\n }\n\n val output: Map\n get() {\n return mapOf(kotlinFileName to kotlinFile, propertyFileName to propertiesFile)\n }\n\n private val propertyFileName: String\n get() =\n \"resources/META-INF/org/pkl/config/java/mapper/classes/${IoUtils.encodePath(moduleSchema.moduleName)}.properties\"\n\n private val propertiesFile: String\n get() {\n val props = Properties()\n props[\"$PROPERTY_PREFIX${moduleSchema.moduleClass.qualifiedName}\"] =\n moduleSchema.moduleClass.toKotlinPoetName().reflectionName()\n for (pClass in moduleSchema.classes.values) {\n props[\"$PROPERTY_PREFIX${pClass.qualifiedName}\"] =\n pClass.toKotlinPoetName().reflectionName()\n }\n return StringWriter()\n .apply { props.store(this, \"Kotlin mappings for Pkl module `${moduleSchema.moduleName}`\") }\n .toString()\n }\n\n private val kotlinFileName: String\n get() = buildString {\n val (packageName, className) = nameMapper.map(moduleSchema.moduleName)\n val dirPath = packageName.split('.').joinToString(\"/\", transform = IoUtils::encodePath)\n val fileName = IoUtils.encodePath(className)\n append(\"kot\")\n append(\"lin/\")\n if (dirPath.isNotEmpty()) {\n append(\"$dirPath/\")\n }\n append(\"$fileName.kt\")\n }\n\n val kotlinFile: String\n get() {\n if (moduleSchema.moduleUri.scheme == \"pkl\") {\n throw KotlinCodeGeneratorException(\n \"Cannot generate Kotlin code for a Pkl standard library module (`${moduleSchema.moduleUri}`).\"\n )\n }\n\n val pModuleClass = moduleSchema.moduleClass\n\n val hasModuleProperties = pModuleClass.properties.any { !it.value.isHidden }\n val isGenerateModuleClass =\n hasModuleProperties || pModuleClass.isOpen || pModuleClass.isAbstract\n\n fun generateCompanionRelatedCode(\n builder: TypeSpec.Builder,\n isModuleType: Boolean = false,\n ): TypeSpec.Builder {\n // ensure that at most one companion object is generated for this type\n val companionObjectBuilder: Lazy = lazy {\n TypeSpec.companionObjectBuilder()\n }\n\n // generate serialization code\n if (\n options.implementSerializable &&\n (!isModuleType || isGenerateModuleClass) &&\n !builder.modifiers.contains(KModifier.ABSTRACT)\n ) {\n builder.addSuperinterface(java.io.Serializable::class.java)\n companionObjectBuilder.value.addProperty(\n PropertySpec.builder(\n \"serialVersionUID\",\n Long::class.java,\n KModifier.PRIVATE,\n KModifier.CONST,\n )\n .initializer(\"0L\")\n .build()\n )\n }\n\n if (companionObjectBuilder.isInitialized()) {\n builder.addType(companionObjectBuilder.value.build())\n }\n\n return builder\n }\n\n val moduleType =\n if (isGenerateModuleClass) {\n generateTypeSpec(pModuleClass, moduleSchema)\n } else {\n generateObjectSpec(pModuleClass)\n }\n\n for (pClass in moduleSchema.classes.values) {\n moduleType.addType(\n generateCompanionRelatedCode(generateTypeSpec(pClass, moduleSchema)).build()\n )\n }\n\n val moduleName = moduleSchema.moduleName\n\n val (packageName, moduleTypeName) = nameMapper.map(moduleName)\n\n val fileSpec = FileSpec.builder(packageName, moduleTypeName).indent(options.indent)\n\n for (typeAlias in moduleSchema.typeAliases.values) {\n if (typeAlias.aliasedType is PType.Alias) {\n // generate top-level type alias (Kotlin doesn't support nested type aliases)\n fileSpec.addTypeAlias(generateTypeAliasSpec(typeAlias).build())\n } else {\n val stringLiterals = mutableSetOf()\n if (CodeGeneratorUtils.isRepresentableAsEnum(typeAlias.aliasedType, stringLiterals)) {\n // generate nested enum class\n moduleType.addType(generateEnumTypeSpec(typeAlias, stringLiterals).build())\n } else {\n // generate top-level type alias (Kotlin doesn't support nested type aliases)\n fileSpec.addTypeAlias(generateTypeAliasSpec(typeAlias).build())\n }\n }\n }\n\n fileSpec.addType(generateCompanionRelatedCode(moduleType, isModuleType = true).build())\n return fileSpec.build().toString()\n }\n\n private fun generateObjectSpec(pClass: PClass): TypeSpec.Builder {\n val builder = TypeSpec.objectBuilder(pClass.toKotlinPoetName())\n val docComment = pClass.docComment\n if (docComment != null && options.generateKdoc) {\n builder.addKdoc(renderAsKdoc(docComment))\n }\n return builder\n }\n\n private fun generateTypeSpec(pClass: PClass, schema: ModuleSchema): TypeSpec.Builder {\n val isModuleClass = pClass == schema.moduleClass\n val kotlinPoetClassName = pClass.toKotlinPoetName()\n val superclass =\n pClass.superclass?.takeIf { it.info != PClassInfo.Typed && it.info != PClassInfo.Module }\n val superProperties = superclass?.allProperties?.filterValues { !it.isHidden } ?: mapOf()\n val properties = pClass.properties.filterValues { !it.isHidden }\n val allProperties = superProperties + properties\n\n fun PClass.Property.isRegex(): Boolean =\n (this.type as? PType.Class)?.pClass?.info == PClassInfo.Regex\n\n fun PClass.Property.isByteArray(): Boolean =\n (this.type as? PType.Class)?.pClass?.info == PClassInfo.Bytes\n\n fun generateConstructor(): FunSpec {\n val builder = FunSpec.constructorBuilder()\n for ((name, property) in allProperties) {\n builder.addParameter(name, property.type.toKotlinPoetName())\n }\n return builder.build()\n }\n\n fun generateCopyMethod(parameters: Map, isOverride: Boolean): FunSpec {\n val methodBuilder = FunSpec.builder(\"copy\").returns(kotlinPoetClassName)\n\n if (isOverride) {\n methodBuilder.addModifiers(KModifier.OVERRIDE)\n }\n if (pClass.isOpen || pClass.isAbstract) {\n methodBuilder.addModifiers(KModifier.OPEN)\n }\n\n for ((name, property) in parameters) {\n val paramBuilder = ParameterSpec.builder(name, property.type.toKotlinPoetName())\n if (!isOverride) {\n paramBuilder.defaultValue(\"this.%N\", name)\n }\n methodBuilder.addParameter(paramBuilder.build())\n }\n\n val codeBuilder = CodeBlock.builder().add(\"return %T(\", kotlinPoetClassName)\n for ((index, name) in allProperties.keys.withIndex()) {\n codeBuilder.add(if (index == 0) \"%N\" else \", %N\", name)\n }\n codeBuilder.add(\")\\n\")\n\n return methodBuilder.addCode(codeBuilder.build()).build()\n }\n\n fun inheritsCopyMethodWithSameArity(): Boolean {\n val nearestNonAbstractAncestor =\n generateSequence(pClass.superclass) { it.superclass }.firstOrNull { !it.isAbstract }\n ?: return false\n return nearestNonAbstractAncestor.allProperties.values.count { !it.isHidden } ==\n allProperties.size\n }\n\n // besides generating copy method for current class,\n // override copy methods inherited from parent classes\n fun generateCopyMethods(typeBuilder: TypeSpec.Builder) {\n // copy methods don't make sense for abstract classes\n if (pClass.isAbstract) return\n\n var prevParameterCount = Int.MAX_VALUE\n for (currClass in generateSequence(pClass) { it.superclass }) {\n if (currClass.isAbstract) continue\n\n val currParameters = currClass.allProperties.filter { !it.value.isHidden }\n\n // avoid generating multiple methods with same no. of parameters\n if (currParameters.size < prevParameterCount) {\n val isOverride = currClass !== pClass || inheritsCopyMethodWithSameArity()\n typeBuilder.addFunction(generateCopyMethod(currParameters, isOverride))\n prevParameterCount = currParameters.size\n }\n }\n }\n\n fun generateEqualsMethod(): FunSpec {\n val builder =\n FunSpec.builder(\"equals\")\n .addModifiers(KModifier.OVERRIDE)\n .addParameter(\"other\", ANY_NULL)\n .returns(BOOLEAN)\n .addStatement(\"if (this === other) return true\")\n // generating this.javaClass instead of class literal avoids a SpotBugs warning\n .addStatement(\"if (this.javaClass != other?.javaClass) return false\")\n .addStatement(\"other as %T\", kotlinPoetClassName)\n\n for ((propertyName, property) in allProperties) {\n if (property.isByteArray()) {\n builder.addStatement(\n \"if (!this.%N.contentEquals(other.%N)) return false\",\n propertyName,\n propertyName,\n )\n } else {\n val accessor = if (property.isRegex()) \"%N.pattern\" else \"%N\"\n builder.addStatement(\n \"if (this.$accessor != other.$accessor) return false\",\n propertyName,\n propertyName,\n )\n }\n }\n\n builder.addStatement(\"return true\")\n return builder.build()\n }\n\n fun generateHashCodeMethod(): FunSpec {\n val builder =\n FunSpec.builder(\"hashCode\")\n .addModifiers(KModifier.OVERRIDE)\n .returns(INT)\n .addStatement(\"var result = 1\")\n\n for ((propertyName, property) in allProperties) {\n if (property.isByteArray()) {\n builder.addStatement(\"result = 31 * result + this.%N.contentHashCode()\", propertyName)\n } else {\n val accessor = if (property.isRegex()) \"this.%N.pattern\" else \"this.%N\"\n // use Objects.hashCode() because Kotlin's Any?.hashCode()\n // doesn't work for platform types (will get NPE if null)\n builder.addStatement(\n \"result = 31 * result + %T.hashCode($accessor)\",\n Objects::class,\n propertyName,\n )\n }\n }\n\n builder.addStatement(\"return result\")\n return builder.build()\n }\n\n // produce same output as default toString() method of data classes\n fun generateToStringMethod(): FunSpec {\n return FunSpec.builder(\"toString\")\n .addModifiers(KModifier.OVERRIDE)\n .returns(STRING)\n .addStatement(\n \"return %P\",\n CodeBlock.builder()\n .apply {\n add(\"%L\", pClass.toKotlinPoetName().simpleName)\n add(\"(\")\n for ((index, entry) in allProperties.entries.withIndex()) {\n val (propertyName, property) = entry\n add(if (index == 0) \"%L\" else \", %L\", propertyName)\n if (property.isByteArray()) {\n add(\"=\\${%T.toString(%L)}\", Arrays::class, propertyName)\n } else {\n add(\"=$\")\n add(\"%N\", propertyName)\n }\n }\n add(\")\")\n }\n .build(),\n )\n .build()\n }\n\n fun generateDeprecation(\n annotations: Collection,\n addAnnotation: (AnnotationSpec) -> Unit,\n ) {\n annotations\n .firstOrNull { it.classInfo == PClassInfo.Deprecated }\n ?.let { deprecation ->\n val builder = AnnotationSpec.builder(Deprecated::class)\n (deprecation[\"message\"] as String?)?.let { builder.addMember(\"message = %S\", it) }\n addAnnotation(builder.build())\n }\n }\n\n fun generateProperty(propertyName: String, property: PClass.Property): PropertySpec {\n val typeName = property.type.toKotlinPoetName()\n val builder = PropertySpec.builder(propertyName, typeName).initializer(\"%L\", propertyName)\n\n generateDeprecation(property.annotations) { builder.addAnnotation(it) }\n\n val docComment = property.docComment\n if (docComment != null && options.generateKdoc) {\n builder.addKdoc(renderAsKdoc(docComment))\n }\n if (propertyName in superProperties) {\n builder.addModifiers(KModifier.OVERRIDE)\n }\n if (pClass.isOpen || pClass.isAbstract) {\n builder.addModifiers(KModifier.OPEN)\n }\n\n return builder.build()\n }\n\n fun generateSpringBootAnnotations(builder: TypeSpec.Builder) {\n if (isModuleClass) {\n builder.addAnnotation(\n ClassName(\"org.springframework.boot.context.properties\", \"ConfigurationProperties\")\n )\n } else {\n // not very efficient to repeat computing module property base types for every class\n val modulePropertiesWithMatchingType =\n schema.moduleClass.allProperties.values.filter { property ->\n var propertyType = property.type\n while (propertyType is PType.Constrained || propertyType is PType.Nullable) {\n if (propertyType is PType.Constrained) {\n propertyType = propertyType.baseType\n } else if (propertyType is PType.Nullable) {\n propertyType = propertyType.baseType\n }\n }\n propertyType is PType.Class && propertyType.pClass == pClass\n }\n if (modulePropertiesWithMatchingType.size == 1) {\n // exactly one module property has this type -> make it available for direct injection\n // (potential improvement: make type available for direct injection if it occurs exactly\n // once in property tree)\n builder.addAnnotation(\n AnnotationSpec.builder(\n ClassName(\"org.springframework.boot.context.properties\", \"ConfigurationProperties\")\n )\n // use \"value\" instead of \"prefix\" to entice JavaPoet to generate a single-line\n // annotation\n // that can easily be filtered out by JavaCodeGeneratorTest.`spring boot config`\n .addMember(\"%S\", modulePropertiesWithMatchingType.first().simpleName)\n .build()\n )\n }\n }\n }\n\n fun generateRegularClass(): TypeSpec.Builder {\n val builder = TypeSpec.classBuilder(kotlinPoetClassName)\n\n if (options.generateSpringBootConfig) {\n generateSpringBootAnnotations(builder)\n }\n if (options.addGeneratedAnnotation) {\n builder.addAnnotation(ClassName(\"org.pkl.config.java\", \"Generated\"))\n }\n\n builder.primaryConstructor(generateConstructor())\n\n val docComment = pClass.docComment\n if (docComment != null && options.generateKdoc) {\n builder.addKdoc(renderAsKdoc(docComment))\n }\n\n if (pClass.isAbstract) {\n builder.addModifiers(KModifier.ABSTRACT)\n } else if (pClass.isOpen) {\n builder.addModifiers(KModifier.OPEN)\n }\n\n superclass?.let { superclass ->\n val superclassName = superclass.toKotlinPoetName()\n builder.superclass(superclassName)\n for (propertyName in superProperties.keys) {\n builder.addSuperclassConstructorParameter(propertyName)\n }\n }\n\n for ((name, property) in properties) {\n builder.addProperty(generateProperty(name, property))\n }\n\n if (!pClass.isAbstract) {\n generateCopyMethods(builder)\n builder\n .addFunction(generateEqualsMethod())\n .addFunction(generateHashCodeMethod())\n .addFunction(generateToStringMethod())\n }\n\n return builder\n }\n\n fun generateDataClass(): TypeSpec.Builder {\n val builder = TypeSpec.classBuilder(kotlinPoetClassName).addModifiers(KModifier.DATA)\n\n if (options.generateSpringBootConfig) {\n generateSpringBootAnnotations(builder)\n }\n if (options.addGeneratedAnnotation) {\n builder.addAnnotation(ClassName(\"org.pkl.config.java\", \"Generated\"))\n }\n\n builder.primaryConstructor(generateConstructor())\n\n generateDeprecation(pClass.annotations) { builder.addAnnotation(it) }\n\n val docComment = pClass.docComment\n if (docComment != null && options.generateKdoc) {\n builder.addKdoc(renderAsKdoc(docComment))\n }\n\n var hasRegexOrByteArray = false\n for ((name, property) in properties) {\n hasRegexOrByteArray = hasRegexOrByteArray || property.isRegex() || property.isByteArray()\n builder.addProperty(generateProperty(name, property))\n }\n\n // Regex and ByteArray define equaltiy as identity.\n // To match Pkl semantics, override equals and hashCode if the data class has a property of\n // type Regex or ByteArray.\n if (hasRegexOrByteArray) {\n builder.addFunction(generateEqualsMethod()).addFunction(generateHashCodeMethod())\n }\n\n return builder\n }\n\n return if (superclass == null && !pClass.isAbstract && !pClass.isOpen) generateDataClass()\n else generateRegularClass()\n }\n\n private fun generateEnumTypeSpec(\n typeAlias: TypeAlias,\n stringLiterals: Set,\n ): TypeSpec.Builder {\n val enumConstantToPklNames =\n stringLiterals\n .groupingBy { literal ->\n CodeGeneratorUtils.toEnumConstantName(literal)\n ?: throw KotlinCodeGeneratorException(\n \"Cannot generate Kotlin enum class for Pkl type alias `${typeAlias.displayName}` \" +\n \"because string literal type \\\"$literal\\\" cannot be converted to a valid enum constant name.\"\n )\n }\n .reduce { enumConstantName, firstLiteral, secondLiteral ->\n throw KotlinCodeGeneratorException(\n \"Cannot generate Kotlin enum class for Pkl type alias `${typeAlias.displayName}` \" +\n \"because string literal types \\\"$firstLiteral\\\" and \\\"$secondLiteral\\\" \" +\n \"would both be converted to enum constant name `$enumConstantName`.\"\n )\n }\n\n val builder =\n TypeSpec.enumBuilder(typeAlias.simpleName)\n .primaryConstructor(\n FunSpec.constructorBuilder().addParameter(\"value\", String::class).build()\n )\n .addProperty(PropertySpec.builder(\"value\", String::class).initializer(\"value\").build())\n .addFunction(\n FunSpec.builder(\"toString\")\n .addModifiers(KModifier.OVERRIDE)\n .addStatement(\"return value\")\n .build()\n )\n for ((enumConstantName, pklName) in enumConstantToPklNames) {\n builder.addEnumConstant(\n enumConstantName,\n TypeSpec.anonymousClassBuilder().addSuperclassConstructorParameter(\"%S\", pklName).build(),\n )\n }\n\n return builder\n }\n\n private fun generateTypeAliasSpec(typeAlias: TypeAlias): TypeAliasSpec.Builder {\n val builder =\n TypeAliasSpec.builder(typeAlias.simpleName, typeAlias.aliasedType.toKotlinPoetName())\n for (typeParameter in typeAlias.typeParameters) {\n builder.addTypeVariable(\n TypeVariableName(typeParameter.name, typeParameter.variance.toKotlinPoet())\n )\n }\n\n val docComment = typeAlias.docComment\n if (docComment != null && options.generateKdoc) {\n builder.addKdoc(renderAsKdoc(docComment))\n }\n\n return builder\n }\n\n private fun TypeParameter.Variance.toKotlinPoet(): KModifier? =\n when (this) {\n TypeParameter.Variance.COVARIANT -> KModifier.OUT\n TypeParameter.Variance.CONTRAVARIANT -> KModifier.IN\n else -> null\n }\n\n // do the minimum work necessary to avoid kotlin compile errors\n // generating idiomatic KDoc would require parsing doc comments, converting member links, etc.\n private fun renderAsKdoc(docComment: String): String = docComment\n\n private fun PClass.toKotlinPoetName(): ClassName {\n val (packageName, moduleTypeName) = nameMapper.map(moduleName)\n return if (isModuleClass) {\n ClassName(packageName, moduleTypeName)\n } else {\n ClassName(packageName, moduleTypeName, simpleName)\n }\n }\n\n private fun TypeAlias.toKotlinPoetName(): ClassName {\n val (packageName, moduleTypeName) = nameMapper.map(moduleName)\n\n return when {\n aliasedType is PType.Alias -> {\n // Kotlin type generated for [this] is a top-level type alias\n ClassName(packageName, simpleName)\n }\n CodeGeneratorUtils.isRepresentableAsEnum(aliasedType, null) -> {\n if (isStandardLibraryMember) {\n throw KotlinCodeGeneratorException(\n \"Standard library typealias `${qualifiedName}` is not supported by Kotlin code generator.\" +\n \" If you think this is an omission, please let us know.\"\n )\n }\n // Kotlin type generated for [this] is a nested enum class\n ClassName(packageName, moduleTypeName, simpleName)\n }\n else -> {\n // Kotlin type generated for [this] is a top-level type alias\n ClassName(packageName, simpleName)\n }\n }\n }\n\n private fun PType.toKotlinPoetName(): TypeName =\n when (this) {\n PType.UNKNOWN -> ANY_NULL\n PType.NOTHING -> NOTHING\n is PType.StringLiteral -> STRING\n is PType.Class -> {\n // if in doubt, spell it out\n when (val classInfo = pClass.info) {\n PClassInfo.Any -> ANY_NULL\n PClassInfo.Typed,\n PClassInfo.Dynamic -> ANY\n PClassInfo.Boolean -> BOOLEAN\n PClassInfo.String -> STRING\n // seems more useful to generate `Double` than `kotlin.Number`\n PClassInfo.Number -> DOUBLE\n PClassInfo.Int -> LONG\n PClassInfo.Float -> DOUBLE\n PClassInfo.Duration -> DURATION\n PClassInfo.DataSize -> DATA_SIZE\n PClassInfo.Bytes -> BYTE_ARRAY\n PClassInfo.Pair ->\n KOTLIN_PAIR.parameterizedBy(\n if (typeArguments.isEmpty()) ANY_NULL else typeArguments[0].toKotlinPoetName(),\n if (typeArguments.isEmpty()) ANY_NULL else typeArguments[1].toKotlinPoetName(),\n )\n PClassInfo.Collection ->\n COLLECTION.parameterizedBy(\n if (typeArguments.isEmpty()) ANY_NULL else typeArguments[0].toKotlinPoetName()\n )\n PClassInfo.List,\n PClassInfo.Listing ->\n LIST.parameterizedBy(\n if (typeArguments.isEmpty()) ANY_NULL else typeArguments[0].toKotlinPoetName()\n )\n PClassInfo.Set ->\n SET.parameterizedBy(\n if (typeArguments.isEmpty()) ANY_NULL else typeArguments[0].toKotlinPoetName()\n )\n PClassInfo.Map,\n PClassInfo.Mapping ->\n MAP.parameterizedBy(\n if (typeArguments.isEmpty()) ANY_NULL else typeArguments[0].toKotlinPoetName(),\n if (typeArguments.isEmpty()) ANY_NULL else typeArguments[1].toKotlinPoetName(),\n )\n PClassInfo.Module -> PMODULE\n PClassInfo.Class -> PCLASS\n PClassInfo.Regex -> REGEX\n PClassInfo.Version -> VERSION\n else ->\n when {\n !classInfo.isStandardLibraryClass -> pClass.toKotlinPoetName()\n else ->\n throw KotlinCodeGeneratorException(\n \"Standard library class `${pClass.qualifiedName}` is not supported by Kotlin code generator. \" +\n \"If you think this is an omission, please let us know.\"\n )\n }\n }\n }\n is PType.Nullable -> baseType.toKotlinPoetName().copy(nullable = true)\n is PType.Constrained -> baseType.toKotlinPoetName()\n is PType.Alias ->\n when (typeAlias.qualifiedName) {\n \"pkl.base#NonNull\" -> ANY\n // Not currently generating Kotlin unsigned types\n // because it's not clear if the benefits outweigh the drawbacks:\n // - breaking change\n // - Kotlin unsigned types aren't intended for domain modeling\n // - diverts from Java code generator\n // - doesn't increase safety\n // - range already checked on Pkl side\n // - conversion to signed type doesn't perform range check\n \"pkl.base#Int8\" -> BYTE\n \"pkl.base#Int16\",\n \"pkl.base#UInt8\" -> SHORT\n \"pkl.base#Int32\",\n \"pkl.base#UInt16\" -> INT\n \"pkl.base#UInt\",\n \"pkl.base#UInt32\" -> LONG\n \"pkl.base#DurationUnit\" -> DURATION_UNIT\n \"pkl.base#DataSizeUnit\" -> DATA_SIZE_UNIT\n \"pkl.base#Uri\" -> URI\n else -> {\n val className = typeAlias.toKotlinPoetName()\n when {\n typeAlias.typeParameters.isEmpty() -> className\n typeArguments.isEmpty() -> {\n // no type arguments provided for a type alias with type parameters -> fill in\n // `Any?` (equivalent of `unknown`)\n val typeArgs = Array(typeAlias.typeParameters.size) { ANY_NULL }\n className.parameterizedBy(*typeArgs)\n }\n else -> className.parameterizedBy(*typeArguments.toKotlinPoet())\n }\n }\n }\n is PType.Function ->\n throw KotlinCodeGeneratorException(\n \"Pkl function types are not supported by the Kotlin code generator.\"\n )\n is PType.Union ->\n if (CodeGeneratorUtils.isRepresentableAsString(this)) STRING\n else\n throw KotlinCodeGeneratorException(\n \"Pkl union types are not supported by the Kotlin code generator.\"\n )\n\n // occurs on RHS of generic type aliases\n is PType.TypeVariable -> TypeVariableName(typeParameter.name)\n else -> throw AssertionError(\"Encountered unexpected PType subclass: $this\")\n }\n\n private fun List.toKotlinPoet(): Array =\n map { it.toKotlinPoetName() }.toTypedArray()\n\n private val nameMapper = NameMapper(options.renames)\n}\n" }, { "path": "pkl-codegen-kotlin/src/main/kotlin/org/pkl/codegen/kotlin/Main.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n@file:JvmName(\"Main\")\n\npackage org.pkl.codegen.kotlin\n\nimport com.github.ajalt.clikt.core.main\nimport com.github.ajalt.clikt.parameters.options.associate\nimport com.github.ajalt.clikt.parameters.options.default\nimport com.github.ajalt.clikt.parameters.options.flag\nimport com.github.ajalt.clikt.parameters.options.option\nimport com.github.ajalt.clikt.parameters.types.path\nimport java.nio.file.Path\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.cliMain\nimport org.pkl.commons.cli.commands.ModulesCommand\nimport org.pkl.commons.cli.commands.installCommonOptions\nimport org.pkl.commons.toPath\nimport org.pkl.core.Release\n\n/** Main method for the Kotlin code generator CLI. */\ninternal fun main(args: Array) {\n cliMain { PklKotlinCodegenCommand().main(args) }\n}\n\nval helpLink = \"${Release.current().documentation.homepage}kotlin-binding/codegen.html#cli\"\n\nclass PklKotlinCodegenCommand : ModulesCommand(name = \"pkl-codegen-kotlin\", helpLink = helpLink) {\n private val defaults = CliKotlinCodeGeneratorOptions(CliBaseOptions(), \"\".toPath())\n\n private val outputDir: Path by\n option(\n names = arrayOf(\"-o\", \"--output-dir\"),\n metavar = \"path\",\n help = \"The directory where generated source code is placed.\",\n )\n .path()\n .default(defaults.outputDir)\n\n private val indent: String by\n option(\n names = arrayOf(\"--indent\"),\n metavar = \"chars\",\n help = \"The characters to use for indenting generated source code.\",\n )\n .default(defaults.indent)\n\n private val generateKdoc: Boolean by\n option(\n names = arrayOf(\"--generate-kdoc\"),\n help = \"Whether to preserve Pkl doc comments by generating corresponding KDoc comments.\",\n )\n .flag()\n\n private val generateSpringboot: Boolean by\n option(\n names = arrayOf(\"--generate-spring-boot\"),\n help = \"Whether to generate config classes for use with Spring Boot.\",\n )\n .flag()\n\n private val implementSerializable: Boolean by\n option(\n names = arrayOf(\"--implement-serializable\"),\n help = \"Whether to generate classes that implement java.io.Serializable.\",\n )\n .flag()\n\n private val addGeneratedAnnotation: Boolean by\n option(\n names = arrayOf(\"--add-generated-annotation\"),\n help = \"Whether to add a @Generated annotation to the types to be generated.\",\n )\n .flag()\n private val renames: Map by\n option(\n names = arrayOf(\"--rename\"),\n metavar = \"old_name=new_name\",\n help =\n \"\"\"\n Replace a prefix in the names of the generated Kotlin classes (repeatable).\n By default, the names of generated classes are derived from the Pkl module names.\n With this option, you can override or modify the default names, renaming entire\n classes or just their packages.\n \"\"\"\n .trimIndent(),\n )\n .associate()\n\n override val helpString: String = \"Generate Kotlin classes and interfaces from Pkl module(s)\"\n\n override fun run() {\n val options =\n CliKotlinCodeGeneratorOptions(\n base = baseOptions.baseOptions(modules, projectOptions),\n outputDir = outputDir,\n indent = indent,\n generateKdoc = generateKdoc,\n generateSpringBootConfig = generateSpringboot,\n implementSerializable = implementSerializable,\n addGeneratedAnnotation = addGeneratedAnnotation,\n renames = renames,\n )\n CliKotlinCodeGenerator(options).run()\n }\n\n init {\n installCommonOptions()\n }\n}\n" }, { "path": "pkl-codegen-kotlin/src/test/kotlin/org/pkl/codegen/kotlin/CliKotlinCodeGeneratorTest.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.codegen.kotlin\n\nimport java.nio.file.Path\nimport org.assertj.core.api.Assertions.assertThat\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.io.TempDir\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.readString\n\nclass CliKotlinCodeGeneratorTest {\n @Test\n fun `module inheritance`(@TempDir tempDir: Path) {\n val module1 =\n PklModule(\n \"org.mod1\",\n \"\"\"\n open module org.mod1\n\n pigeon: Person\n\n class Person {\n name: String\n age: Int\n }\n \"\"\",\n )\n\n val module2 =\n PklModule(\n \"org.mod2\",\n \"\"\"\n module org.mod2\n\n extends \"mod1.pkl\"\n\n parrot: Person\n \"\"\",\n )\n\n val module1File = module1.writeToDisk(tempDir.resolve(\"org/mod1.pkl\"))\n val module2File = module2.writeToDisk(tempDir.resolve(\"org/mod2.pkl\"))\n val outputDir = tempDir.resolve(\"output\")\n\n val generator =\n CliKotlinCodeGenerator(\n CliKotlinCodeGeneratorOptions(\n CliBaseOptions(listOf(module1File.toUri(), module2File.toUri())),\n outputDir,\n )\n )\n\n generator.run()\n\n val module1KotlinFile = outputDir.resolve(\"kotlin/org/Mod1.kt\")\n assertThat(module1KotlinFile).exists()\n\n val module2KotlinFile = outputDir.resolve(\"kotlin/org/Mod2.kt\")\n assertThat(module2KotlinFile).exists()\n\n assertContains(\n \"\"\"\n open class Mod1(\n open val pigeon: Person\n ) {\n \"\"\"\n .trimIndent(),\n module1KotlinFile.readString(),\n )\n\n assertContains(\n \"\"\"\n class Mod2(\n pigeon: Mod1.Person,\n val parrot: Mod1.Person\n ) : Mod1(pigeon) {\n \"\"\"\n .trimIndent(),\n module2KotlinFile.readString(),\n )\n }\n\n @Test\n fun `class name clashes`(@TempDir tempDir: Path) {\n val module1 =\n PklModule(\n \"org.mod1\",\n \"\"\"\n module org.mod1\n\n class Person {\n name: String\n }\n \"\"\",\n )\n\n val module2 =\n PklModule(\n \"org.mod2\",\n \"\"\"\n module org.mod2\n\n import \"mod1.pkl\"\n\n person1: mod1.Person\n person2: Person\n\n class Person {\n age: Int\n }\n \"\"\",\n )\n\n val module1PklFile = module1.writeToDisk(tempDir.resolve(\"org/mod1.pkl\"))\n val module2PklFile = module2.writeToDisk(tempDir.resolve(\"org/mod2.pkl\"))\n val outputDir = tempDir.resolve(\"output\")\n\n val generator =\n CliKotlinCodeGenerator(\n CliKotlinCodeGeneratorOptions(\n CliBaseOptions(listOf(module1PklFile.toUri(), module2PklFile.toUri())),\n outputDir,\n )\n )\n\n generator.run()\n\n val module2KotlinFile = outputDir.resolve(\"kotlin/org/Mod2.kt\")\n assertContains(\n \"\"\"\n data class Mod2(\n val person1: Mod1.Person,\n val person2: Person\n )\n \"\"\"\n .trimIndent(),\n module2KotlinFile.readString(),\n )\n }\n\n @Test\n fun `custom package names`(@TempDir tempDir: Path) {\n val module1 =\n PklModule(\n \"org.foo.Module1\",\n \"\"\"\n module org.foo.Module1\n\n class Person {\n name: String\n }\n \"\"\",\n )\n\n val module2 =\n PklModule(\n \"org.bar.Module2\",\n \"\"\"\n module org.bar.Module2\n \n import \"../../org/foo/Module1.pkl\"\n\n class Group {\n owner: Module1.Person\n name: String\n }\n \"\"\",\n )\n\n val module3 =\n PklModule(\n \"org.baz.Module3\",\n \"\"\"\n module org.baz.Module3\n \n import \"../../org/bar/Module2.pkl\"\n\n class Supergroup {\n owner: Module2.Group\n }\n \"\"\",\n )\n\n val module1PklFile = module1.writeToDisk(tempDir.resolve(\"org/foo/Module1.pkl\"))\n val module2PklFile = module2.writeToDisk(tempDir.resolve(\"org/bar/Module2.pkl\"))\n val module3PklFile = module3.writeToDisk(tempDir.resolve(\"org/baz/Module3.pkl\"))\n val outputDir = tempDir.resolve(\"output\")\n\n val generator =\n CliKotlinCodeGenerator(\n CliKotlinCodeGeneratorOptions(\n CliBaseOptions(listOf(module1PklFile, module2PklFile, module3PklFile).map { it.toUri() }),\n outputDir,\n renames = mapOf(\"org.foo\" to \"com.foo.x\", \"org.baz\" to \"com.baz.a.b\"),\n )\n )\n\n generator.run()\n\n val module1KotlinFile = outputDir.resolve(\"kotlin/com/foo/x/Module1.kt\")\n module1KotlinFile.readString().let {\n assertContains(\"package com.foo.x\", it)\n\n assertContains(\"object Module1 {\", it)\n\n assertContains(\n \"\"\"\n | data class Person(\n | val name: String\n | )\n \"\"\",\n it,\n )\n }\n\n val module2KotlinFile = outputDir.resolve(\"kotlin/org/bar/Module2.kt\")\n module2KotlinFile.readString().let {\n assertContains(\"package org.bar\", it)\n\n assertContains(\"import com.foo.x.Module1\", it)\n\n assertContains(\"object Module2 {\", it)\n\n assertContains(\n \"\"\"\n | data class Group(\n | val owner: Module1.Person,\n | val name: String\n | )\n \"\"\",\n it,\n )\n }\n\n val module3KotlinFile = outputDir.resolve(\"kotlin/com/baz/a/b/Module3.kt\")\n module3KotlinFile.readString().let {\n assertContains(\"package com.baz.a.b\", it)\n\n assertContains(\"import org.bar.Module2\", it)\n\n assertContains(\"object Module3 {\", it)\n\n assertContains(\n \"\"\"\n | data class Supergroup(\n | val owner: Module2.Group\n | )\n \"\"\",\n it,\n )\n }\n }\n\n private fun assertContains(part: String, code: String) {\n val trimmedPart = part.trim().trimMargin()\n if (!code.contains(trimmedPart)) {\n // check for equality to get better error output (ide diff dialog)\n assertThat(code).isEqualTo(trimmedPart)\n }\n }\n}\n" }, { "path": "pkl-codegen-kotlin/src/test/kotlin/org/pkl/codegen/kotlin/InMemoryKotlinCompiler.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.codegen.kotlin\n\nimport javax.script.ScriptEngineManager\nimport javax.script.ScriptException\nimport kotlin.reflect.KClass\nimport kotlin.text.RegexOption.MULTILINE\nimport kotlin.text.RegexOption.UNIX_LINES\n\nclass CompilationFailedException(msg: String?, cause: Throwable? = null) :\n RuntimeException(msg, cause)\n\nobject InMemoryKotlinCompiler {\n // Implementation notes:\n // * all [sourceFiles] are currently combined into a single file\n // * implementation makes assumptions about structure of generated source files\n fun compile(sourceFiles: Map): Map> {\n fun String.findClasses(\n prefix: String = \"\",\n nameGroup: Int = 2,\n bodyGroup: Int = 4,\n regex: String =\n \"^(data |open |enum )?class\\\\s+(\\\\w+) *(\\\\([^)]*\\\\))?.*$\\\\n((^ .*\\\\n|^$\\\\n)*)\",\n transform: (String, String) -> Sequence> = { name, body ->\n sequenceOf(Pair(name, prefix + name)) + body.findClasses(\"$prefix$name.\")\n },\n ): Sequence> = // (simpleName1, qualifiedName1), ...\n Regex(regex, setOf(MULTILINE, UNIX_LINES)).findAll(this).flatMap {\n transform(it.groupValues[nameGroup], it.groupValues[bodyGroup].trimIndent())\n }\n\n fun String.findOuterObjects(): Sequence> = // (simpleName, qualifiedName)\n findClasses(nameGroup = 1, bodyGroup = 2, regex = \"^object\\\\s+(\\\\w+).*$\\n((^ .*$\\n|^$\\n)*)\") {\n name,\n body ->\n body.findClasses(\"$name.\")\n }\n\n val (importLines, remainder) =\n sourceFiles.entries\n .filter { (filename, _) -> filename.endsWith(\".kt\") }\n .flatMap { (_, text) -> text.lines() }\n .partition { it.startsWith(\"import\") }\n val importBlock = importLines.sorted().distinct()\n val (packageLines, code) = remainder.partition { it.startsWith(\"package\") }\n val packageBlock = packageLines.distinct()\n assert(\n packageBlock.size <= 1\n ) // everything is in the same package and/or there is no package line\n val sourceText = listOf(packageBlock, importBlock, code).flatten().joinToString(\"\\n\")\n\n val (simpleNames, qualifiedNames) =\n sourceText.findClasses().plus(sourceText.findOuterObjects()).unzip()\n val instrumentation =\n \"listOf>(${qualifiedNames.joinToString(\",\") { \"$it::class\" }})\"\n\n // create new engine for each compilation\n // (otherwise we sometimes get kotlin compiler exceptions)\n val engine = ScriptEngineManager().getEngineByExtension(\"kts\")!!\n val classes =\n try {\n @Suppress(\"UNCHECKED_CAST\")\n engine.eval(\"$sourceText\\n\\n$instrumentation\") as List>\n } catch (e: ScriptException) {\n throw CompilationFailedException(e.message, e)\n }\n\n return simpleNames.zip(classes).toMap()\n }\n}\n" }, { "path": "pkl-codegen-kotlin/src/test/kotlin/org/pkl/codegen/kotlin/KotlinCodeGeneratorTest.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.codegen.kotlin\n\nimport java.io.*\nimport java.nio.file.Path\nimport kotlin.reflect.KClass\nimport kotlin.reflect.full.declaredMemberProperties\nimport kotlin.reflect.full.memberProperties\nimport org.assertj.core.api.AbstractAssert\nimport org.assertj.core.api.Assertions.assertThat\nimport org.assertj.core.api.Assertions.assertThatCode\nimport org.junit.jupiter.api.Test\nimport org.junit.jupiter.api.assertAll\nimport org.junit.jupiter.api.assertDoesNotThrow\nimport org.junit.jupiter.api.assertThrows\nimport org.junit.jupiter.api.io.TempDir\nimport org.pkl.commons.test.ReflectionUtils.enumValues\nimport org.pkl.core.*\nimport org.pkl.core.util.IoUtils\n\nclass KotlinCodeGeneratorTest {\n companion object {\n private const val MAPPER_PREFIX = \"resources/META-INF/org/pkl/config/java/mapper/classes\"\n\n // according to:\n // https://github.com/JetBrains/kotlin/blob/master/core/descriptors/\n // src/org/jetbrains/kotlin/renderer/KeywordStringsGenerated.java\n private val kotlinKeywords =\n setOf(\n \"package\",\n \"as\",\n \"typealias\",\n \"class\",\n \"this\",\n \"super\",\n \"val\",\n \"var\",\n \"fun\",\n \"for\",\n \"null\",\n \"true\",\n \"false\",\n \"is\",\n \"in\",\n \"throw\",\n \"return\",\n \"break\",\n \"continue\",\n \"object\",\n \"if\",\n \"try\",\n \"else\",\n \"while\",\n \"do\",\n \"when\",\n \"interface\",\n \"typeof\",\n )\n\n private val simpleClass: KClass<*> by lazy {\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n open class Simple {\n str: String\n list: List\n }\n \"\"\"\n .trimIndent()\n )\n .compile()\n .getValue(\"Simple\")\n }\n\n private val propertyTypesKotlinCode: KotlinSourceCode by lazy {\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n open class PropertyTypes {\n boolean: Boolean\n int: Int\n float: Float\n string: String\n duration: Duration\n durationUnit: DurationUnit\n dataSize: DataSize\n dataSizeUnit: DataSizeUnit\n nullable: String?\n nullable2: String?\n pair: Pair\n pair2: Pair\n coll: Collection\n coll2: Collection\n list: List\n list2: List\n set: Set\n set2: Set\n map: Map\n map2: Map\n container: Mapping\n container2: Mapping\n other: Other\n regex: Regex\n any: Any\n nonNull: NonNull\n enum: Direction\n bytes: Bytes\n }\n\n open class Other {\n name: String\n }\n\n typealias Direction = \"north\"|\"east\"|\"south\"|\"west\"\n \"\"\"\n .trimIndent()\n )\n }\n\n private val propertyTypesClasses: Map> by lazy {\n propertyTypesKotlinCode.compile()\n }\n\n private fun generateKotlinCode(\n pklCode: String,\n generateKdoc: Boolean = false,\n generateSpringBootConfig: Boolean = false,\n implementSerializable: Boolean = false,\n ): KotlinSourceCode {\n\n val module = Evaluator.preconfigured().evaluateSchema(ModuleSource.text(pklCode))\n\n val generator =\n KotlinCodeGenerator(\n module,\n KotlinCodeGeneratorOptions(\n generateKdoc = generateKdoc,\n generateSpringBootConfig = generateSpringBootConfig,\n implementSerializable = implementSerializable,\n ),\n )\n return KotlinSourceCode(generator.kotlinFile)\n }\n }\n\n @TempDir lateinit var tempDir: Path\n\n @Test\n fun testEquals() {\n val ctor = simpleClass.constructors.first()\n val instance1 = ctor.call(\"foo\", listOf(1, 2, 3))\n val instance2 = ctor.call(\"foo\", listOf(1, 2, 3))\n val instance3 = ctor.call(\"foo\", listOf(1, 3, 2))\n val instance4 = ctor.call(\"bar\", listOf(1, 2, 3))\n\n assertThat(instance1).isEqualTo(instance1)\n assertThat(instance1).isEqualTo(instance2)\n assertThat(instance2).isEqualTo(instance1)\n\n assertThat(instance3).isNotEqualTo(instance1)\n assertThat(instance4).isNotEqualTo(instance1)\n }\n\n @Test\n fun testHashCode() {\n val ctor = simpleClass.constructors.first()\n val instance1 = ctor.call(\"foo\", listOf(1, 2, 3))\n val instance2 = ctor.call(\"foo\", listOf(1, 2, 3))\n val instance3 = ctor.call(\"foo\", listOf(1, 3, 2))\n val instance4 = ctor.call(\"bar\", listOf(1, 2, 3))\n\n assertThat(instance1.hashCode()).isEqualTo(instance1.hashCode())\n assertThat(instance1.hashCode()).isEqualTo(instance2.hashCode())\n assertThat(instance3.hashCode()).isNotEqualTo(instance1.hashCode())\n assertThat(instance4.hashCode()).isNotEqualTo(instance1.hashCode())\n }\n\n @Test\n fun testToString() {\n val (_, propertyTypes) = instantiateOtherAndPropertyTypes()\n assertThat(propertyTypes.toString())\n .isEqualTo(\n \"\"\"PropertyTypes(boolean=true, int=42, float=42.3, string=string, duration=5.min, \"\"\" +\n \"\"\"durationUnit=min, dataSize=3.gb, dataSizeUnit=gb, nullable=idea, nullable2=null, \"\"\" +\n \"\"\"pair=(1, 2), pair2=(pigeon, Other(name=pigeon)), coll=[1, 2], \"\"\" +\n \"\"\"coll2=[Other(name=pigeon), Other(name=pigeon)], list=[1, 2], \"\"\" +\n \"\"\"list2=[Other(name=pigeon), Other(name=pigeon)], set=[1, 2], \"\"\" +\n \"\"\"set2=[Other(name=pigeon)], map={1=one, 2=two}, map2={one=Other(name=pigeon), \"\"\" +\n \"\"\"two=Other(name=pigeon)}, container={1=one, 2=two}, container2={one=Other(name=pigeon), \"\"\" +\n \"\"\"two=Other(name=pigeon)}, other=Other(name=pigeon), regex=(i?)\\w*, any=Other(name=pigeon), \"\"\" +\n \"\"\"nonNull=Other(name=pigeon), enum=north, \"\"\" +\n \"\"\"bytes=[1, 2, 3, 4])\"\"\"\n )\n }\n\n @Test\n fun `quoted identifiers`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n open class `A Person` {\n `first name`: String\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n | open class `A Person`(\n | open val `first name`: String\n | )\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | override fun toString(): String = \"\"${'\"'}A Person(first name=${'$'}`first name`)\"\"${'\"'}\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | open fun copy(`first name`: String = this.`first name`): `A Person` = `A Person`(`first name`)\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `deprecated property with message`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n class ClassWithDeprecatedProperty {\n @Deprecated { message = \"property deprecation message\" } \n deprecatedProperty: Int = 1337\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .contains(\n \"\"\"\n | data class ClassWithDeprecatedProperty(\n | @Deprecated(message = \"property deprecation message\")\n | val deprecatedProperty: Long\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `deprecated class with message`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n @Deprecated { message = \"class deprecation message\" }\n class DeprecatedClass {\n propertyOfDeprecatedClass: Int = 42\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .contains(\n \"\"\"\n | @Deprecated(message = \"class deprecation message\")\n | data class DeprecatedClass(\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `deprecated module class with message`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n @Deprecated{ message = \"module class deprecation message\" }\n module DeprecatedModule\n \n propertyInDeprecatedModuleClass : Int = 42\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .contains(\n \"\"\"\n |@Deprecated(message = \"module class deprecation message\")\n |data class DeprecatedModule(\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `deprecated property`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n class ClassWithDeprecatedProperty {\n @Deprecated\n deprecatedProperty: Int = 1337\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .contains(\n \"\"\"\n | data class ClassWithDeprecatedProperty(\n | @Deprecated\n | val deprecatedProperty: Long\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `deprecated class`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n @Deprecated\n class DeprecatedClass {\n propertyOfDeprecatedClass: Int = 42\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .contains(\n \"\"\"\n | @Deprecated\n | data class DeprecatedClass(\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `deprecated module class`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n @Deprecated\n module DeprecatedModule\n \n propertyInDeprecatedModuleClass : Int = 42\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .contains(\n \"\"\"\n |@Deprecated\n |data class DeprecatedModule(\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun properties() {\n val (other, propertyTypes) = instantiateOtherAndPropertyTypes()\n\n assertThat(readProperty(other, \"name\")).isEqualTo(\"pigeon\")\n assertThat(readProperty(propertyTypes, \"boolean\")).isEqualTo(true)\n assertThat(readProperty(propertyTypes, \"int\")).isEqualTo(42L)\n assertThat(readProperty(propertyTypes, \"float\")).isEqualTo(42.3)\n assertThat(readProperty(propertyTypes, \"string\")).isEqualTo(\"string\")\n assertThat(readProperty(propertyTypes, \"duration\"))\n .isEqualTo(Duration(5.0, DurationUnit.MINUTES))\n assertThat(readProperty(propertyTypes, \"dataSize\"))\n .isEqualTo(DataSize(3.0, DataSizeUnit.GIGABYTES))\n assertThat(readProperty(propertyTypes, \"nullable\")).isEqualTo(\"idea\")\n assertThat(readProperty(propertyTypes, \"nullable2\")).isEqualTo(null)\n assertThat(readProperty(propertyTypes, \"list\")).isEqualTo(listOf(1, 2))\n assertThat(readProperty(propertyTypes, \"list2\")).isEqualTo(listOf(other, other))\n assertThat(readProperty(propertyTypes, \"set\")).isEqualTo(setOf(1, 2))\n assertThat(readProperty(propertyTypes, \"set2\")).isEqualTo(setOf(other))\n assertThat(readProperty(propertyTypes, \"map\")).isEqualTo(mapOf(1 to \"one\", 2 to \"two\"))\n assertThat(readProperty(propertyTypes, \"map2\")).isEqualTo(mapOf(\"one\" to other, \"two\" to other))\n assertThat(readProperty(propertyTypes, \"container\")).isEqualTo(mapOf(1 to \"one\", 2 to \"two\"))\n assertThat(readProperty(propertyTypes, \"container2\"))\n .isEqualTo(mapOf(\"one\" to other, \"two\" to other))\n assertThat(readProperty(propertyTypes, \"other\")).isEqualTo(other)\n assertThat(readProperty(propertyTypes, \"regex\")).isInstanceOf(Regex::class.java)\n assertThat(readProperty(propertyTypes, \"any\")).isEqualTo(other)\n assertThat(readProperty(propertyTypes, \"nonNull\")).isEqualTo(other)\n assertThat(readProperty(propertyTypes, \"bytes\")).isEqualTo(byteArrayOf(1, 2, 3, 4))\n }\n\n private fun readProperty(receiver: Any, name: String): Any? {\n val property = receiver.javaClass.kotlin.memberProperties.find { it.name == name }!!\n return property.invoke(receiver)\n }\n\n @Test\n fun `properties 2`() {\n assertThat(propertyTypesKotlinCode).isEqualToResourceFile(\"PropertyTypes.kotlin\")\n }\n\n @Test\n fun `enum constant names`() {\n val cases =\n listOf(\n \"camelCasedName\" to \"CAMEL_CASED_NAME\",\n \"hyphenated-name\" to \"HYPHENATED_NAME\",\n \"EnQuad\\u2000EmSpace\\u2003IdeographicSpace\\u3000\" to \"EN_QUAD_EM_SPACE_IDEOGRAPHIC_SPACE_\",\n \"ᾊᾨ\" to \"ᾊᾨ\",\n \"0-digit\" to \"_0_DIGIT\",\n \"digit-1\" to \"DIGIT_1\",\n \"42\" to \"_42\",\n \"àœü\" to \"ÀŒÜ\",\n \"日本-つくば\" to \"日本_つくば\",\n )\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n typealias MyTypeAlias = ${cases.joinToString(\" | \") { \"\\\"${it.first}\\\"\" }}\n \"\"\"\n .trimIndent()\n )\n val kotlinClass = kotlinCode.compile().getValue(\"MyTypeAlias\")\n\n assertThat(kotlinClass.enumValues().size)\n .isEqualTo(cases.size) // make sure zip doesn't drop cases\n\n assertAll(\n kotlinClass.enumValues().zip(cases) { enumValue, (pklName, kotlinName) ->\n {\n assertThat(enumValue.name).isEqualTo(kotlinName)\n assertThat(enumValue.toString()).isEqualTo(pklName)\n }\n }\n )\n }\n\n @Test\n fun `conflicting enum constant names`() {\n val exception =\n assertThrows {\n generateKotlinCode(\n \"\"\"\n module my.mod\n typealias MyTypeAlias = \"foo-bar\" | \"foo bar\"\n \"\"\"\n .trimIndent()\n )\n }\n assertThat(exception)\n .hasMessageContainingAll(\"both be converted to enum constant name\", \"FOO_BAR\")\n }\n\n @Test\n fun `empty enum constant name`() {\n val exception =\n assertThrows {\n generateKotlinCode(\n \"\"\"\n module my.mod\n typealias MyTypeAlias = \"foo\" | \"\" | \"bar\"\n \"\"\"\n .trimIndent()\n )\n }\n assertThat(exception).hasMessageContaining(\"cannot be converted\")\n }\n\n @Test\n fun `inconvertible enum constant name`() {\n val exception =\n assertThrows {\n generateKotlinCode(\n \"\"\"\n module my.mod\n typealias MyTypeAlias = \"foo\" | \"✅\" | \"bar\"\n \"\"\"\n .trimIndent()\n )\n }\n assertThat(exception).hasMessageContainingAll(\"✅\", \"cannot be converted\")\n }\n\n @Test\n fun `data class`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n class Person {\n name: String\n age: Int\n hobbies: List\n friends: Map\n sibling: Person?\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n .isEqualTo(\n \"\"\"\n package my\n \n import kotlin.Long\n import kotlin.String\n import kotlin.collections.List\n import kotlin.collections.Map\n \n object Mod {\n data class Person(\n val name: String,\n val age: Long,\n val hobbies: List,\n val friends: Map,\n val sibling: Person?\n )\n }\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `data class with Regex property has custom equals and hashCode methods`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n class Person {\n age: Int\n name: Regex\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .contains(\"if (this.name.pattern != other.name.pattern) return false\")\n .contains(\"result = 31 * result + Objects.hashCode(this.name.pattern)\")\n }\n\n @Test\n fun `data class with ByteArray property has custom equals and hashCode methods`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n class Foo {\n bytes: Bytes\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .contains(\"if (!this.bytes.contentEquals(other.bytes)) return false\")\n .contains(\"result = 31 * result + this.bytes.contentHashCode()\")\n }\n\n @Test\n fun `recursive types`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n open class Foo {\n other: Int\n bar: Bar\n }\n open class Bar {\n foo: Foo\n other: String\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n | open class Foo(\n | open val other: Long,\n | open val bar: Bar\n | )\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | open class Bar(\n | open val foo: Foo,\n | open val other: String\n | )\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun inheritance() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n open class Foo {\n one: Int\n }\n open class None extends Foo {}\n open class Bar extends None {\n two: String\n }\n class Baz extends Bar {\n three: Duration\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n | open class Foo(\n | open val one: Long\n | )\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | open class None(\n | one: Long\n | ) : Foo(one)\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | open class Bar(\n | one: Long,\n | open val two: String\n | ) : None(one)\n \"\"\"\n .trimMargin()\n )\n .isEqualToResourceFile(\"Inheritance.kotlin\")\n }\n\n @Test\n fun `stateless classes`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n class Foo\n abstract class Bar\n class Baz extends Bar\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .contains(\n \"\"\"\n | data class Foo\n |\n | abstract class Bar\n |\n | class Baz : Bar() {\n | fun copy(): Baz = Baz()\n \"\"\"\n .trimMargin()\n )\n }\n\n // https://github.com/apple/pkl/issues/569\n @Test\n fun `abstract classes`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n abstract class Foo { one: Int }\n abstract class Bar extends Foo { two: String }\n class Baz extends Bar { three: Duration }\n class Qux extends Bar {}\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n // missing trailing `{` proves that no methods are generated\n .contains(\n \"\"\"\n | abstract class Foo(\n | open val one: Long\n | )\n \"\"\"\n .trimMargin()\n )\n // missing trailing `{` proves that no methods are generated\n .contains(\n \"\"\"\n | abstract class Bar(\n | one: Long,\n | open val two: String\n | ) : Foo(one)\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | class Baz(\n | one: Long,\n | two: String,\n | val three: Duration\n | ) : Bar(one, two) {\n | fun copy(\n | one: Long = this.one,\n | two: String = this.two,\n | three: Duration = this.three\n | ): Baz = Baz(one, two, three)\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | class Qux(\n | one: Long,\n | two: String\n | ) : Bar(one, two) {\n | fun copy(one: Long = this.one, two: String = this.two): Qux = Qux(one, two)\n \"\"\"\n .trimMargin()\n )\n }\n\n // https://github.com/apple/pkl/issues/569\n @Test\n fun `abstract class that extends open class`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n open class Foo { one: Int }\n abstract class Bar extends Foo { two: String }\n class Baz extends Bar { three: Duration }\n class Qux extends Bar {}\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n | open class Foo(\n | open val one: Long\n | ) {\n | open fun copy(one: Long = this.one): Foo = Foo(one)\n \"\"\"\n .trimMargin()\n )\n // missing trailing `{` proves that no methods are generated\n .contains(\n \"\"\"\n | abstract class Bar(\n | one: Long,\n | open val two: String\n | ) : Foo(one)\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | class Baz(\n | one: Long,\n | two: String,\n | val three: Duration\n | ) : Bar(one, two) {\n | fun copy(\n | one: Long = this.one,\n | two: String = this.two,\n | three: Duration = this.three\n | ): Baz = Baz(one, two, three)\n |\n | override fun copy(one: Long): Baz = Baz(one, two, three)\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | class Qux(\n | one: Long,\n | two: String\n | ) : Bar(one, two) {\n | fun copy(one: Long = this.one, two: String = this.two): Qux = Qux(one, two)\n |\n | override fun copy(one: Long): Qux = Qux(one, two)\n \"\"\"\n .trimMargin()\n )\n }\n\n // https://github.com/apple/pkl/issues/569\n @Test\n fun `abstract class that extends open class without adding properties`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n open class Foo { one: Int }\n abstract class Bar extends Foo {}\n class Baz extends Bar { two: Duration }\n class Qux extends Bar {}\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n | open class Foo(\n | open val one: Long\n | ) {\n | open fun copy(one: Long = this.one): Foo = Foo(one)\n \"\"\"\n .trimMargin()\n )\n // missing trailing `{` proves that no methods are generated\n .contains(\n \"\"\"\n | abstract class Bar(\n | one: Long\n | ) : Foo(one)\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | class Baz(\n | one: Long,\n | val two: Duration\n | ) : Bar(one) {\n | fun copy(one: Long = this.one, two: Duration = this.two): Baz = Baz(one, two)\n |\n | override fun copy(one: Long): Baz = Baz(one, two)\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | class Qux(\n | one: Long\n | ) : Bar(one) {\n | override fun copy(one: Long): Qux = Qux(one)\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun keywords() {\n val props = kotlinKeywords.joinToString(\"\\n\") { \"`$it`: Int\" }\n\n val fooClass =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n class Foo {\n $props\n }\n \"\"\"\n .trimIndent()\n )\n .compile()\n .getValue(\"Foo\")\n\n assertThat(fooClass.declaredMemberProperties.map { it.name }).hasSameElementsAs(kotlinKeywords)\n }\n\n @Test\n fun `module properties`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n pigeon: Person\n parrot: Person\n\n class Person {\n name: String\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n .isEqualTo(\n \"\"\"\n package my\n\n import kotlin.String\n \n data class Mod(\n val pigeon: Person,\n val parrot: Person\n ) {\n data class Person(\n val name: String\n )\n }\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `simple module name`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module mod\n\n pigeon: Person\n parrot: Person\n\n class Person {\n name: String\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n .isEqualTo(\n \"\"\"\n import kotlin.String\n\n data class Mod(\n val pigeon: Person,\n val parrot: Person\n ) {\n data class Person(\n val name: String\n )\n }\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `hidden properties`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n hidden pigeon1: String\n parrot1: String\n\n class Persons {\n hidden pigeon2: String\n parrot2: String\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .doesNotContain(\"pigeon1: String\")\n .contains(\"parrot1: String\")\n .doesNotContain(\"pigeon2: String\")\n .contains(\"parrot2: String\")\n }\n\n @Test\n fun kdoc() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n /// module comment.\n /// *emphasized* `code`.\n module my.mod\n\n /// module property comment.\n /// *emphasized* `code`.\n pigeon: Person\n\n /// class comment.\n /// *emphasized* `code`.\n open class Product {\n /// class property comment.\n /// *emphasized* `code`.\n price: String\n }\n\n /// class comment.\n /// *emphasized* `code`.\n class Person {\n /// class property comment.\n /// *emphasized* `code`.\n name: String\n }\n\n /// type alias comment.\n /// *emphasized* `code`.\n typealias Email = String(contains(\"@\"))\n \"\"\"\n .trimIndent(),\n generateKdoc = true,\n )\n\n assertThat(kotlinCode).compilesSuccessfully().isEqualToResourceFile(\"Kdoc.kotlin\")\n }\n\n @Test\n fun `kdoc 2`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n /// module comment.\n /// *emphasized* `code`.\n module my.mod\n\n class Product\n \"\"\"\n .trimIndent(),\n generateKdoc = true,\n )\n\n assertThat(kotlinCode)\n .isEqualTo(\n \"\"\"\n package my\n\n /**\n * module comment.\n * *emphasized* `code`.\n */\n object Mod {\n data class Product\n }\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `pkl_base type aliases`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module mod\n\n uint8: UInt8\n uint16: UInt16\n uint32: UInt32\n uint: UInt\n int8: Int8\n int16: Int16\n int32: Int32\n uri: Uri\n\n pair: Pair\n list: List\n set: Set\n map: Map\n listing: Listing\n mapping: Mapping\n nullable: UInt16?\n\n class Foo {\n uint8: UInt8\n uint16: UInt16\n uint32: UInt32\n uint: UInt\n int8: Int8\n int16: Int16\n int32: Int32\n uri: Uri\n list: List\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n .isEqualTo(\n \"\"\"\n import java.net.URI\n import kotlin.Byte\n import kotlin.Int\n import kotlin.Long\n import kotlin.Pair\n import kotlin.Short\n import kotlin.collections.List\n import kotlin.collections.Map\n import kotlin.collections.Set\n \n data class Mod(\n val uint8: Short,\n val uint16: Int,\n val uint32: Long,\n val uint: Long,\n val int8: Byte,\n val int16: Short,\n val int32: Int,\n val uri: URI,\n val pair: Pair,\n val list: List,\n val set: Set,\n val map: Map,\n val listing: List,\n val mapping: Map,\n val nullable: Int?\n ) {\n data class Foo(\n val uint8: Short,\n val uint16: Int,\n val uint32: Long,\n val uint: Long,\n val int8: Byte,\n val int16: Short,\n val int32: Int,\n val uri: URI,\n val list: List\n )\n }\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun `user defined type aliases`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module mod\n\n typealias Simple = String\n typealias Constrained = String(length >= 3)\n typealias Parameterized = List\n typealias Recursive1 = Parameterized(nonEmpty)\n typealias Recursive2 = List\n\n simple: Simple\n constrained: Constrained\n parameterized: Parameterized\n recursive1: Recursive1\n recursive2: Recursive2\n\n class Foo {\n simple: Simple\n constrained: Constrained\n parameterized: Parameterized\n recursive1: Recursive1\n recursive2: Recursive2\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n .isEqualTo(\n \"\"\"\n import kotlin.Long\n import kotlin.String\n import kotlin.collections.List\n \n typealias Simple = String\n \n typealias Constrained = String\n \n typealias Parameterized = List\n \n typealias Recursive1 = Parameterized\n \n typealias Recursive2 = List\n \n data class Mod(\n val simple: Simple,\n val constrained: Constrained,\n val parameterized: Parameterized,\n val recursive1: Recursive1,\n val recursive2: Recursive2\n ) {\n data class Foo(\n val simple: Simple,\n val constrained: Constrained,\n val parameterized: Parameterized,\n val recursive1: Recursive1,\n val recursive2: Recursive2\n )\n }\n \n \"\"\"\n .trimIndent()\n )\n }\n\n @Test\n fun genericTypeAliases() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module mod\n\n class Person { name: String }\n\n typealias List2 = List\n typealias Map2 = Map\n typealias StringMap = Map\n typealias MMap = Map\n\n res1: List2\n res2: List2>\n res3: Map2\n res4: StringMap\n res5: MMap\n\n res6: List2\n res7: Map2\n res8: StringMap\n res9: MMap\n\n class Foo {\n res1: List2\n res2: List2>\n res3: Map2\n res4: StringMap\n res5: MMap\n\n res6: List2\n res7: Map2\n res8: StringMap\n res9: MMap\n }\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n |data class Mod(\n | val res1: List2,\n | val res2: List2>,\n | val res3: Map2,\n | val res4: StringMap,\n | val res5: MMap,\n | val res6: List2,\n | val res7: Map2,\n | val res8: StringMap,\n | val res9: MMap\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | data class Foo(\n | val res1: List2,\n | val res2: List2>,\n | val res3: Map2,\n | val res4: StringMap,\n | val res5: MMap,\n | val res6: List2,\n | val res7: Map2,\n | val res8: StringMap,\n | val res9: MMap\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `union of string literals`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module mod\n\n x: \"Pigeon\"|\"Barn Owl\"|\"Parrot\"\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .compilesSuccessfully()\n .contains(\n \"\"\"\n |data class Mod(\n | val x: String\n |)\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `other union type`() {\n val e =\n assertThrows {\n generateKotlinCode(\n \"\"\"\n module mod\n \n x: \"Pigeon\"|Int|\"Parrot\"\n \"\"\"\n .trimIndent()\n )\n }\n assertThat(e).hasMessageContaining(\"Pkl union types are not supported\")\n }\n\n @Test\n fun `stringy type`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module mod\n\n v1: \"RELEASE\"\n v2: \"RELEASE\"|String\n v3: String|\"RELEASE\"\n v4: \"RELEASE\"|String|\"LATEST\"\n v5: Version|String|\"LATEST\"\n v6: (Version|String)|(\"LATEST\"|String)\n \n typealias Version = \"RELEASE\"|String|\"LATEST\"\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .contains(\"v1: String\")\n .contains(\"v2: String\")\n .contains(\"v3: String\")\n .contains(\"v4: String\")\n .contains(\"v5: String\")\n .contains(\"v6: String\")\n }\n\n @Test\n fun `stringy type alias`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module mod\n\n typealias Version1 = \"RELEASE\"|String\n typealias Version2 = String|\"RELEASE\"\n typealias Version3 = \"RELEASE\"|String|\"LATEST\"\n typealias Version4 = Version3|String|\"LATEST\" // ideally wouldn't be inlined\n typealias Version5 = (Version4|String)|(\"LATEST\"|String)\n typealias Version6 = Version5 // not inlined\n \"\"\"\n .trimIndent()\n )\n\n assertThat(kotlinCode)\n .contains(\"typealias Version1 = String\")\n .contains(\"typealias Version2 = String\")\n .contains(\"typealias Version3 = String\")\n .contains(\"typealias Version4 = String\")\n .contains(\"typealias Version5 = String\")\n .contains(\"typealias Version6 = Version5\")\n }\n\n @Test\n fun `spring boot config`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module my.mod\n\n server: Server\n\n class Server {\n port: Int\n urls: Listing\n }\n \"\"\"\n .trimIndent(),\n generateSpringBootConfig = true,\n )\n\n assertThat(kotlinCode)\n .contains(\n \"\"\"\n |@ConfigurationProperties\n |data class Mod(\n | val server: Server\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | @ConfigurationProperties(\"server\")\n | data class Server(\n | val port: Long,\n | val urls: List\n \"\"\"\n .trimMargin()\n )\n .doesNotContain(\"@ConstructorBinding\")\n\n // not worthwhile to add spring & spring boot dependency just so that this test can compile\n // their annotations\n val kotlinCodeWithoutSpringAnnotations =\n kotlinCode.deleteLines { it.contains(\"ConfigurationProperties\") }\n assertThat(kotlinCodeWithoutSpringAnnotations).compilesSuccessfully()\n }\n\n @Test\n fun `import module`() {\n val library =\n PklModule(\n \"library\",\n \"\"\"\n module library\n \n class Person { name: String; age: Int }\n \n pigeon: Person\n \"\"\"\n .trimIndent(),\n )\n\n val client =\n PklModule(\n \"client\",\n \"\"\"\n module client\n \n import \"library.pkl\"\n \n lib: library\n \n parrot: library.Person\n \"\"\"\n .trimIndent(),\n )\n\n val kotlinSourceFiles = generateFiles(library, client)\n assertDoesNotThrow {\n InMemoryKotlinCompiler.compile(kotlinSourceFiles.mapValues { it.value.text })\n }\n\n val kotlinClientCode =\n kotlinSourceFiles.entries.find { (fileName, _) -> fileName.endsWith(\"Client.kt\") }!!.value\n\n assertThat(kotlinClientCode)\n .contains(\n \"\"\"\n |data class Client(\n | val lib: Library,\n | val parrot: Library.Person\n |)\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `extend module`() {\n val base =\n PklModule(\n \"base\",\n \"\"\"\n open module base\n \n open class Person { name: String }\n \n pigeon: Person\n \"\"\"\n .trimIndent(),\n )\n\n val derived =\n PklModule(\n \"derived\",\n \"\"\"\n module derived\n extends \"base.pkl\"\n \n class Person2 extends Person { age: Int }\n \n person1: Person\n person2: Person2\n \"\"\"\n .trimIndent(),\n )\n\n val kotlinSourceFiles = generateFiles(base, derived)\n assertDoesNotThrow {\n InMemoryKotlinCompiler.compile(kotlinSourceFiles.mapValues { it.value.text })\n }\n\n val kotlinDerivedCode =\n kotlinSourceFiles.entries.find { (filename, _) -> filename.endsWith(\"Derived.kt\") }!!.value\n\n assertThat(kotlinDerivedCode)\n .contains(\n \"\"\"\n |class Derived(\n | pigeon: Base.Person,\n | val person1: Base.Person,\n | val person2: Person2\n |) : Base(pigeon)\n \"\"\"\n .trimMargin()\n )\n .contains(\n \"\"\"\n | class Person2(\n | name: String,\n | val age: Long\n | ) : Base.Person(name)\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `empty module`() {\n val kotlinCode = generateKotlinCode(\"module mod\")\n assertThat(kotlinCode).isEqualTo(\"object Mod\\n\")\n }\n\n @Test\n fun `extend module that only contains type aliases`() {\n val moduleOne =\n PklModule(\n \"base\",\n \"\"\"\n abstract module base\n \n typealias Version = \"LATEST\"|String\n \"\"\"\n .trimIndent(),\n )\n\n val moduleTwo =\n PklModule(\n \"derived\",\n \"\"\"\n module derived\n \n extends \"base.pkl\"\n \n v: Version = \"1.2.3\"\n \"\"\"\n .trimIndent(),\n )\n\n val kotlinSourceFiles = generateFiles(moduleOne, moduleTwo)\n assertDoesNotThrow {\n InMemoryKotlinCompiler.compile(kotlinSourceFiles.mapValues { it.value.text })\n }\n\n val kotlinDerivedCode =\n kotlinSourceFiles.entries.find { (filename, _) -> filename.endsWith(\"Derived.kt\") }!!.value\n assertThat(kotlinDerivedCode)\n .contains(\n \"\"\"\n |class Derived(\n | val v: Version\n |) : Base()\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `generated properties files`() {\n val pklModule =\n PklModule(\n \"Mod.pkl\",\n \"\"\"\n module org.pkl.Mod\n \n foo: Foo\n \n bar: Bar\n \n class Foo {\n prop: String\n }\n \n class Bar {\n prop: Int\n }\n \"\"\"\n .trimIndent(),\n )\n val generated = generateFiles(pklModule)\n val expectedPropertyFile =\n \"resources/META-INF/org/pkl/config/java/mapper/classes/org.pkl.Mod.properties\"\n assertThat(generated).containsKey(expectedPropertyFile)\n val propertyFileContents = generated[expectedPropertyFile]!!\n assertThat(propertyFileContents)\n .contains(\"org.pkl.config.java.mapper.org.pkl.Mod\\\\#ModuleClass=org.pkl.Mod\")\n .contains(\"org.pkl.config.java.mapper.org.pkl.Mod\\\\#Foo=org.pkl.Mod\\$Foo\")\n .contains(\"org.pkl.config.java.mapper.org.pkl.Mod\\\\#Bar=org.pkl.Mod\\$Bar\")\n }\n\n @Test\n fun `generates serializable classes`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module mod\n\n class BigStruct {\n boolean: Boolean\n int: Int\n float: Float\n string: String\n duration: Duration\n dataSize: DataSize\n pair: Pair\n pair2: Pair\n coll: Collection\n coll2: Collection\n list: List\n list2: List\n set: Set\n set2: Set\n map: Map\n map2: Map\n container: Mapping\n container2: Mapping\n other: SmallStruct\n regex: Regex\n nonNull: NonNull\n enum: Direction\n }\n\n class SmallStruct {\n name: String\n }\n\n typealias Direction = \"north\"|\"east\"|\"south\"|\"west\"\n \n abstract class NotSerializable\n \"\"\"\n .trimIndent(),\n implementSerializable = true,\n )\n\n assertThat(kotlinCode)\n .contains(\": Serializable\")\n .contains(\"private const val serialVersionUID: Long = 0L\")\n .contains(\"abstract class NotSerializable\\n\")\n\n val classes = kotlinCode.compile()\n val enumClass = classes.getValue(\"Direction\")\n val enumValue = enumClass.java.enumConstants.first()\n\n val smallStructCtor = classes.getValue(\"SmallStruct\").constructors.first()\n val smallStruct = smallStructCtor.call(\"pigeon\")\n\n val bigStructCtor = classes.getValue(\"BigStruct\").constructors.first()\n val bigStruct =\n bigStructCtor.call(\n true,\n 42L,\n 42.3,\n \"string\",\n Duration(5.0, DurationUnit.MINUTES),\n DataSize(3.0, DataSizeUnit.GIGABYTES),\n kotlin.Pair(1, 2),\n kotlin.Pair(\"pigeon\", smallStruct),\n listOf(1, 2, 3),\n listOf(smallStruct, smallStruct),\n listOf(1, 2, 3),\n listOf(smallStruct, smallStruct),\n setOf(1, 2, 3),\n setOf(smallStruct, smallStruct),\n mapOf(1 to \"one\", 2 to \"two\"),\n mapOf(\"one\" to smallStruct, \"two\" to smallStruct),\n mapOf(1 to \"one\", 2 to \"two\"),\n mapOf(\"one\" to smallStruct, \"two\" to smallStruct),\n smallStruct,\n Regex(\"(i?)\\\\w*\"),\n smallStruct,\n enumValue,\n )\n\n fun confirmSerDe(instance: Any) {\n var restoredInstance: Any? = null\n\n assertThatCode {\n // serialize\n val baos = ByteArrayOutputStream()\n val oos = ObjectOutputStream(baos)\n oos.writeObject(instance)\n oos.flush()\n\n // deserialize\n val bais = ByteArrayInputStream(baos.toByteArray())\n val ois =\n object : ObjectInputStream(bais) {\n override fun resolveClass(desc: ObjectStreamClass?): Class<*> {\n return Class.forName(desc!!.name, false, instance.javaClass.classLoader)\n }\n }\n restoredInstance = ois.readObject()\n }\n .doesNotThrowAnyException()\n\n assertThat(restoredInstance!!).isEqualTo(instance)\n }\n\n confirmSerDe(enumValue)\n confirmSerDe(smallStruct)\n confirmSerDe(bigStruct)\n }\n\n @Test\n fun `generates serializable module classes`() {\n val kotlinCode =\n generateKotlinCode(\n \"\"\"\n module Person\n \n address: Address\n \n class Address {\n street: String\n }\n \"\"\",\n implementSerializable = true,\n )\n\n assertThat(kotlinCode)\n .contains(\n \"\"\"\n |data class Person(\n | val address: Address\n |) : Serializable {\n | data class Address(\n | val street: String\n | ) : Serializable {\n | companion object {\n | private const val serialVersionUID: Long = 0L\n | }\n | }\n |\n | companion object {\n | private const val serialVersionUID: Long = 0L\n | }\n |}\n \"\"\"\n .trimMargin()\n )\n }\n\n @Test\n fun `encoded file paths`() {\n val kotlinCode =\n generateFiles(\n PklModule(\n \"FooBar.pkl\",\n \"\"\"\n module `Foo*Bar`\n \n someProp: String\n \"\"\"\n .trimIndent(),\n )\n )\n assertThat(kotlinCode).containsKey(\"kotlin/Foo(2a)Bar.kt\")\n }\n\n @Test\n fun `override names in a standalone module`() {\n val files =\n KotlinCodeGeneratorOptions(\n renames = mapOf(\"a.b.c\" to \"x.y.z\", \"d.e.f.AnotherModule\" to \"u.v.w.RenamedModule\")\n )\n .generateFiles(\n \"MyModule.pkl\" to\n \"\"\"\n module a.b.c.MyModule\n \n foo: String = \"abc\"\n \"\"\"\n .trimIndent(),\n \"AnotherModule.pkl\" to\n \"\"\"\n module d.e.f.AnotherModule\n \n bar: Int = 123\n \"\"\"\n .trimIndent(),\n )\n .toMutableMap()\n\n files.validateContents(\n \"kotlin/x/y/z/MyModule.kt\" to listOf(\"package x.y.z\", \"data class MyModule(\"),\n \"$MAPPER_PREFIX/a.b.c.MyModule.properties\" to\n listOf(\"org.pkl.config.java.mapper.a.b.c.MyModule\\\\#ModuleClass=x.y.z.MyModule\"),\n // ---\n \"kotlin/u/v/w/RenamedModule.kt\" to listOf(\"package u.v.w\", \"data class RenamedModule(\"),\n \"$MAPPER_PREFIX/d.e.f.AnotherModule.properties\" to\n listOf(\"org.pkl.config.java.mapper.d.e.f.AnotherModule\\\\#ModuleClass=u.v.w.RenamedModule\"),\n )\n }\n\n @Test\n fun `override names based on the longest prefix`() {\n val files =\n KotlinCodeGeneratorOptions(\n renames = mapOf(\"com.foo.bar.\" to \"x.\", \"com.foo.\" to \"y.\", \"com.\" to \"z.\", \"\" to \"w.\")\n )\n .generateFiles(\n \"com/foo/bar/Module1\" to\n \"\"\"\n module com.foo.bar.Module1\n \n bar: String\n \"\"\"\n .trimIndent(),\n \"com/Module2\" to\n \"\"\"\n module com.Module2\n \n com: String\n \"\"\"\n .trimIndent(),\n \"org/baz/Module3\" to\n \"\"\"\n module org.baz.Module3\n \n baz: String\n \"\"\"\n .trimIndent(),\n )\n .toMutableMap()\n\n files.validateContents(\n \"kotlin/x/Module1.kt\" to listOf(\"package x\", \"data class Module1(\"),\n \"$MAPPER_PREFIX/com.foo.bar.Module1.properties\" to\n listOf(\"org.pkl.config.java.mapper.com.foo.bar.Module1\\\\#ModuleClass=x.Module1\"),\n // ---\n \"kotlin/z/Module2.kt\" to listOf(\"package z\", \"data class Module2(\"),\n \"$MAPPER_PREFIX/com.Module2.properties\" to\n listOf(\"org.pkl.config.java.mapper.com.Module2\\\\#ModuleClass=z.Module2\"),\n // ---\n \"kotlin/w/org/baz/Module3.kt\" to listOf(\"package w.org.baz\", \"data class Module3(\"),\n \"$MAPPER_PREFIX/org.baz.Module3.properties\" to\n listOf(\"org.pkl.config.java.mapper.org.baz.Module3\\\\#ModuleClass=w.org.baz.Module3\"),\n )\n }\n\n @Test\n fun `override names in multiple modules using each other`() {\n val files =\n KotlinCodeGeneratorOptions(\n renames =\n mapOf(\n \"org.foo\" to \"com.foo.x\",\n \"org.bar.Module2\" to \"org.bar.RenamedModule\",\n \"org.baz\" to \"com.baz.a.b\",\n )\n )\n .generateFiles(\n \"org/foo/Module1\" to\n \"\"\"\n module org.foo.Module1\n \n class Person {\n name: String\n }\n \"\"\"\n .trimIndent(),\n \"org/bar/Module2\" to\n \"\"\"\n module org.bar.Module2\n \n import \"../../org/foo/Module1.pkl\"\n\n class Group {\n owner: Module1.Person\n name: String\n }\n \"\"\"\n .trimIndent(),\n \"org/baz/Module3\" to\n \"\"\"\n module org.baz.Module3\n \n import \"../../org/bar/Module2.pkl\"\n\n class Supergroup {\n owner: Module2.Group\n }\n \"\"\"\n .trimIndent(),\n )\n\n files.validateContents(\n \"kotlin/com/foo/x/Module1.kt\" to\n listOf(\"package com.foo.x\", \"object Module1 {\", \"data class Person(\"),\n \"$MAPPER_PREFIX/org.foo.Module1.properties\" to\n listOf(\n \"org.pkl.config.java.mapper.org.foo.Module1\\\\#ModuleClass=com.foo.x.Module1\",\n \"org.pkl.config.java.mapper.org.foo.Module1\\\\#Person=com.foo.x.Module1${'$'}Person\",\n ),\n // ---\n \"kotlin/org/bar/RenamedModule.kt\" to\n listOf(\n \"package org.bar\",\n \"import com.foo.x.Module1\",\n \"object RenamedModule {\",\n \"val owner: Module1.Person\",\n ),\n \"$MAPPER_PREFIX/org.bar.Module2.properties\" to\n listOf(\n \"org.pkl.config.java.mapper.org.bar.Module2\\\\#ModuleClass=org.bar.RenamedModule\",\n \"org.pkl.config.java.mapper.org.bar.Module2\\\\#Group=org.bar.RenamedModule${'$'}Group\",\n ),\n // ---\n \"kotlin/com/baz/a/b/Module3.kt\" to\n listOf(\n \"package com.baz.a.b\",\n \"import org.bar.RenamedModule\",\n \"object Module3 {\",\n \"val owner: RenamedModule.Group\",\n ),\n \"$MAPPER_PREFIX/org.baz.Module3.properties\" to\n listOf(\n \"org.pkl.config.java.mapper.org.baz.Module3\\\\#ModuleClass=com.baz.a.b.Module3\",\n \"org.pkl.config.java.mapper.org.baz.Module3\\\\#Supergroup=com.baz.a.b.Module3${'$'}Supergroup\",\n ),\n )\n }\n\n @Test\n fun `do not capitalize names of renamed classes`() {\n val files =\n KotlinCodeGeneratorOptions(\n renames = mapOf(\"a.b.c.MyModule\" to \"x.y.z.renamed_module\", \"d.e.f.\" to \"u.v.w.\")\n )\n .generateFiles(\n \"MyModule.pkl\" to\n \"\"\"\n module a.b.c.MyModule\n \n foo: String = \"abc\"\n \"\"\"\n .trimIndent(),\n \"lower_module.pkl\" to\n \"\"\"\n module d.e.f.lower_module \n \n bar: Int = 123\n \"\"\"\n .trimIndent(),\n )\n\n files.validateContents(\n \"kotlin/x/y/z/renamed_module.kt\" to listOf(\"package x.y.z\", \"data class renamed_module(\"),\n \"$MAPPER_PREFIX/a.b.c.MyModule.properties\" to\n listOf(\"org.pkl.config.java.mapper.a.b.c.MyModule\\\\#ModuleClass=x.y.z.renamed_module\"),\n // ---\n \"kotlin/u/v/w/Lower_module.kt\" to listOf(\"package u.v.w\", \"data class Lower_module(\"),\n \"$MAPPER_PREFIX/d.e.f.lower_module.properties\" to\n listOf(\"org.pkl.config.java.mapper.d.e.f.lower_module\\\\#ModuleClass=u.v.w.Lower_module\"),\n )\n }\n\n @Test\n fun `add generated annotation`() {\n val files =\n KotlinCodeGeneratorOptions(addGeneratedAnnotation = true)\n .generateFiles(\"com.example.MyModule\" to \"foo: String\")\n assertThat(files).containsKey(\"kotlin/com/example/MyModule.kt\")\n assertThat(files[\"kotlin/com/example/MyModule.kt\"])\n .isEqualTo(\n \"\"\"\n package com.example\n\n import kotlin.String\n import org.pkl.config.java.Generated\n\n @Generated\n data class MyModule(\n val foo: String\n )\n\n \"\"\"\n .trimIndent()\n )\n }\n\n private fun Map.validateContents(\n @Suppress(\"RemoveRedundantQualifierName\") vararg assertions: kotlin.Pair>\n ) {\n val files = toMutableMap()\n\n for ((fileName, lines) in assertions) {\n assertThat(files).containsKey(fileName)\n assertThat(files.remove(fileName)).describedAs(\"Contents of $fileName\").contains(lines)\n }\n\n assertThat(files).isEmpty()\n }\n\n private fun KotlinCodeGeneratorOptions.generateFiles(\n vararg pklModules: PklModule\n ): Map {\n val pklFiles = pklModules.map { it.writeToDisk(tempDir.resolve(\"pkl/${it.name}.pkl\")) }\n val evaluator = Evaluator.preconfigured()\n return pklFiles.fold(mapOf()) { acc, pklFile ->\n val pklSchema = evaluator.evaluateSchema(ModuleSource.path(pklFile))\n val generator = KotlinCodeGenerator(pklSchema, this)\n acc + generator.output\n }\n }\n\n private fun KotlinCodeGeneratorOptions.generateFiles(\n @Suppress(\"RemoveRedundantQualifierName\") vararg pklModules: kotlin.Pair\n ): Map =\n generateFiles(*pklModules.map { (name, text) -> PklModule(name, text) }.toTypedArray())\n\n private fun generateFiles(vararg pklModules: PklModule): Map =\n KotlinCodeGeneratorOptions().generateFiles(*pklModules).mapValues { KotlinSourceCode(it.value) }\n\n private fun instantiateOtherAndPropertyTypes(): kotlin.Pair {\n val otherCtor = propertyTypesClasses.getValue(\"Other\").constructors.first()\n val other = otherCtor.call(\"pigeon\")\n\n val enumClass = propertyTypesClasses.getValue(\"Direction\").java\n val enumValue = enumClass.enumConstants.first()\n\n val propertyTypesCtor = propertyTypesClasses.getValue(\"PropertyTypes\").constructors.first()\n val propertyTypes =\n propertyTypesCtor.call(\n true,\n 42,\n 42.3,\n \"string\",\n Duration(5.0, DurationUnit.MINUTES),\n DurationUnit.MINUTES,\n DataSize(3.0, DataSizeUnit.GIGABYTES),\n DataSizeUnit.GIGABYTES,\n \"idea\",\n null,\n kotlin.Pair(1, 2),\n kotlin.Pair(\"pigeon\", other),\n listOf(1, 2),\n listOf(other, other),\n listOf(1, 2),\n listOf(other, other),\n setOf(1, 2),\n setOf(other),\n mapOf(1 to \"one\", 2 to \"two\"),\n mapOf(\"one\" to other, \"two\" to other),\n mapOf(1 to \"one\", 2 to \"two\"),\n mapOf(\"one\" to other, \"two\" to other),\n other,\n Regex(\"(i?)\\\\w*\"),\n other,\n other,\n enumValue,\n byteArrayOf(1, 2, 3, 4),\n )\n\n return other to propertyTypes\n }\n\n private fun assertThat(actual: KotlinSourceCode): KotlinSourceCodeAssert =\n KotlinSourceCodeAssert(actual)\n\n private class KotlinSourceCodeAssert(actual: KotlinSourceCode) :\n AbstractAssert(\n actual,\n KotlinSourceCodeAssert::class.java,\n ) {\n fun contains(expected: String): KotlinSourceCodeAssert {\n if (!actual.text.contains(expected)) {\n // check for equality to get better error output (IDE diff dialog)\n assertThat(actual.text).isEqualTo(expected)\n }\n return this\n }\n\n fun doesNotContain(expected: String): KotlinSourceCodeAssert {\n assertThat(actual.text).doesNotContain(expected)\n return this\n }\n\n fun compilesSuccessfully(): KotlinSourceCodeAssert {\n assertThatCode { actual.compile() }.doesNotThrowAnyException()\n return this\n }\n\n fun isEqualTo(expected: String): KotlinSourceCodeAssert {\n assertThat(actual.text).isEqualTo(expected)\n return this\n }\n\n fun isEqualToResourceFile(fileName: String): KotlinSourceCodeAssert {\n isEqualTo(IoUtils.readClassPathResourceAsString(javaClass, fileName))\n return this\n }\n }\n\n data class KotlinSourceCode(val text: String) {\n fun compile(): Map> =\n InMemoryKotlinCompiler.compile(mapOf(\"my/Mod.kt\" to text))\n\n fun deleteLines(predicate: (String) -> Boolean): KotlinSourceCode =\n KotlinSourceCode(text.lines().filterNot(predicate).joinToString(\"\\n\"))\n }\n}\n" }, { "path": "pkl-codegen-kotlin/src/test/kotlin/org/pkl/codegen/kotlin/PklModule.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.codegen.kotlin\n\nimport java.nio.file.Path\nimport kotlin.io.path.createParentDirectories\nimport org.pkl.commons.writeString\n\ndata class PklModule(val name: String, val content: String) {\n fun writeToDisk(path: Path): Path {\n return path.createParentDirectories().writeString(content)\n }\n}\n" }, { "path": "pkl-codegen-kotlin/src/test/resources/org/pkl/codegen/kotlin/Inheritance.kotlin", "content": "package my\n\nimport java.util.Objects\nimport kotlin.Any\nimport kotlin.Boolean\nimport kotlin.Int\nimport kotlin.Long\nimport kotlin.String\nimport org.pkl.core.Duration\n\nobject Mod {\n open class Foo(\n open val one: Long\n ) {\n open fun copy(one: Long = this.one): Foo = Foo(one)\n\n override fun equals(other: Any?): Boolean {\n if (this === other) return true\n if (this.javaClass != other?.javaClass) return false\n other as Foo\n if (this.one != other.one) return false\n return true\n }\n\n override fun hashCode(): Int {\n var result = 1\n result = 31 * result + Objects.hashCode(this.one)\n return result\n }\n\n override fun toString(): String = \"\"\"Foo(one=$one)\"\"\"\n }\n\n open class None(\n one: Long\n ) : Foo(one) {\n open override fun copy(one: Long): None = None(one)\n\n override fun equals(other: Any?): Boolean {\n if (this === other) return true\n if (this.javaClass != other?.javaClass) return false\n other as None\n if (this.one != other.one) return false\n return true\n }\n\n override fun hashCode(): Int {\n var result = 1\n result = 31 * result + Objects.hashCode(this.one)\n return result\n }\n\n override fun toString(): String = \"\"\"None(one=$one)\"\"\"\n }\n\n open class Bar(\n one: Long,\n open val two: String\n ) : None(one) {\n open fun copy(one: Long = this.one, two: String = this.two): Bar = Bar(one, two)\n\n open override fun copy(one: Long): Bar = Bar(one, two)\n\n override fun equals(other: Any?): Boolean {\n if (this === other) return true\n if (this.javaClass != other?.javaClass) return false\n other as Bar\n if (this.one != other.one) return false\n if (this.two != other.two) return false\n return true\n }\n\n override fun hashCode(): Int {\n var result = 1\n result = 31 * result + Objects.hashCode(this.one)\n result = 31 * result + Objects.hashCode(this.two)\n return result\n }\n\n override fun toString(): String = \"\"\"Bar(one=$one, two=$two)\"\"\"\n }\n\n class Baz(\n one: Long,\n two: String,\n val three: Duration\n ) : Bar(one, two) {\n fun copy(\n one: Long = this.one,\n two: String = this.two,\n three: Duration = this.three\n ): Baz = Baz(one, two, three)\n\n override fun copy(one: Long, two: String): Baz = Baz(one, two, three)\n\n override fun copy(one: Long): Baz = Baz(one, two, three)\n\n override fun equals(other: Any?): Boolean {\n if (this === other) return true\n if (this.javaClass != other?.javaClass) return false\n other as Baz\n if (this.one != other.one) return false\n if (this.two != other.two) return false\n if (this.three != other.three) return false\n return true\n }\n\n override fun hashCode(): Int {\n var result = 1\n result = 31 * result + Objects.hashCode(this.one)\n result = 31 * result + Objects.hashCode(this.two)\n result = 31 * result + Objects.hashCode(this.three)\n return result\n }\n\n override fun toString(): String = \"\"\"Baz(one=$one, two=$two, three=$three)\"\"\"\n }\n}\n" }, { "path": "pkl-codegen-kotlin/src/test/resources/org/pkl/codegen/kotlin/Kdoc.kotlin", "content": "package my\n\nimport java.util.Objects\nimport kotlin.Any\nimport kotlin.Boolean\nimport kotlin.Int\nimport kotlin.String\n\n/**\n * type alias comment.\n * *emphasized* `code`.\n */\ntypealias Email = String\n\n/**\n * module comment.\n * *emphasized* `code`.\n */\ndata class Mod(\n /**\n * module property comment.\n * *emphasized* `code`.\n */\n val pigeon: Person\n) {\n /**\n * class comment.\n * *emphasized* `code`.\n */\n open class Product(\n /**\n * class property comment.\n * *emphasized* `code`.\n */\n open val price: String\n ) {\n open fun copy(price: String = this.price): Product = Product(price)\n\n override fun equals(other: Any?): Boolean {\n if (this === other) return true\n if (this.javaClass != other?.javaClass) return false\n other as Product\n if (this.price != other.price) return false\n return true\n }\n\n override fun hashCode(): Int {\n var result = 1\n result = 31 * result + Objects.hashCode(this.price)\n return result\n }\n\n override fun toString(): String = \"\"\"Product(price=$price)\"\"\"\n }\n\n /**\n * class comment.\n * *emphasized* `code`.\n */\n data class Person(\n /**\n * class property comment.\n * *emphasized* `code`.\n */\n val name: String\n )\n}\n" }, { "path": "pkl-codegen-kotlin/src/test/resources/org/pkl/codegen/kotlin/PropertyTypes.kotlin", "content": "package my\n\nimport java.util.Arrays\nimport java.util.Objects\nimport kotlin.Any\nimport kotlin.Boolean\nimport kotlin.ByteArray\nimport kotlin.Double\nimport kotlin.Int\nimport kotlin.Long\nimport kotlin.Pair\nimport kotlin.String\nimport kotlin.collections.Collection\nimport kotlin.collections.List\nimport kotlin.collections.Map\nimport kotlin.collections.Set\nimport kotlin.text.Regex\nimport org.pkl.core.DataSize\nimport org.pkl.core.DataSizeUnit\nimport org.pkl.core.Duration\nimport org.pkl.core.DurationUnit\n\nobject Mod {\n open class PropertyTypes(\n open val boolean: Boolean,\n open val int: Long,\n open val float: Double,\n open val string: String,\n open val duration: Duration,\n open val durationUnit: DurationUnit,\n open val dataSize: DataSize,\n open val dataSizeUnit: DataSizeUnit,\n open val nullable: String?,\n open val nullable2: String?,\n open val pair: Pair,\n open val pair2: Pair,\n open val coll: Collection,\n open val coll2: Collection,\n open val list: List,\n open val list2: List,\n open val set: Set,\n open val set2: Set,\n open val map: Map,\n open val map2: Map,\n open val container: Map,\n open val container2: Map,\n open val other: Other,\n open val regex: Regex,\n open val any: Any?,\n open val nonNull: Any,\n open val enum: Direction,\n open val bytes: ByteArray\n ) {\n open fun copy(\n boolean: Boolean = this.boolean,\n int: Long = this.int,\n float: Double = this.float,\n string: String = this.string,\n duration: Duration = this.duration,\n durationUnit: DurationUnit = this.durationUnit,\n dataSize: DataSize = this.dataSize,\n dataSizeUnit: DataSizeUnit = this.dataSizeUnit,\n nullable: String? = this.nullable,\n nullable2: String? = this.nullable2,\n pair: Pair = this.pair,\n pair2: Pair = this.pair2,\n coll: Collection = this.coll,\n coll2: Collection = this.coll2,\n list: List = this.list,\n list2: List = this.list2,\n set: Set = this.set,\n set2: Set = this.set2,\n map: Map = this.map,\n map2: Map = this.map2,\n container: Map = this.container,\n container2: Map = this.container2,\n other: Other = this.other,\n regex: Regex = this.regex,\n any: Any? = this.any,\n nonNull: Any = this.nonNull,\n enum: Direction = this.enum,\n bytes: ByteArray = this.bytes\n ): PropertyTypes = PropertyTypes(boolean, int, float, string, duration, durationUnit, dataSize,\n dataSizeUnit, nullable, nullable2, pair, pair2, coll, coll2, list, list2, set, set2, map,\n map2, container, container2, other, regex, any, nonNull, enum, bytes)\n\n override fun equals(other: Any?): Boolean {\n if (this === other) return true\n if (this.javaClass != other?.javaClass) return false\n other as PropertyTypes\n if (this.boolean != other.boolean) return false\n if (this.int != other.int) return false\n if (this.float != other.float) return false\n if (this.string != other.string) return false\n if (this.duration != other.duration) return false\n if (this.durationUnit != other.durationUnit) return false\n if (this.dataSize != other.dataSize) return false\n if (this.dataSizeUnit != other.dataSizeUnit) return false\n if (this.nullable != other.nullable) return false\n if (this.nullable2 != other.nullable2) return false\n if (this.pair != other.pair) return false\n if (this.pair2 != other.pair2) return false\n if (this.coll != other.coll) return false\n if (this.coll2 != other.coll2) return false\n if (this.list != other.list) return false\n if (this.list2 != other.list2) return false\n if (this.set != other.set) return false\n if (this.set2 != other.set2) return false\n if (this.map != other.map) return false\n if (this.map2 != other.map2) return false\n if (this.container != other.container) return false\n if (this.container2 != other.container2) return false\n if (this.other != other.other) return false\n if (this.regex.pattern != other.regex.pattern) return false\n if (this.any != other.any) return false\n if (this.nonNull != other.nonNull) return false\n if (this.enum != other.enum) return false\n if (!this.bytes.contentEquals(other.bytes)) return false\n return true\n }\n\n override fun hashCode(): Int {\n var result = 1\n result = 31 * result + Objects.hashCode(this.boolean)\n result = 31 * result + Objects.hashCode(this.int)\n result = 31 * result + Objects.hashCode(this.float)\n result = 31 * result + Objects.hashCode(this.string)\n result = 31 * result + Objects.hashCode(this.duration)\n result = 31 * result + Objects.hashCode(this.durationUnit)\n result = 31 * result + Objects.hashCode(this.dataSize)\n result = 31 * result + Objects.hashCode(this.dataSizeUnit)\n result = 31 * result + Objects.hashCode(this.nullable)\n result = 31 * result + Objects.hashCode(this.nullable2)\n result = 31 * result + Objects.hashCode(this.pair)\n result = 31 * result + Objects.hashCode(this.pair2)\n result = 31 * result + Objects.hashCode(this.coll)\n result = 31 * result + Objects.hashCode(this.coll2)\n result = 31 * result + Objects.hashCode(this.list)\n result = 31 * result + Objects.hashCode(this.list2)\n result = 31 * result + Objects.hashCode(this.set)\n result = 31 * result + Objects.hashCode(this.set2)\n result = 31 * result + Objects.hashCode(this.map)\n result = 31 * result + Objects.hashCode(this.map2)\n result = 31 * result + Objects.hashCode(this.container)\n result = 31 * result + Objects.hashCode(this.container2)\n result = 31 * result + Objects.hashCode(this.other)\n result = 31 * result + Objects.hashCode(this.regex.pattern)\n result = 31 * result + Objects.hashCode(this.any)\n result = 31 * result + Objects.hashCode(this.nonNull)\n result = 31 * result + Objects.hashCode(this.enum)\n result = 31 * result + this.bytes.contentHashCode()\n return result\n }\n\n override fun toString(): String =\n \"\"\"PropertyTypes(boolean=$boolean, int=$int, float=$float, string=$string, duration=$duration, durationUnit=$durationUnit, dataSize=$dataSize, dataSizeUnit=$dataSizeUnit, nullable=$nullable, nullable2=$nullable2, pair=$pair, pair2=$pair2, coll=$coll, coll2=$coll2, list=$list, list2=$list2, set=$set, set2=$set2, map=$map, map2=$map2, container=$container, container2=$container2, other=$other, regex=$regex, any=$any, nonNull=$nonNull, enum=$enum, bytes=${Arrays.toString(bytes)})\"\"\"\n }\n\n open class Other(\n open val name: String\n ) {\n open fun copy(name: String = this.name): Other = Other(name)\n\n override fun equals(other: Any?): Boolean {\n if (this === other) return true\n if (this.javaClass != other?.javaClass) return false\n other as Other\n if (this.name != other.name) return false\n return true\n }\n\n override fun hashCode(): Int {\n var result = 1\n result = 31 * result + Objects.hashCode(this.name)\n return result\n }\n\n override fun toString(): String = \"\"\"Other(name=$name)\"\"\"\n }\n\n enum class Direction(\n val value: String\n ) {\n NORTH(\"north\"),\n\n EAST(\"east\"),\n\n SOUTH(\"south\"),\n\n WEST(\"west\");\n\n override fun toString() = value\n }\n}\n" }, { "path": "pkl-commons/gradle.lockfile", "content": "# This is a Gradle generated file for dependency locking.\n# Manual edits can break the build and are not advised.\n# This file is expected to be part of source control.\ncom.github.ben-manes.caffeine:caffeine:2.9.3=swiftExportClasspathResolvable\ncom.google.errorprone:error_prone_annotations:2.28.0=swiftExportClasspathResolvable\nio.github.java-diff-utils:java-diff-utils:4.12=kotlinInternalAbiValidation\nio.opentelemetry:opentelemetry-api:1.41.0=swiftExportClasspathResolvable\nio.opentelemetry:opentelemetry-context:1.41.0=swiftExportClasspathResolvable\nnet.bytebuddy:byte-buddy:1.17.7=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.apiguardian:apiguardian-api:1.1.2=testCompileClasspath,testImplementationDependenciesMetadata\norg.assertj:assertj-core:3.27.6=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.bouncycastle:bcpg-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcpkix-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcprov-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcutil-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.checkerframework:checker-qual:3.43.0=swiftExportClasspathResolvable\norg.jetbrains.kotlin:abi-tools-api:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:abi-tools:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-build-tools-api:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-build-tools-impl:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-compiler-runner:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-client:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-klib-commonizer-embeddable:2.2.20=kotlinKlibCommonizerClasspath\norg.jetbrains.kotlin:kotlin-metadata-jvm:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-native-prebuilt:2.0.21=kotlinNativeBundleConfiguration\norg.jetbrains.kotlin:kotlin-reflect:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-script-runtime:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-scripting-common:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-compiler-impl-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-jvm:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-stdlib-jdk7:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib-jdk8:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,runtimeClasspath,swiftExportClasspathResolvable,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:swift-export-embeddable:2.2.20=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.8.0=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-bom:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core-jvm:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3=swiftExportClasspathResolvable\norg.jetbrains:annotations:13.0=compileClasspath,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,runtimeClasspath,swiftExportClasspathResolvable,testCompileClasspath,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-api:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-engine:5.14.0=testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-params:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-commons:1.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-engine:1.14.0=testRuntimeClasspath\norg.junit.platform:junit-platform-launcher:1.14.0=testRuntimeClasspath\norg.junit:junit-bom:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.opentest4j:opentest4j:1.3.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\nempty=annotationProcessor,compileOnlyDependenciesMetadata,intransitiveDependenciesMetadata,kotlinCompilerPluginClasspath,kotlinNativeCompilerPluginClasspath,kotlinScriptDefExtensions,signatures,sourcesJar,testAnnotationProcessor,testApiDependenciesMetadata,testCompileOnlyDependenciesMetadata,testIntransitiveDependenciesMetadata,testKotlinScriptDefExtensions\n" }, { "path": "pkl-commons/pkl-commons.gradle.kts", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nplugins {\n pklAllProjects\n pklKotlinLibrary\n pklPublishLibrary\n}\n\npublishing {\n publications {\n named(\"library\") {\n pom {\n url.set(\"https://github.com/apple/pkl/tree/main/pkl-commons\")\n description.set(\"Internal utilities. NOT A PUBLIC API.\")\n }\n }\n }\n}\n" }, { "path": "pkl-commons/src/main/kotlin/org/pkl/commons/Control.kt", "content": "/*\n * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons\n\nimport java.util.WeakHashMap\nimport kotlin.reflect.KProperty\n\n// Adapted from https://stackoverflow.com/a/38084930\nfun lazyWithReceiver(\n initializer: This.() -> Return\n): LazyWithReceiver = LazyWithReceiver(initializer)\n\nclass LazyWithReceiver(val initializer: This.() -> Return) {\n private val values = WeakHashMap()\n\n private val lock = Object()\n\n operator fun getValue(thisValue: This, property: KProperty<*>): Return =\n synchronized(lock) { values.getOrPut(thisValue) { thisValue.initializer() } }\n}\n" }, { "path": "pkl-commons/src/main/kotlin/org/pkl/commons/NameMapper.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons\n\n/**\n * A helper class for translating names of Pkl modules to different names of classes and/or objects\n * in the target language of a code generation execution.\n *\n * The `mapping` parameter is expected to contain valid prefixes of Pkl module names, with an\n * optional dot at the end, and values should be valid class names in the language for which code\n * generation is performed.\n *\n * If the rename patterns do not explicitly rename the class, the class name is capitalized.\n *\n * When computing the appropriate target name, the longest matching prefix is used.\n *\n * Prefix replacements are literal, and therefore dots are important. When renaming packages, in\n * most cases, you must ensure that you have an ending dot on both sides of a mapping (except for\n * the empty mapping, if you use it), otherwise you may get unexpected results:\n * ```kotlin\n * val mapper = NameMapper(\n * mapOf(\n * \"com.foo.\" to \"x\", // Dot on the left only\n * \"org.bar\" to \"y.\", // Dot on the right only\n * \"net.baz\" to \"z\" // No dots\n * )\n * )\n *\n * assertThat(mapper.map(\"com.foo.bar\")).isEqualTo(\"\" to \"xbar\") // Target prefix merged into the suffix\n * assertThat(mapper.map(\"org.bar.baz\")).isEqualTo(\"y.\" to \"Baz\") // Double dot, invalid package name\n * assertThat(mapper.map(\"net.baz.qux\")).isEqualTo(\"z\" to \"Qux\") // Looks okay, but...\n * assertThat(mapper.map(\"net.bazqux\")).isEqualTo(\"\" to \"zqux\") // ...may cut the package name in the middle.\n * ```\n */\nclass NameMapper(mapping: Map) {\n private val sortedMapping = mapping.toList().sortedBy { -it.first.length }\n\n private fun doMap(sourceName: String): Pair {\n for ((sourcePrefix, targetPrefix) in sortedMapping) {\n if (sourceName.startsWith(sourcePrefix)) {\n val rest = sourceName.substring(sourcePrefix.length)\n val mapped = targetPrefix + rest\n val wasClassRenamed =\n !targetPrefix.endsWith('.') && (sourcePrefix.length - 1) >= sourceName.lastIndexOf('.')\n return mapped to wasClassRenamed\n }\n }\n return sourceName to false\n }\n\n fun map(sourceName: String): Pair {\n val (mappedName, wasClassRenamed) = doMap(sourceName)\n val packageName = mappedName.substringBeforeLast(\".\", \"\")\n val mappedClassName = mappedName.substringAfterLast(\".\")\n val className =\n if (wasClassRenamed) mappedClassName\n else mappedClassName.replaceFirstChar { it.titlecaseChar() }\n return packageName to className\n }\n}\n" }, { "path": "pkl-commons/src/main/kotlin/org/pkl/commons/Paths.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons\n\nimport java.io.*\nimport java.nio.charset.Charset\nimport java.nio.file.*\nimport java.nio.file.attribute.FileAttribute\nimport java.util.stream.Stream\nimport kotlin.io.path.copyTo\nimport kotlin.io.path.createParentDirectories\nimport kotlin.io.path.exists\n\n// not stored to avoid build-time initialization by native-image\nval currentWorkingDir: Path\n get() = System.getProperty(\"user.dir\").toPath()\n\n// unlike `Path.resolve`, this works across file systems if `other` is absolute\nfun Path.resolveSafely(other: Path): Path = if (other.isAbsolute) other else resolve(other)\n\n@Throws(IOException::class)\nfun Path.walk(maxDepth: Int = Int.MAX_VALUE, vararg options: FileVisitOption): Stream =\n Files.walk(this, maxDepth, *options)\n\n@Throws(IOException::class)\nfun Path.createTempFile(\n prefix: String? = null,\n suffix: String? = null,\n vararg attributes: FileAttribute<*>,\n): Path = Files.createTempFile(this, prefix, suffix, *attributes)\n\n/** [Files.writeString] seems more efficient than [kotlin.io.path.writeText]. */\n@Throws(IOException::class)\nfun Path.writeString(\n text: String,\n charset: Charset = Charsets.UTF_8,\n vararg options: OpenOption,\n): Path = Files.writeString(this, text, charset, *options)\n\n/** [Files.readString] seems more efficient than [kotlin.io.path.readText]. */\n@Throws(IOException::class)\nfun Path.readString(charset: Charset = Charsets.UTF_8): String = Files.readString(this, charset)\n\n@Throws(IOException::class)\nfun Path.copyRecursively(target: Path) {\n if (exists()) {\n target.createParentDirectories()\n walk().use { paths ->\n paths.forEach { src ->\n val dst = target.resolve(this@copyRecursively.relativize(src))\n src.copyTo(dst, overwrite = true)\n }\n }\n }\n}\n\nprivate val isWindows by lazy { System.getProperty(\"os.name\").contains(\"Windows\") }\n\n/** Copy implementation from IoUtils.toNormalizedPathString */\nfun Path.toNormalizedPathString(): String {\n if (isWindows) {\n return toString().replace(\"\\\\\", \"/\")\n }\n return toString()\n}\n" }, { "path": "pkl-commons/src/main/kotlin/org/pkl/commons/Strings.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons\n\nimport java.io.File\nimport java.net.URI\nimport java.nio.file.Path\nimport java.util.regex.Pattern\n\nfun String.toPath(): Path = Path.of(this)\n\nprivate val uriLike = Pattern.compile(\"\\\\w+:[^\\\\\\\\].*\")\n\nprivate val windowsPathLike = Pattern.compile(\"\\\\w:\\\\\\\\.*\")\n\n/** Copy of org.pkl.core.util.IoUtils.toUri */\nfun String.toUri(): URI {\n if (uriLike.matcher(this).matches()) {\n return URI(this)\n }\n if (windowsPathLike.matcher(this).matches()) {\n return File(this).toURI()\n }\n return URI(null, null, this, null)\n}\n\n/** Lex a string into tokens similar to how a shell would */\nfun shlex(input: String): List {\n val result = mutableListOf()\n var inEscape = false\n var quote: Char? = null\n var lastCloseQuoteIndex = Int.MIN_VALUE\n val current = StringBuilder()\n\n for ((idx, char) in input.withIndex()) {\n when {\n // if in an escape always append the next character\n inEscape -> {\n inEscape = false\n current.append(char)\n }\n // enter an escape on \\ if not in a quote or in a non-single quote\n char == '\\\\' && quote != '\\'' -> inEscape = true\n // if in a quote and encounter the delimiter, tentatively exit the quote\n // this handles cases with adjoining quotes e.g. `abc'123''xyz'`\n quote == char -> {\n quote = null\n lastCloseQuoteIndex = idx\n }\n // if not in a quote and encounter a quote character, enter a quote\n quote == null && (char == '\\'' || char == '\"') -> {\n quote = char\n }\n // if not in a quote and whitespace is encountered\n quote == null && char.isWhitespace() -> {\n // if the current token isn't empty or if a quote has just ended, finalize the current token\n // otherwise do nothing, which handles multiple whitespace cases e.g. `abc 123`\n if (current.isNotEmpty() || lastCloseQuoteIndex == (idx - 1)) {\n result.add(current.toString())\n current.clear()\n }\n }\n // in other cases, append to the current token\n else -> current.append(char)\n }\n }\n // clean up last token\n // if the current token isn't empty or if a quote has just ended, finalize the token\n // if this condition is false, the input likely ended in whitespace\n if (current.isNotEmpty() || lastCloseQuoteIndex == (input.length - 1)) {\n result.add(current.toString())\n }\n\n return result\n}\n" }, { "path": "pkl-commons/src/main/kotlin/org/pkl/commons/Throwables.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons\n\nimport java.io.PrintWriter\nimport java.io.StringWriter\n\n/** Same as [Throwable.printStackTrace] except that it prints to a [String]. */\nfun Throwable.printStackTraceToString(): String =\n StringWriter().also { printStackTrace(PrintWriter(it)) }.toString()\n" }, { "path": "pkl-commons/src/main/kotlin/org/pkl/commons/Uris.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons\n\nimport java.net.URI\nimport java.nio.file.Path\n\nfun URI.toPath(): Path = Path.of(this)\n" }, { "path": "pkl-commons/src/test/kotlin/org/pkl/commons/NameMapperTest.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons\n\nimport org.assertj.core.api.Assertions.assertThat\nimport org.junit.jupiter.api.Test\n\nclass NameMapperTest {\n @Test\n fun `empty prefixes everything`() {\n val mapper = NameMapper(mapOf(\"\" to \"bar.\"))\n assertThat(mapper.map(\"foo.bar.Baz\")).isEqualTo(\"bar.foo.bar\" to \"Baz\")\n assertThat(mapper.map(\"Baz\")).isEqualTo(\"bar\" to \"Baz\")\n }\n\n @Test\n fun `longest prefix wins`() {\n val mapper = NameMapper(mapOf(\"bar.\" to \"com.bar.\", \"bar.baz.\" to \"foo.bar.\"))\n assertThat(mapper.map(\"bar.baz.Buzzy\")).isEqualTo(\"foo.bar\" to \"Buzzy\")\n }\n\n @Test\n fun `implicit uppercase classname`() {\n val mapper = NameMapper(mapOf(\"foo.\" to \"bar.\"))\n assertThat(mapper.map(\"foo.bar.baz\")).isEqualTo(\"bar.bar\" to \"Baz\")\n assertThat(mapper.map(\"foo.bar\")).isEqualTo(\"bar\" to \"Bar\")\n assertThat(mapper.map(\"baz\")).isEqualTo(\"\" to \"Baz\")\n assertThat(mapper.map(\"baz\")).isEqualTo(\"\" to \"Baz\")\n }\n\n @Test\n fun `no implicit uppercased classname if explicitly renamed`() {\n val mapper = NameMapper(mapOf(\"foo.bar\" to \"bar.bar\", \"foo.c\" to \"foo.z\", \"com.foo.\" to \"x\"))\n assertThat(mapper.map(\"foo.bar\")).isEqualTo(\"bar\" to \"bar\")\n assertThat(mapper.map(\"foo.bar\")).isEqualTo(\"bar\" to \"bar\")\n assertThat(mapper.map(\"foo.cow\")).isEqualTo(\"foo\" to \"zow\")\n assertThat(mapper.map(\"com.foo.bar\")).isEqualTo(\"\" to \"xbar\")\n }\n}\n" }, { "path": "pkl-commons/src/test/kotlin/org/pkl/commons/ShlexTest.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons\n\nimport org.assertj.core.api.Assertions.assertThat\nimport org.junit.jupiter.api.Test\n\nclass ShlexTest {\n\n @Test\n fun `empty input produces empty output`() {\n assertThat(shlex(\"\")).isEqualTo(emptyList())\n }\n\n @Test\n fun `whitespace input produces empty output`() {\n assertThat(shlex(\" \\n \\t \")).isEqualTo(emptyList())\n }\n\n @Test\n fun `regular token parsing`() {\n assertThat(shlex(\"\\nabc def\\tghi \")).isEqualTo(listOf(\"abc\", \"def\", \"ghi\"))\n }\n\n @Test\n fun `single quoted token parsing`() {\n assertThat(shlex(\"'this is a single token'\")).isEqualTo(listOf(\"this is a single token\"))\n }\n\n @Test\n fun `double quoted token parsing`() {\n assertThat(shlex(\"\\\"this is a single token\\\"\")).isEqualTo(listOf(\"this is a single token\"))\n }\n\n @Test\n fun `escaping handles double quotes`() {\n assertThat(shlex(\"\"\"\"\\\"this is a single double quoted token\\\"\"\"\"\"))\n .isEqualTo(listOf(\"\\\"this is a single double quoted token\\\"\"))\n }\n\n @Test\n fun `escaping does not apply within single quotes`() {\n assertThat(shlex(\"\"\"'this is a single \\\" token'\"\"\"))\n .isEqualTo(listOf(\"\"\"this is a single \\\" token\"\"\"))\n }\n\n @Test\n fun `adjacent quoted strings are one token`() {\n assertThat(shlex(\"\"\"\"single\"' joined 'token\"\"\")).isEqualTo(listOf(\"single joined token\"))\n assertThat(shlex(\"\"\"\"single\"' 'token\"\"\")).isEqualTo(listOf(\"single token\"))\n }\n\n @Test\n fun `space escapes do not split tokens`() {\n assertThat(shlex(\"\"\"single\\ token\"\"\")).isEqualTo(listOf(\"single token\"))\n }\n\n @Test\n fun `empty quotes produce a single empty token`() {\n assertThat(shlex(\"\\\"\\\"\")).isEqualTo(listOf(\"\"))\n assertThat(shlex(\"''\")).isEqualTo(listOf(\"\"))\n assertThat(shlex(\"'' ''\")).isEqualTo(listOf(\"\", \"\"))\n assertThat(shlex(\"''''\")).isEqualTo(listOf(\"\"))\n }\n}\n" }, { "path": "pkl-commons-cli/gradle.lockfile", "content": "# This is a Gradle generated file for dependency locking.\n# Manual edits can break the build and are not advised.\n# This file is expected to be part of source control.\ncom.github.ajalt.clikt:clikt-core-jvm:5.0.3=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-core:5.0.3=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-jvm:5.0.3=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-markdown-jvm:5.0.3=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt-markdown:5.0.3=compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.clikt:clikt:5.0.3=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.colormath:colormath-jvm:3.6.0=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.colormath:colormath:3.6.0=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-core-jvm:3.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-core:3.0.1=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-ffm-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-ffm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-graal-ffi-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-graal-ffi:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-jna-jvm:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm-jna:3.0.1=runtimeClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-jvm:3.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-markdown-jvm:3.0.1=compileClasspath,runtimeClasspath,testCompileClasspath,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant-markdown:3.0.1=compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ajalt.mordant:mordant:3.0.1=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\ncom.github.ben-manes.caffeine:caffeine:2.9.3=swiftExportClasspathResolvable\ncom.google.errorprone:error_prone_annotations:2.28.0=swiftExportClasspathResolvable\nio.github.java-diff-utils:java-diff-utils:4.12=kotlinInternalAbiValidation\nio.opentelemetry:opentelemetry-api:1.41.0=swiftExportClasspathResolvable\nio.opentelemetry:opentelemetry-context:1.41.0=swiftExportClasspathResolvable\nnet.bytebuddy:byte-buddy:1.17.7=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\nnet.java.dev.jna:jna:5.14.0=runtimeClasspath,testRuntimeClasspath\norg.apiguardian:apiguardian-api:1.1.2=testCompileClasspath,testImplementationDependenciesMetadata\norg.assertj:assertj-core:3.27.6=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.bouncycastle:bcpg-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcpkix-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcprov-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.bouncycastle:bcutil-jdk18on:1.80=kotlinBouncyCastleConfiguration\norg.checkerframework:checker-qual:3.43.0=swiftExportClasspathResolvable\norg.graalvm.compiler:compiler:25.0.0=svmClasspath\norg.graalvm.espresso:espresso-svm:25.0.0=svmClasspath\norg.graalvm.nativeimage:native-image-base:25.0.0=svmClasspath\norg.graalvm.nativeimage:objectfile:25.0.0=svmClasspath\norg.graalvm.nativeimage:pointsto:25.0.0=svmClasspath\norg.graalvm.nativeimage:svm-capnproto-runtime:25.0.0=svmClasspath\norg.graalvm.nativeimage:svm-configure:25.0.0=svmClasspath\norg.graalvm.nativeimage:svm:25.0.0=svmClasspath\norg.graalvm.nativeimage:truffle-runtime-svm:25.0.0=svmClasspath\norg.graalvm.polyglot:polyglot:25.0.0=runtimeClasspath,svmClasspath,testRuntimeClasspath\norg.graalvm.sdk:collections:25.0.0=runtimeClasspath,svmClasspath,testRuntimeClasspath\norg.graalvm.sdk:graal-sdk:25.0.0=runtimeClasspath,svmClasspath,testRuntimeClasspath\norg.graalvm.sdk:jniutils:25.0.0=svmClasspath\norg.graalvm.sdk:nativeimage-libgraal:25.0.0=svmClasspath\norg.graalvm.sdk:nativeimage:25.0.0=runtimeClasspath,svmClasspath,testRuntimeClasspath\norg.graalvm.sdk:word:25.0.0=runtimeClasspath,svmClasspath,testRuntimeClasspath\norg.graalvm.truffle:truffle-api:25.0.0=runtimeClasspath,svmClasspath,testRuntimeClasspath\norg.graalvm.truffle:truffle-compiler:25.0.0=svmClasspath\norg.graalvm.truffle:truffle-runtime:25.0.0=svmClasspath\norg.jetbrains.kotlin:abi-tools-api:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:abi-tools:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-build-tools-api:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-build-tools-impl:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-compiler-runner:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-client:2.2.20=kotlinBuildToolsApiClasspath\norg.jetbrains.kotlin:kotlin-daemon-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-klib-commonizer-embeddable:2.2.20=kotlinKlibCommonizerClasspath\norg.jetbrains.kotlin:kotlin-metadata-jvm:2.2.20=kotlinInternalAbiValidation\norg.jetbrains.kotlin:kotlin-native-prebuilt:2.0.21=kotlinNativeBundleConfiguration\norg.jetbrains.kotlin:kotlin-reflect:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-script-runtime:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathSvm,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlin:kotlin-scripting-common:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathSvm,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathSvm,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-compiler-impl-embeddable:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathSvm,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-scripting-jvm:2.2.20=kotlinBuildToolsApiClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathSvm,kotlinCompilerPluginClasspathTest\norg.jetbrains.kotlin:kotlin-stdlib-jdk7:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib-jdk8:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,runtimeClasspath,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:kotlin-stdlib:2.2.20=apiDependenciesMetadata,compileClasspath,implementationDependenciesMetadata,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathSvm,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,runtimeClasspath,swiftExportClasspathResolvable,testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.jetbrains.kotlin:swift-export-embeddable:2.2.20=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.8.0=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-bom:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core-jvm:1.7.3=swiftExportClasspathResolvable\norg.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3=swiftExportClasspathResolvable\norg.jetbrains:annotations:13.0=compileClasspath,kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinCompilerPluginClasspathMain,kotlinCompilerPluginClasspathSvm,kotlinCompilerPluginClasspathTest,kotlinInternalAbiValidation,kotlinKlibCommonizerClasspath,runtimeClasspath,swiftExportClasspathResolvable,testCompileClasspath,testRuntimeClasspath\norg.jetbrains:markdown-jvm:0.7.3=runtimeClasspath,testRuntimeClasspath\norg.jetbrains:markdown:0.7.3=implementationDependenciesMetadata,runtimeClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-api:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-engine:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.jupiter:junit-jupiter-params:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-commons:1.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-engine:1.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.junit.platform:junit-platform-launcher:1.14.0=testRuntimeClasspath\norg.junit:junit-bom:5.14.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.msgpack:msgpack-core:0.9.8=runtimeClasspath,svmClasspath,testRuntimeClasspath\norg.opentest4j:opentest4j:1.3.0=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath\norg.organicdesign:Paguro:3.10.3=runtimeClasspath,svmClasspath,testRuntimeClasspath\norg.snakeyaml:snakeyaml-engine:2.10=runtimeClasspath,svmClasspath,testRuntimeClasspath\nempty=annotationProcessor,compileOnlyDependenciesMetadata,intransitiveDependenciesMetadata,kotlinCompilerPluginClasspath,kotlinNativeCompilerPluginClasspath,kotlinScriptDefExtensions,signatures,sourcesJar,svmAnnotationProcessor,svmApiDependenciesMetadata,svmCompileClasspath,svmCompileOnlyDependenciesMetadata,svmImplementationDependenciesMetadata,svmIntransitiveDependenciesMetadata,svmKotlinScriptDefExtensions,svmRuntimeClasspath,testAnnotationProcessor,testApiDependenciesMetadata,testCompileOnlyDependenciesMetadata,testIntransitiveDependenciesMetadata,testKotlinScriptDefExtensions\n" }, { "path": "pkl-commons-cli/pkl-commons-cli.gradle.kts", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\nplugins {\n pklAllProjects\n pklKotlinLibrary\n pklPublishLibrary\n}\n\nval svmClasspath: Configuration by configurations.creating\n\n// used by pklNativeExecutable.gradle.kts\n@Suppress(\"unused\") val svm: SourceSet by sourceSets.creating { compileClasspath = svmClasspath }\n\ndependencies {\n api(projects.pklCore)\n api(libs.clikt)\n implementation(libs.cliktMarkdown)\n\n implementation(projects.pklCommons)\n testImplementation(projects.pklCommonsTest)\n\n svmClasspath(libs.svm)\n svmClasspath(libs.truffleSvm)\n svmClasspath(projects.pklCore)\n}\n\npublishing {\n publications {\n named(\"library\") {\n pom {\n url.set(\"https://github.com/apple/pkl/tree/main/pkl-commons-cli\")\n description.set(\"Internal CLI utilities. NOT A PUBLIC API.\")\n }\n }\n }\n}\n" }, { "path": "pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/CliBaseOptions.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons.cli\n\nimport java.net.URI\nimport java.nio.file.Files\nimport java.nio.file.Path\nimport java.time.Duration\nimport java.util.regex.Pattern\nimport org.pkl.core.evaluatorSettings.Color\nimport org.pkl.core.evaluatorSettings.PklEvaluatorSettings.ExternalReader\nimport org.pkl.core.evaluatorSettings.TraceMode\nimport org.pkl.core.module.ProjectDependenciesManager\nimport org.pkl.core.util.IoUtils\n\n/** Base options shared between CLI commands. */\ndata class CliBaseOptions(\n /** The source modules to evaluate. Relative URIs are resolved against [workingDir]. */\n val sourceModules: List = listOf(),\n\n /**\n * The URI patterns that determine which modules can be loaded and evaluated. Patterns are matched\n * against the beginning of module URIs. At least one pattern needs to match for a module to be\n * loadable. Both [sourceModules] and module imports are subject to this check.\n */\n val allowedModules: List? = null,\n\n /**\n * The URI patterns that determine which external resources can be read. Patterns are matched\n * against the beginning of resource URIs. At least one pattern needs to match for a resource to\n * be readable.\n */\n val allowedResources: List? = null,\n\n /**\n * The environment variables to set. Pkl code can read environment variables with\n * `read(\"env:\")`.\n */\n val environmentVariables: Map? = null,\n\n /**\n * The external properties to set. Pkl code can read external properties with\n * `read(\"prop:\")`.\n */\n val externalProperties: Map? = null,\n\n /**\n * The directories, ZIP archives, or JAR archives to search when resolving `modulepath:` URIs.\n * Relative paths are resolved against [workingDir].\n */\n private val modulePath: List? = null,\n\n /**\n * The base path that relative module paths passed as command-line arguments are resolved against.\n */\n private val workingDir: Path = IoUtils.getCurrentWorkingDir(),\n\n /**\n * The root directory for `file:` modules and resources. If non-null, access to file-based modules\n * and resources is restricted to those located under [rootDir]. Any symlinks are resolved before\n * this check is performed.\n */\n private val rootDir: Path? = null,\n\n /**\n * The Pkl settings file to use. A settings file is a Pkl module amending the `pkl.settings`\n * standard library module. If `null`, `~/.pkl/settings.pkl` (if present) or the defaults\n * specified in the `pkl:settings` standard library module are used.\n */\n private val settings: URI? = null,\n\n /**\n * The root directory of the project. The directory must contain a `PklProject` that amends the\n * `pkl.Project` standard library module.\n *\n * If `null`, looks for a `PklProject` file in [workingDir], traversing up to [rootDir], or `/` if\n * [rootDir] is `null`.\n *\n * This can be disabled with [noProject].\n */\n private val projectDir: Path? = null,\n\n /**\n * The duration after which evaluation of a source module will be timed out. Note that a timeout\n * is treated the same as a program error in that any subsequent source modules will not be\n * evaluated.\n */\n val timeout: Duration? = null,\n\n /** The cache directory for storing packages. */\n private val moduleCacheDir: Path? = null,\n\n /** Whether to render errors in ANSI color. */\n val color: Color? = null,\n\n /** Whether to disable the module cache. */\n val noCache: Boolean = false,\n\n /** Ignores any evaluator settings set in the PklProject file. */\n val omitProjectSettings: Boolean = false,\n\n /** Disables all behavior related to projects. */\n val noProject: Boolean = false,\n\n /** Tells whether to run the CLI in test mode. This is an internal option. */\n val testMode: Boolean = false,\n\n /**\n * Unless -1, rewrites HTTP requests that specify port 0 to the given port. This is an internal\n * test option.\n */\n val testPort: Int = -1,\n\n /**\n * The CA certificates to trust.\n *\n * The given files must contain [X.509](https://en.wikipedia.org/wiki/X.509) certificates in PEM\n * format.\n *\n * If [caCertificates] is the empty list, the certificate files in `~/.pkl/cacerts/` are used. If\n * `~/.pkl/cacerts/` does not exist or is empty, Pkl's built-in CA certificates are used.\n */\n val caCertificates: List = listOf(),\n\n /** The proxy to connect to. */\n val httpProxy: URI? = null,\n\n /** Hostnames, IP addresses, or CIDR blocks to not proxy. */\n val httpNoProxy: List? = null,\n\n /** URL prefixes to rewrite. */\n val httpRewrites: Map? = null,\n\n /** External module reader process specs */\n val externalModuleReaders: Map = mapOf(),\n\n /** External resource reader process specs */\n val externalResourceReaders: Map = mapOf(),\n\n /** Defines options for the formatting of calls to the trace() method. */\n val traceMode: TraceMode? = null,\n\n /** Whether power assertions are enabled. */\n val powerAssertionsEnabled: Boolean = false,\n) {\n\n companion object {\n tailrec fun Path.getProjectFile(rootDir: Path?): Path? {\n val candidate = resolve(ProjectDependenciesManager.PKL_PROJECT_FILENAME)\n return when {\n Files.exists(candidate) -> candidate\n parent == null -> null\n rootDir != null && !parent.startsWith(rootDir) -> null\n else -> parent.getProjectFile(rootDir)\n }\n }\n }\n\n /** [workingDir] after normalization. */\n val normalizedWorkingDir: Path = IoUtils.getCurrentWorkingDir().resolve(workingDir)\n\n /** [rootDir] after normalization. */\n val normalizedRootDir: Path? = rootDir?.let(normalizedWorkingDir::resolve)\n\n /** The effective project directory, if exists. */\n val normalizedProjectFile: Path? by lazy {\n projectDir?.resolve(ProjectDependenciesManager.PKL_PROJECT_FILENAME)\n ?: normalizedWorkingDir.getProjectFile(rootDir)\n }\n\n /** [sourceModules] after normalization. */\n val normalizedSourceModules: List =\n sourceModules\n .map { uri ->\n if (uri.isAbsolute) uri\n else if (uri.path.startsWith(\"@\") && !noProject && normalizedProjectFile != null) uri\n else IoUtils.resolve(normalizedWorkingDir.toUri(), uri)\n }\n // sort modules to make cli output independent of source module order\n .sorted()\n\n val normalizedSettingsModule: URI? =\n settings?.let { uri ->\n if (uri.isAbsolute) uri else IoUtils.resolve(normalizedWorkingDir.toUri(), uri)\n }\n\n /** [modulePath] after normalization. */\n val normalizedModulePath: List? = modulePath?.map(normalizedWorkingDir::resolve)\n\n /** [moduleCacheDir] after normalization. */\n val normalizedModuleCacheDir: Path? = moduleCacheDir?.let(normalizedWorkingDir::resolve)\n\n /** [caCertificates] after normalization. */\n val normalizedCaCertificates: List = caCertificates.map(normalizedWorkingDir::resolve)\n}\n" }, { "path": "pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/CliCommand.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons.cli\n\nimport com.github.ajalt.clikt.core.CliktError\nimport java.net.URI\nimport java.nio.file.Files\nimport java.nio.file.Path\nimport java.util.regex.Pattern\nimport kotlin.io.path.isRegularFile\nimport org.pkl.core.*\nimport org.pkl.core.evaluatorSettings.PklEvaluatorSettings\nimport org.pkl.core.evaluatorSettings.TraceMode\nimport org.pkl.core.externalreader.ExternalReaderProcess\nimport org.pkl.core.http.HttpClient\nimport org.pkl.core.module.ModuleKeyFactories\nimport org.pkl.core.module.ModuleKeyFactory\nimport org.pkl.core.module.ModulePathResolver\nimport org.pkl.core.project.Project\nimport org.pkl.core.resource.ResourceReader\nimport org.pkl.core.resource.ResourceReaders\nimport org.pkl.core.settings.PklSettings\nimport org.pkl.core.util.IoUtils\n\n/** Building block for CLI commands. Configured programmatically to allow for embedding. */\nabstract class CliCommand(protected val cliOptions: CliBaseOptions) {\n /** Runs this command. */\n fun run() {\n if (cliOptions.testMode) {\n IoUtils.setTestMode()\n }\n\n try {\n proxyAddress?.let(IoUtils::setSystemProxy)\n doRun()\n } catch (e: PklException) {\n if (e.cause is CliktError) throw e.cause!!\n throw CliException(e.message!!)\n } catch (e: CliException) {\n throw e\n } catch (e: Exception) {\n throw CliBugException(e)\n }\n }\n\n /**\n * Implements this command. May throw [PklException] or [CliException]. Any other thrown exception\n * is treated as a bug.\n */\n protected abstract fun doRun()\n\n /** The Pkl settings used by this command. */\n @Suppress(\"MemberVisibilityCanBePrivate\")\n protected val settings: PklSettings by lazy {\n try {\n if (cliOptions.normalizedSettingsModule != null) {\n PklSettings.load(ModuleSource.uri(cliOptions.normalizedSettingsModule))\n } else {\n PklSettings.loadFromPklHomeDir()\n }\n } catch (e: PklException) {\n // do not use `errorRenderer` because it depends on `settings`\n throw CliException(e.toString())\n }\n }\n\n /** The Project used by this command. */\n protected val project: Project? by lazy {\n if (cliOptions.noProject) {\n null\n } else {\n cliOptions.normalizedProjectFile?.let { loadProject(it) }\n }\n }\n\n protected fun resolveModuleUri(uri: URI): URI =\n if (uri.isAbsolute) uri\n else { // must be @dep/mod.pkl notation!!\n if (!uri.path.startsWith('@'))\n throw CliBugException(\n RuntimeException(\"tried to resolve project URI `$uri` with no @ prefix\")\n )\n if (project == null)\n throw CliBugException(\n RuntimeException(\"tried to resolve project URI `$uri` with no project present\")\n )\n val dep = uri.path.substringBefore('/').drop(1)\n val path = uri.path.dropWhile { it != '/' }\n if (path.isEmpty()) throw CliException(\"Invalid project dependency URI `$uri`.\")\n\n val remoteDep =\n project!!.dependencies.remoteDependencies()[dep]\n ?: if (project!!.dependencies.localDependencies().containsKey(dep))\n throw CliException(\n \"Only remote project dependencies may be referenced using @-notation. Dependency `@$dep` is a local dependency.\"\n )\n else throw CliException(\"Project does not contain dependency `@$dep`.\")\n remoteDep.packageUri.toPackageAssetUri(path).uri\n }\n\n protected val resolvedSourceModules: List by lazy {\n if (project == null) cliOptions.normalizedSourceModules\n else cliOptions.normalizedSourceModules.map(::resolveModuleUri)\n }\n\n protected fun loadProject(projectFile: Path): Project {\n val securityManager =\n SecurityManagers.standard(\n cliOptions.allowedModules ?: SecurityManagers.defaultAllowedModules,\n cliOptions.allowedResources ?: SecurityManagers.defaultAllowedResources,\n SecurityManagers.defaultTrustLevels,\n cliOptions.normalizedRootDir,\n )\n val envVars = cliOptions.environmentVariables ?: System.getenv()\n val stackFrameTransformer =\n if (IoUtils.isTestMode()) StackFrameTransformers.empty\n else StackFrameTransformers.defaultTransformer\n return Project.loadFromPath(\n projectFile,\n securityManager,\n cliOptions.timeout,\n stackFrameTransformer,\n envVars,\n cliOptions.powerAssertionsEnabled,\n )\n }\n\n private val evaluatorSettings: PklEvaluatorSettings? by lazy {\n @Suppress(\"PklCliDirectProjectEvaluatorSettingsAccess\")\n if (cliOptions.omitProjectSettings) null else project?.evaluatorSettings\n }\n\n protected val allowedModules: List by lazy {\n cliOptions.allowedModules\n ?: evaluatorSettings?.allowedModules\n ?: (SecurityManagers.defaultAllowedModules +\n externalModuleReaders.keys.map { Pattern.compile(Pattern.quote(\"$it:\")) }.toList())\n }\n\n protected val allowedResources: List by lazy {\n cliOptions.allowedResources\n ?: evaluatorSettings?.allowedResources\n ?: (SecurityManagers.defaultAllowedResources +\n externalResourceReaders.keys.map { Pattern.compile(Pattern.quote(\"$it:\")) }.toList())\n }\n\n protected val rootDir: Path? by lazy {\n cliOptions.normalizedRootDir ?: evaluatorSettings?.rootDir\n }\n\n protected val environmentVariables: Map by lazy {\n cliOptions.environmentVariables ?: evaluatorSettings?.env ?: System.getenv()\n }\n\n protected val externalProperties: Map by lazy {\n cliOptions.externalProperties ?: evaluatorSettings?.externalProperties ?: emptyMap()\n }\n\n protected val moduleCacheDir: Path? by lazy {\n if (cliOptions.noCache) null\n else\n cliOptions.normalizedModuleCacheDir\n ?: evaluatorSettings?.let { settings ->\n if (settings.noCache == true) null else settings.moduleCacheDir\n }\n ?: IoUtils.getDefaultModuleCacheDir()\n }\n\n protected val modulePath: List by lazy {\n cliOptions.normalizedModulePath ?: evaluatorSettings?.modulePath ?: emptyList()\n }\n\n protected val stackFrameTransformer: StackFrameTransformer by lazy {\n if (cliOptions.testMode) {\n StackFrameTransformers.empty\n } else {\n StackFrameTransformers.createDefault(settings)\n }\n }\n\n protected val securityManager: SecurityManager by lazy {\n SecurityManagers.standard(\n allowedModules,\n allowedResources,\n SecurityManagers.defaultTrustLevels,\n rootDir,\n )\n }\n\n protected val useColor: Boolean by lazy {\n cliOptions.color?.hasColor() ?: evaluatorSettings?.color?.hasColor() ?: false\n }\n\n protected val proxyAddress: URI? by lazy {\n cliOptions.httpProxy ?: evaluatorSettings?.http?.proxy?.address ?: settings.http?.proxy?.address\n }\n\n protected val noProxy: List? by lazy {\n cliOptions.httpNoProxy\n ?: evaluatorSettings?.http?.proxy?.noProxy\n ?: settings.http?.proxy?.noProxy\n }\n\n protected val httpRewrites: Map? by lazy {\n cliOptions.httpRewrites ?: evaluatorSettings?.http?.rewrites ?: settings.http?.rewrites()\n }\n\n protected val externalModuleReaders: Map by lazy {\n (evaluatorSettings?.externalModuleReaders ?: emptyMap()) + cliOptions.externalModuleReaders\n }\n\n protected val externalResourceReaders: Map by lazy {\n (evaluatorSettings?.externalResourceReaders ?: emptyMap()) + cliOptions.externalResourceReaders\n }\n\n private val externalProcesses:\n Map by lazy {\n // Share ExternalReaderProcess instances between configured external resource/module readers\n // with the same spec. This avoids spawning multiple subprocesses if the same reader implements\n // both reader types and/or multiple schemes.\n (externalModuleReaders + externalResourceReaders).values.toSet().associateWith {\n ExternalReaderProcess.of(it)\n }\n }\n\n private val traceMode: TraceMode by lazy {\n cliOptions.traceMode ?: evaluatorSettings?.traceMode ?: TraceMode.COMPACT\n }\n\n private fun HttpClient.Builder.addDefaultCliCertificates() {\n val caCertsDir = IoUtils.getPklHomeDir().resolve(\"cacerts\")\n var certsAdded = false\n if (Files.isDirectory(caCertsDir)) {\n Files.list(caCertsDir)\n .filter { it.isRegularFile() }\n .forEach { cert ->\n certsAdded = true\n addCertificates(cert)\n }\n }\n if (!certsAdded) {\n val defaultCerts =\n this@CliCommand.javaClass.classLoader.getResourceAsStream(\n \"org/pkl/commons/cli/PklCARoots.pem\"\n ) ?: throw CliException(\"Could not find bundled certificates\")\n addCertificates(defaultCerts.readAllBytes())\n }\n }\n\n /**\n * The HTTP client used for this command.\n *\n * To release resources held by the HTTP client in a timely manner, call [HttpClient.close].\n */\n val httpClient: HttpClient by lazy {\n with(HttpClient.builder()) {\n setTestPort(cliOptions.testPort)\n if (cliOptions.normalizedCaCertificates.isEmpty()) {\n addDefaultCliCertificates()\n } else {\n for (file in cliOptions.normalizedCaCertificates) addCertificates(file)\n }\n if ((proxyAddress ?: noProxy) != null) {\n setProxy(proxyAddress, noProxy ?: listOf())\n }\n httpRewrites?.let(::setRewrites)\n // Lazy building significantly reduces execution time of commands that do minimal work.\n // However, it means that HTTP client initialization errors won't surface until an HTTP\n // request is made.\n buildLazily()\n }\n }\n\n protected fun moduleKeyFactories(modulePathResolver: ModulePathResolver): List {\n return buildList {\n externalModuleReaders.forEach { (key, value) ->\n add(ModuleKeyFactories.externalProcess(key, externalProcesses[value]!!))\n }\n add(ModuleKeyFactories.standardLibrary)\n add(ModuleKeyFactories.modulePath(modulePathResolver))\n add(ModuleKeyFactories.pkg)\n add(ModuleKeyFactories.projectpackage)\n addAll(ModuleKeyFactories.fromServiceProviders())\n add(ModuleKeyFactories.file)\n add(ModuleKeyFactories.http)\n add(ModuleKeyFactories.genericUrl)\n }\n }\n\n private fun resourceReaders(modulePathResolver: ModulePathResolver): List {\n return buildList {\n add(ResourceReaders.environmentVariable())\n add(ResourceReaders.externalProperty())\n add(ResourceReaders.modulePath(modulePathResolver))\n add(ResourceReaders.pkg())\n add(ResourceReaders.projectpackage())\n add(ResourceReaders.file())\n add(ResourceReaders.http())\n add(ResourceReaders.https())\n externalResourceReaders.forEach { (key, value) ->\n add(ResourceReaders.externalProcess(key, externalProcesses[value]!!))\n }\n }\n }\n\n /**\n * Creates an [EvaluatorBuilder] preconfigured according to [cliOptions]. To avoid resource leaks,\n * `ModuleKeyFactories.closeQuietly(builder.moduleKeyFactories)` must be called once the returned\n * builder and evaluators built by it are no longer in use.\n */\n protected fun evaluatorBuilder(): EvaluatorBuilder {\n // indirectly closed by `ModuleKeyFactories.closeQuietly(builder.moduleKeyFactories)`\n val modulePathResolver = ModulePathResolver(modulePath)\n return EvaluatorBuilder.unconfigured()\n .setStackFrameTransformer(stackFrameTransformer)\n .apply { project?.let { setProjectDependencies(it.dependencies) } }\n .setSecurityManager(securityManager)\n .setHttpClient(httpClient)\n .setExternalProperties(externalProperties)\n .setEnvironmentVariables(environmentVariables)\n .addModuleKeyFactories(moduleKeyFactories(modulePathResolver))\n .addResourceReaders(resourceReaders(modulePathResolver))\n .setColor(useColor)\n .setLogger(Loggers.stdErr())\n .setTimeout(cliOptions.timeout)\n .setModuleCacheDir(moduleCacheDir)\n .setTraceMode(traceMode)\n .setPowerAssertionsEnabled(cliOptions.powerAssertionsEnabled)\n }\n}\n" }, { "path": "pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/CliException.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons.cli\n\nimport org.pkl.commons.printStackTraceToString\n\n/** A CLI error to report back to users. */\nopen class CliException(\n /**\n * The error message to report back to CLI users. The message is expected to be displayed as-is\n * without any further enrichment. As such the message should be comprehensive and designed with\n * the CLI user in mind.\n */\n message: String,\n\n /** The cause */\n cause: Throwable?,\n\n /** The process exit code to use. */\n val exitCode: Int = 1,\n) : RuntimeException(message, cause) {\n constructor(message: String, exitCode: Int = 1) : this(message, null, exitCode)\n\n override fun toString(): String = message!!\n}\n\n/** An unexpected CLI error classified as bug. */\nclass CliBugException(\n /** The cause for the bug. */\n private val theCause: Exception,\n\n /** The process exit code to use. */\n exitCode: Int = 1,\n) :\n CliException(\n \"An unexpected error has occurred. Would you mind filing a bug report?\",\n theCause,\n exitCode,\n ) {\n\n override fun toString(): String = \"$message\\n\\n${theCause.printStackTraceToString()}\"\n}\n" }, { "path": "pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/CliMain.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons.cli\n\nimport java.io.PrintStream\nimport kotlin.system.exitProcess\n\n/** Building block for CLIs. Intended to be called from a `main` method. */\nfun cliMain(block: () -> Unit) {\n fun printError(error: Throwable, stream: PrintStream) {\n val message = error.toString()\n stream.print(message)\n // ensure CLI output always ends with newline\n if (!message.endsWith('\\n')) stream.println()\n }\n\n // Force `native-image` to use system proxies (which does not happen with `-D`).\n System.setProperty(\"java.net.useSystemProxies\", \"true\")\n try {\n block()\n } catch (e: CliTestException) {\n // no need to print the error, the test results will already do it\n exitProcess(e.exitCode)\n } catch (e: CliException) {\n printError(e, if (e.exitCode == 0) System.out else System.err)\n exitProcess(e.exitCode)\n } catch (e: Exception) {\n printError(CliBugException(e), System.err)\n exitProcess(1)\n }\n}\n" }, { "path": "pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/CliTestException.kt", "content": "/*\n * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons.cli\n\nclass CliTestException(msg: String, exitCode: Int) : CliException(msg, exitCode)\n" }, { "path": "pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/CliTestOptions.kt", "content": "/*\n * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons.cli\n\nimport java.nio.file.Path\n\nclass CliTestOptions(\n val junitDir: Path? = null,\n val overwrite: Boolean = false,\n val junitAggregateReports: Boolean = false,\n val junitAggregateSuiteName: String = \"pkl-tests\",\n)\n" }, { "path": "pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/BaseCommand.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons.cli.commands\n\nimport com.github.ajalt.clikt.core.CliktCommand\nimport com.github.ajalt.clikt.core.Context\nimport com.github.ajalt.clikt.core.context\nimport com.github.ajalt.clikt.parameters.groups.provideDelegate\n\nabstract class BaseCommand(name: String, private val helpLink: String) : CliktCommand(name = name) {\n init {\n context { readArgumentFile = null }\n }\n\n abstract val helpString: String\n\n override fun help(context: Context) = helpString\n\n final override fun helpEpilog(context: Context) = \"For more information, visit $helpLink\"\n\n val baseOptions: BaseOptions by BaseOptions()\n}\n" }, { "path": "pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/BaseOptions.kt", "content": "/*\n * Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\npackage org.pkl.commons.cli.commands\n\nimport com.github.ajalt.clikt.completion.CompletionCandidates\nimport com.github.ajalt.clikt.parameters.groups.OptionGroup\nimport com.github.ajalt.clikt.parameters.options.*\nimport com.github.ajalt.clikt.parameters.types.enum\nimport com.github.ajalt.clikt.parameters.types.int\nimport com.github.ajalt.clikt.parameters.types.long\nimport com.github.ajalt.clikt.parameters.types.path\nimport java.io.File\nimport java.net.URI\nimport java.net.URISyntaxException\nimport java.nio.file.Path\nimport java.time.Duration\nimport java.util.regex.Pattern\nimport org.pkl.commons.cli.CliBaseOptions\nimport org.pkl.commons.cli.CliException\nimport org.pkl.commons.shlex\nimport org.pkl.core.evaluatorSettings.Color\nimport org.pkl.core.evaluatorSettings.PklEvaluatorSettings.ExternalReader\nimport org.pkl.core.evaluatorSettings.TraceMode\nimport org.pkl.core.runtime.VmUtils\nimport org.pkl.core.util.IoUtils\n\n@Suppress(\"MemberVisibilityCanBePrivate\")\nclass BaseOptions : OptionGroup() {\n companion object {\n /**\n * Parses [moduleName] into a URI. If scheme is not present, we expect that this is a file path\n * and encode any possibly invalid characters, and also normalize directory separators. If a\n * scheme is present, we expect that this is a valid URI.\n */\n fun parseModuleName(moduleName: String): URI =\n when (moduleName) {\n \"-\" -> VmUtils.REPL_TEXT_URI\n else ->\n // Don't use `IoUtils.toUri` here becaus we need to normalize `\\` paths to `/` on Windows.\n try {\n if (IoUtils.isUriLike(moduleName)) URI(moduleName)\n // Can't just use URI constructor, because URI(null, null, \"C:/foo/bar\", null) turns\n // into `URI(\"C\", null, \"/foo/bar\", null)`.\n else if (IoUtils.isWindowsAbsolutePath(moduleName)) Path.of(moduleName).toUri()\n else URI(null, null, IoUtils.toNormalizedPathString(Path.of(moduleName)), null)\n } catch (e: URISyntaxException) {\n val message = buildString {\n append(\"Module URI `$moduleName` has invalid syntax (${e.reason}).\")\n if (e.index > -1) {\n append(\"\\n\\n\")\n append(moduleName)\n append(\"\\n\")\n append(\" \".repeat(e.index))\n append(\"^\")\n }\n }\n throw CliException(message)\n }\n }\n\n fun RawOption.associateProps():\n OptionWithValues, Pair, Pair> {\n return convert {\n val eq = it.indexOf('=')\n if (eq == -1) it to \"true\" else it.substring(0, eq) to it.substring(eq + 1)\n }\n .multiple()\n .toMap()\n }\n\n fun OptionWithValues.parseExternalReader(\n delimiter: String\n ): OptionWithValues<\n Pair?,\n Pair,\n Pair,\n > {\n return splitPair(delimiter).convert {\n val cmd = shlex(it.second)\n Pair(it.first, ExternalReader(cmd.first(), cmd.drop(1)))\n }\n }\n }\n\n private val defaults = CliBaseOptions()\n\n private val output =\n arrayOf(\n \"json\",\n \"jsonnet\",\n \"pcf\",\n \"properties\",\n \"plist\",\n \"textproto\",\n \"xml\",\n \"yaml\",\n \"pkl-binary\",\n )\n\n val allowedModules: List by\n option(\n names = arrayOf(\"--allowed-modules\"),\n help = \"URI patterns that determine which modules can be loaded and evaluated.\",\n )\n .convert(\"pattern1,pattern2\") { Pattern.compile(it) }\n .splitAll()\n\n val allowedResources: List by\n option(\n names = arrayOf(\"--allowed-resources\"),\n help = \"URI patterns that determine which external resources can be read.\",\n )\n .convert(\"pattern1,pattern2\") { Pattern.compile(it) }\n .splitAll()\n\n val rootDir: Path? by\n option(\n names = arrayOf(\"--root-dir\"),\n help =\n \"Restricts access to file-based modules and resources to those located under the root directory.\",\n )\n .single()\n .path()\n\n val cacheDir: Path? by\n option(names = arrayOf(\"--cache-dir\"), help = \"The cache directory for storing packages.\")\n .single()\n .path()\n\n val workingDir: Path by\n option(\n names = arrayOf(\"-w\", \"--working-dir\"),\n help = \"Base path that relative module paths are resolved against.\",\n )\n .single()\n .path()\n .default(defaults.normalizedWorkingDir)\n\n val properties: Map by\n option(\n names = arrayOf(\"-p\", \"--property\"),\n metavar = \"name=value\",\n help = \"External property to set (repeatable).\",\n )\n .associateProps()\n\n val color: Color by\n option(\n names = arrayOf(\"--color\"),\n metavar = \"when\",\n help =\n \"Whether to format messages in ANSI color. Possible values of are 'never', 'auto', and 'always'.\",\n )\n .enum { it.name.lowercase() }\n .single()\n .default(Color.AUTO)\n\n val noCache: Boolean by\n option(names = arrayOf(\"--no-cache\"), help = \"Disable caching of packages\")\n .single()\n .flag(default = false)\n\n val format: String? by\n option(\n names = arrayOf(\"-f\", \"--format\"),\n help = \"Output format to generate. <${output.joinToString()}>\",\n completionCandidates = CompletionCandidates.Fixed(output.toSet()),\n )\n .single()\n\n val envVars: Map by\n option(\n names = arrayOf(\"-e\", \"--env-var\"),\n metavar = \"name=value\",\n help = \"Environment variable to set (repeatable).\",\n )\n .associate()\n\n val modulePath: List by\n option(\n names = arrayOf(\"--module-path\"),\n metavar = \"path1${File.pathSeparator}path2\",\n help =\n \"Directories, ZIP archives, or JAR archives to search when resolving `modulepath:` URIs.\",\n )\n .path()\n .splitAll(File.pathSeparator)\n\n val settings: URI? by\n option(\n names = arrayOf(\"--settings\"),\n help = \"Pkl settings module to use.\",\n completionCandidates = CompletionCandidates.Path,\n )\n .single()\n .convert { parseModuleName(it) }\n\n val timeout: Duration? by\n option(\n names = arrayOf(\"-t\", \"--timeout\"),\n metavar = \"number\",\n help = \"Duration, in seconds, after which evaluation of a source module will be timed out.\",\n )\n .single()\n .long()\n .convert { Duration.ofSeconds(it) }\n\n val caCertificates: List by\n option(\n names = arrayOf(\"--ca-certificates\"),\n metavar = \"path\",\n help = \"Only trust CA certificates from the provided file(s).\",\n )\n .path()\n .multiple()\n\n val proxy: URI? by\n option(\n names = arrayOf(\"--http-proxy\"),\n metavar = \"address\",\n help = \"Proxy to use for HTTP(S) connections.\",\n )\n .single()\n .convert { URI(it) }\n .validate { uri ->\n require(\n uri.scheme == \"http\" && uri.host != null && uri.path.isEmpty() && uri.userInfo == null\n ) {\n \"Malformed proxy URI (expecting `http://[:]`)\"\n }\n }\n\n val noProxy: List? by\n option(\n names = arrayOf(\"--http-no-proxy\"),\n metavar = \"pattern1,pattern\",\n help = \"Hostnames that should not be connected to via a proxy.\",\n )\n .single()\n .split(\",\")\n\n val httpRewrites: Map by\n option(\n names = arrayOf(\"--http-rewrite\"),\n metavar = \"from=to\",\n help = \"URL prefixes that should be rewritten.\",\n )\n .convert { it ->\n val uris = it.split(\"=\", limit = 2)\n require(uris.size == 2) { \"Rewrites must be in the form of =\" }\n try {\n val (fromSpec, toSpec) = uris\n val fromUri = URI(fromSpec).also { IoUtils.validateRewriteRule(it) }\n val toUri = URI(toSpec).also { IoUtils.validateRewriteRule(it) }\n fromUri to toUri\n } catch (e: IllegalArgumentException) {\n fail(e.message!!)\n } catch (e: URISyntaxException) {\n val message = buildString {\n append(\"Rewrite target `${e.input}` has invalid syntax (${e.reason}).\")\n if (e.index > -1) {\n append(\"\\n\\n\")\n append(e.input)\n append(\"\\n\")\n append(\" \".repeat(e.index))\n append(\"^\")\n }\n }\n fail(message)\n }\n }\n .multiple()\n .toMap()\n\n val externalModuleReaders: Map by\n option(\n names = arrayOf(\"--external-module-reader\"),\n metavar = \"=' []'\",\n help = \"External reader registrations for module URI schemes\",\n )\n .parseExternalReader(\"=\")\n .multiple()\n .toMap()\n\n val externalResourceReaders: Map by\n option(\n names = arrayOf(\"--external-resource-reader\"),\n metavar = \"=' []'\",\n help = \"External reader registrations for resource URI schemes\",\n )\n .parseExternalReader(\"=\")\n .multiple()\n .toMap()\n\n val traceMode: TraceMode? by\n option(\n names = arrayOf(\"--trace-mode\"),\n metavar = \"style\",\n help =\n \"Specifies how calls to trace() are formatted. Possible values of