starred/pkl
1
0
Fork 0
mirror of https://github.com/apple/pkl.git synced 2026-01-11 22:30:54 +01:00
Code Issues 198 Packages Projects Releases 10 Wiki Activity

Improve interaction between -x and -f eval flags #241

New Issue
Open
opened 2025-12-30 01:22:37 +01:00 by adam · 7 comments
adam commented 2025-12-30 01:22:37 +01:00
Owner
Copy Link

Originally created by @cakemanny on GitHub (Nov 2, 2024).

When using eval's -x option, the --format option appears to be ignored.

Evaluating the following

pkl eval --format=json -x y - <<EOF            
x { 1; 2; 3 }
y { "a"; "b"; "c" }
EOF

gives

new Dynamic { "a"; "b"; "c" }

I had expected it to give

[
  "a",
  "b",
  "c"
]

Checked with Pkl 0.26.3 (macOS 14.4.1, native) and a build from main, Pkl 0.27.0-dev+9692504 (macOS 14.6.1, native).

If only always wanting a fixed format, a workaround for now is to configure both wishes in the output property.

Details

x { 1; 2; 3 }
y { "a"; "b"; "c" }

output {
  renderer = new JsonRenderer {}
  value = y
}

Originally created by @cakemanny on GitHub (Nov 2, 2024). When using eval's `-x` option, the `--format` option appears to be ignored. Evaluating the following ```shell pkl eval --format=json -x y - <<EOF x { 1; 2; 3 } y { "a"; "b"; "c" } EOF ``` gives ``` new Dynamic { "a"; "b"; "c" } ``` I had expected it to give ``` [ "a", "b", "c" ] ``` Checked with `Pkl 0.26.3 (macOS 14.4.1, native)` and a build from main, `Pkl 0.27.0-dev+9692504 (macOS 14.6.1, native)`. If only always wanting a fixed format, a workaround for now is to configure both wishes in the output property. <details><summary>Details</summary><p> ```pkl x { 1; 2; 3 } y { "a"; "b"; "c" } output { renderer = new JsonRenderer {} value = y } ``` </p></details>
adam commented 2025-12-30 01:22:38 +01:00
Author
Owner
Copy Link

@HT154 commented on GitHub (Nov 2, 2024):

This a dupe of #742

@HT154 commented on GitHub (Nov 2, 2024): This a dupe of #742
adam commented 2025-12-30 01:22:38 +01:00
Author
Owner
Copy Link

@cakemanny commented on GitHub (Nov 2, 2024):

Ahh, ok. So what I have to understand is that the default for -x is actually output.text and that --format changes the renderer that is used to construct that value.

I guess the part about -x and output.text is implied in the online docs about pkl eval. Though not apparent when only reading the CLI --help output.

Perhaps it's possible to improve the docs for the --format option, make it clearer that it's changing the modules' renderers rather than ensuring a specific output format.

I think Pkl stands out here as, with Pkl, rendering happens inside the language behind this hidden output property. Anyone coming to Pkl from another configuration language might expect that the language stops once the contents of the module file have been computed and then the tool is rendering to the supported formats.

Rereading the introduction's concepts, the paragraph on evaluation seems to misrepresent Pkl in this regard:

Evaluating a module produces an in-memory data model that is roughly comparable to a JSON data model. If evaluation completes successfully, the Pkl evaluator converts the data model to an external representation

To me it implies that Pkl works like how I understand Dhall, CUE and KCL to work. (Which I now believe not to be the case).

Sorry for this wall of text. I really just wanted to try to explore where my misconceptions came from and see if I could help find a way to avoid someone else falling into this trap.

Also, in case it's helpful, the use case that I had was: given a large amount of configuration in a single module, can Pkl select and output only part of it. That's what I was after when I spotted the -x option. In case that's useful input to future ergonomics.

@cakemanny commented on GitHub (Nov 2, 2024): Ahh, ok. So what I have to understand is that the default for `-x` is actually `output.text` and that `--format` changes the renderer that is used to construct that value. I guess the part about `-x` and `output.text` is implied in the online docs about [pkl eval](https://pkl-lang.org/main/current/pkl-cli/index.html#command-eval). Though not apparent when only reading the CLI `--help` output. Perhaps it's possible to improve the docs for the `--format` option, make it clearer that it's changing the modules' renderers rather than ensuring a specific output format. I think Pkl stands out here as, with Pkl, rendering happens inside the language behind this hidden output property. Anyone coming to Pkl from another configuration language might expect that the language stops once the contents of the module file have been computed and then the tool is rendering to the supported formats. Rereading the introduction's [concepts](https://pkl-lang.org/main/current/introduction/concepts.html), the paragraph on [evaluation](https://pkl-lang.org/main/current/introduction/concepts.html#evaluation) seems to misrepresent Pkl in this regard: > Evaluating a module produces an in-memory _data model_ that is roughly comparable to a JSON data model. If evaluation completes successfully, the Pkl evaluator converts the data model to an external representation To me it implies that Pkl works like how I understand Dhall, CUE and KCL to work. (Which I now believe not to be the case). Sorry for this wall of text. I really just wanted to try to explore where my misconceptions came from and see if I could help find a way to avoid someone else falling into this trap. Also, in case it's helpful, the use case that I had was: given a large amount of configuration in a single module, can Pkl select and output only part of it. That's what I was after when I spotted the `-x` option. In case that's useful input to future ergonomics.
adam commented 2025-12-30 01:22:38 +01:00
Author
Owner
Copy Link

@odenix commented on GitHub (Nov 2, 2024):

Is there a reason why -x isn't defined as "set output.value"?

@odenix commented on GitHub (Nov 2, 2024): Is there a reason why `-x` isn't defined as "set output.value"?
adam commented 2025-12-30 01:22:38 +01:00
Author
Owner
Copy Link

@HT154 commented on GitHub (Nov 2, 2024):

Is there a reason why -x isn't defined as "set output.value"?

Modules can set output.text directly so output.value may be ignored entirely.

@HT154 commented on GitHub (Nov 2, 2024): > Is there a reason why `-x` isn't defined as "set output.value"? Modules can set `output.text` directly so `output.value` may be ignored entirely.
adam commented 2025-12-30 01:22:38 +01:00
Author
Owner
Copy Link

@odenix commented on GitHub (Nov 3, 2024):

Modules can set output.text directly so output.value may be ignored entirely.

Right, but I think this problem already exists for -f .

The following would at least be consistent and easy to explain:

  • -x overrides output.value and resets output.text
  • -f overrides output.renderer and resets output.text
@odenix commented on GitHub (Nov 3, 2024): > Modules can set output.text directly so output.value may be ignored entirely. Right, but I think this problem already exists for `-f` . The following would at least be consistent and easy to explain: * `-x` overrides `output.value` and resets `output.text` * `-f` overrides `output.renderer` and resets `output.text`
adam commented 2025-12-30 01:22:39 +01:00
Author
Owner
Copy Link

@bioball commented on GitHub (Nov 3, 2024):

Rereading the introduction's concepts, the paragraph on evaluation seems to misrepresent Pkl in this regard:

Evaluating a module produces an in-memory data model that is roughly comparable to a JSON data model. If evaluation completes successfully, the Pkl evaluator converts the data model to an external representation

I think that sentence is a little misleading, but it's actually correct in the strict sense. The conversion can be: Pkl string -> string bytes (in the case of the CLI), or can also be: Pkl object to class/struct/primitive in a host language (in the case of using Pkl as a library).

To your point, the discrepancy between Pkl and Cue/KCL/Dhall is that rendering happens in-language, and you can affect how rendering happens when you author Pkl code.

Is there a reason why -x isn't defined as "set output.value"?

One of the use-cases for the -x flag is for scripting use-cases, for example, pkl eval -x 'package.version'.

If it was defined as set output.value, you'd get something like:

$ pkl eval -x 'package.version' PklProject
"1.0.0"

Instead of:

$ pkl eval -x 'package.version' PklProject
1.0.0

But, I'm more and more thinking that we should provide some way to improve the interaction between -x and -f. Or, introduce a new flag to address this pain point.

@bioball commented on GitHub (Nov 3, 2024): > Rereading the introduction's [concepts](https://pkl-lang.org/main/current/introduction/concepts.html), the paragraph on [evaluation](https://pkl-lang.org/main/current/introduction/concepts.html#evaluation) seems to misrepresent Pkl in this regard: > > Evaluating a module produces an in-memory _data model_ that is roughly comparable to a JSON data model. If evaluation completes successfully, the Pkl evaluator converts the data model to an external representation I think that sentence is a little misleading, but it's actually correct in the strict sense. The conversion can be: Pkl string -> string bytes (in the case of the CLI), or can also be: Pkl object to class/struct/primitive in a host language (in the case of using Pkl as a library). To your point, the discrepancy between Pkl and Cue/KCL/Dhall is that rendering happens _in-language_, and you can affect how rendering happens when you author Pkl code. > Is there a reason why -x isn't defined as "set output.value"? One of the use-cases for the `-x` flag is for scripting use-cases, for example, `pkl eval -x 'package.version'`. If it was defined as `set output.value`, you'd get something like: ``` $ pkl eval -x 'package.version' PklProject "1.0.0" ``` Instead of: ``` $ pkl eval -x 'package.version' PklProject 1.0.0 ``` But, I'm more and more thinking that we should provide some way to improve the interaction between `-x` and `-f`. Or, introduce a new flag to address this pain point.
adam commented 2025-12-30 01:22:39 +01:00
Author
Owner
Copy Link

@ThinkChaos commented on GitHub (Jan 17, 2025):

Posting here so it's more visible, but the workaround was given in #752: -x 'module.output.renderer.renderValue(<expr>).

FWIW I hit this while evaluating Pkl and it seems like unfortunate behavior to me.
If module.output.render is set correctly, why is it ignored? (I get that -x sets it too, it's rhetorical)
I think changing it so -x sets module.renderer instead would make it more intuitive.

@ThinkChaos commented on GitHub (Jan 17, 2025): Posting here so it's more visible, but the workaround was given in #752: `-x 'module.output.renderer.renderValue(<expr>)`. FWIW I hit this while evaluating Pkl and it seems like unfortunate behavior to me. If `module.output.render` is set correctly, why is it ignored? (I get that `-x` sets it too, it's rhetorical) I think changing it so `-x` sets `module.renderer` instead would make it more intuitive.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
duplicate
enhancement
good first issue
help wanted
pull-request
Mirrored from GitHub Pull Request
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/pkl#241
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?