[PR #1100] [MERGED] Adds traceMode evaluator setting to support trace() pretty printing #887

New Issue

2025-12-30T01:27:35+01:00

adam commented

2025-12-30 01:27:35 +01:00

📋 Pull Request Information

Original PR: https://github.com/apple/pkl/pull/1100
Author: @ssalevan
Created: 6/16/2025
Status: ✅ Merged
Merged: 10/7/2025
Merged by: @HT154

Base: main ← Head: ssalevan/pretty-traces

📝 Commits (5)

c639d08 Adds prettyTrace evaluator setting to support indented, multi-line trace() output
1257e5d Converts prettyTraces to TraceMode, loops into pkl-server
30193d6 Adds traceMode option to CLI arguments
a12dceb Correct missing TraceMode specification
8139288 Bumps version to 0.30.0

📊 Changes

43 files changed (+383 additions, -27 deletions)

View changed files

📝 bench/src/jmh/java/org/pkl/core/ListSort.java (+3 -2)
📝 docs/src/test/kotlin/DocSnippetTests.kt (+1 -0)
📝 pkl-cli/src/main/kotlin/org/pkl/cli/CliRepl.kt (+1 -0)
📝 pkl-cli/src/test/kotlin/org/pkl/cli/repl/ReplMessagesTest.kt (+1 -0)
📝 pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/CliBaseOptions.kt (+4 -0)
📝 pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/BaseOptions.kt (+13 -0)
📝 pkl-core/src/main/java/org/pkl/core/Analyzer.java (+7 -2)
📝 pkl-core/src/main/java/org/pkl/core/EvaluatorBuilder.java (+22 -1)
📝 pkl-core/src/main/java/org/pkl/core/EvaluatorImpl.java (+5 -2)
📝 pkl-core/src/main/java/org/pkl/core/ast/expression/unary/TraceNode.java (+17 -3)
📝 pkl-core/src/main/java/org/pkl/core/evaluatorSettings/PklEvaluatorSettings.java (+16 -4)
➕ pkl-core/src/main/java/org/pkl/core/evaluatorSettings/TraceMode.java (+26 -0)
📝 pkl-core/src/main/java/org/pkl/core/messaging/AbstractMessagePackEncoder.java (+4 -2)
📝 pkl-core/src/main/java/org/pkl/core/project/Project.java (+10 -4)
📝 pkl-core/src/main/java/org/pkl/core/repl/ReplServer.java (+5 -2)
📝 pkl-core/src/main/java/org/pkl/core/runtime/StdLibModule.java (+2 -1)
📝 pkl-core/src/main/java/org/pkl/core/runtime/VmContext.java (+10 -2)
➕ pkl-core/src/test/files/LanguageSnippetTests/input/projects/defaultTraceMode/PklProject (+5 -0)
➕ pkl-core/src/test/files/LanguageSnippetTests/input/projects/defaultTraceMode/defaultTraceMode.pkl (+18 -0)
➕ pkl-core/src/test/files/LanguageSnippetTests/input/projects/evaluatorSettings/nullTraceMode.pkl (+18 -0)

...and 23 more files

📄 Description

Problem

Calling trace(...) upon a complex Pkl data structure results in a compact, single-line evaluation of that structure, which is non-ideal when debugging complex rendering scenarios.

Solution

Adds a new evaluator setting, traceMode, which supports the following values:

"hidden": No trace() calls will be emitted to stderr
"default": All structures passed to trace(...) will be emitted to stderr in compact, single-line form.
"pretty": All structures passed to trace(...) will be emitted to stderr in indented, multi-line form.

As this mechanism needs to be evaluated within the TraceNode visitor, this setting is ultimately plumbed into the VmContext to be accessible from an executeGeneric()->doTrace() call. This approach seemed to be the most idiomatic, but there may ultimately be more straightforward options for exposing this value at the doTrace() level.

Testing

Added Pkl, Java and Kotlin tests across all applicable areas to ensure correct parsing of traceMode value alongside expected behavior. Ensured that all spotless formatting checks ran cleanly.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/apple/pkl/pull/1100 **Author:** [@ssalevan](https://github.com/ssalevan) **Created:** 6/16/2025 **Status:** ✅ Merged **Merged:** 10/7/2025 **Merged by:** [@HT154](https://github.com/HT154) **Base:** `main` ← **Head:** `ssalevan/pretty-traces` --- ### 📝 Commits (5) - [`c639d08`](https://github.com/apple/pkl/commit/c639d0881d4ca5d44723eeeb691023ea22698d14) Adds prettyTrace evaluator setting to support indented, multi-line trace() output - [`1257e5d`](https://github.com/apple/pkl/commit/1257e5dcadd67b331f238ccd57d2f6afe1a94d1e) Converts prettyTraces to TraceMode, loops into pkl-server - [`30193d6`](https://github.com/apple/pkl/commit/30193d6a26bfc2dc3a04028bf2cbb2519f2a06cc) Adds traceMode option to CLI arguments - [`a12dceb`](https://github.com/apple/pkl/commit/a12dceb923aa736e6cc7050b0ccd416f2bef6bec) Correct missing TraceMode specification - [`8139288`](https://github.com/apple/pkl/commit/81392887be0754e550f8734d94e079f3ebf1c7f4) Bumps version to 0.30.0 ### 📊 Changes **43 files changed** (+383 additions, -27 deletions) <details> <summary>View changed files</summary> 📝 `bench/src/jmh/java/org/pkl/core/ListSort.java` (+3 -2) 📝 `docs/src/test/kotlin/DocSnippetTests.kt` (+1 -0) 📝 `pkl-cli/src/main/kotlin/org/pkl/cli/CliRepl.kt` (+1 -0) 📝 `pkl-cli/src/test/kotlin/org/pkl/cli/repl/ReplMessagesTest.kt` (+1 -0) 📝 `pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/CliBaseOptions.kt` (+4 -0) 📝 `pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/commands/BaseOptions.kt` (+13 -0) 📝 `pkl-core/src/main/java/org/pkl/core/Analyzer.java` (+7 -2) 📝 `pkl-core/src/main/java/org/pkl/core/EvaluatorBuilder.java` (+22 -1) 📝 `pkl-core/src/main/java/org/pkl/core/EvaluatorImpl.java` (+5 -2) 📝 `pkl-core/src/main/java/org/pkl/core/ast/expression/unary/TraceNode.java` (+17 -3) 📝 `pkl-core/src/main/java/org/pkl/core/evaluatorSettings/PklEvaluatorSettings.java` (+16 -4) ➕ `pkl-core/src/main/java/org/pkl/core/evaluatorSettings/TraceMode.java` (+26 -0) 📝 `pkl-core/src/main/java/org/pkl/core/messaging/AbstractMessagePackEncoder.java` (+4 -2) 📝 `pkl-core/src/main/java/org/pkl/core/project/Project.java` (+10 -4) 📝 `pkl-core/src/main/java/org/pkl/core/repl/ReplServer.java` (+5 -2) 📝 `pkl-core/src/main/java/org/pkl/core/runtime/StdLibModule.java` (+2 -1) 📝 `pkl-core/src/main/java/org/pkl/core/runtime/VmContext.java` (+10 -2) ➕ `pkl-core/src/test/files/LanguageSnippetTests/input/projects/defaultTraceMode/PklProject` (+5 -0) ➕ `pkl-core/src/test/files/LanguageSnippetTests/input/projects/defaultTraceMode/defaultTraceMode.pkl` (+18 -0) ➕ `pkl-core/src/test/files/LanguageSnippetTests/input/projects/evaluatorSettings/nullTraceMode.pkl` (+18 -0) _...and 23 more files_ </details> ### 📄 Description Problem ------- Calling `trace(...)` upon a complex Pkl data structure results in a compact, single-line evaluation of that structure, which is non-ideal when debugging complex rendering scenarios. Solution -------- Adds a new evaluator setting, `traceMode`, which supports the following values: * `"hidden"`: No trace() calls will be emitted to stderr * `"default"`: All structures passed to `trace(...)` will be emitted to stderr in compact, single-line form. * `"pretty"`: All structures passed to `trace(...)` will be emitted to stderr in indented, multi-line form. As this mechanism needs to be evaluated within the `TraceNode` visitor, this setting is ultimately plumbed into the `VmContext` to be accessible from an `executeGeneric()->doTrace()` call. This approach seemed to be the most idiomatic, but there may ultimately be more straightforward options for exposing this value at the `doTrace()` level. Testing ------- Added Pkl, Java and Kotlin tests across all applicable areas to ensure correct parsing of `traceMode` value alongside expected behavior. Ensured that all spotless formatting checks ran cleanly. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

adam added the pull-request label 2025-12-30 01:27:35 +01:00

adam closed this issue

2025-12-30 01:27:35 +01:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/pkl#887