docs: explain Risor vs Starlark callable-return divergence#140
Merged
Conversation
Risor errors when a script's final value is a callable
("function object returned from script: ..."); Starlark auto-invokes a
trailing callable with no args. The two behaviors are intentional and
reflect each host language's idiom:
- Risor is expression-oriented (top-level expressions are normal), so a
trailing function value is a legitimate result; auto-call would guess
at arity.
- Starlark has no top-level expression statement, so scripts end in a
`def` block by convention; auto-call provides the "run my main()"
ergonomics the language otherwise lacks.
Adds a new "Script Return Value Handling" section to engines/README.md
and brief rationale comments at the two divergence sites. No behavior
change.
https://claude.ai/code/session_01C61VEAmjxSnX5Xhbab8NvL
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR documents the intentional divergence between the Risor and Starlark engines when a script’s “final value” is callable, and adds small in-code pointers to the new documentation. No runtime behavior is changed.
Changes:
- Added an
engines/README.mdsection describing per-engine script return value handling (incl. rationale for divergence). - Added short comments in both evaluators pointing readers to the new documentation section.
- Added an
[Unreleased]changelog entry under Documentation.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| engines/starlark/evaluator/evaluator.go | Adds a comment explaining the intentional Starlark callable auto-invoke behavior and links to the docs. |
| engines/risor/evaluator/evaluator.go | Adds a comment explaining the intentional Risor callable-as-error behavior and links to the docs. |
| engines/README.md | Introduces “Script Return Value Handling” section documenting the divergence and rationale. |
| CHANGELOG.md | Adds an Unreleased Documentation entry for the new docs/comments. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Per Copilot review on #140 — the previous "final assignment's value" phrasing was imprecise. The evaluator actually reads global `_` (the Starlark convention for the anonymous value) and falls back to global `result` when `_` is None. Updated the README section to match the implementation in engines/starlark/evaluator/evaluator.go:127-138. https://claude.ai/code/session_01C61VEAmjxSnX5Xhbab8NvL
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the intentional divergence between Risor and Starlark in how a callable-returning script is handled. No behavior change.
The divergence:
"function object returned from script: ..."defby convention. Auto-call provides "run my main()" ergonomics.Changes:
engines/README.md— new## Script Return Value Handlingsection between## Engine-Specific Data Handlingand## Data Provider Patterns, with one sub-section per engine plus a "Why they differ" coda.engines/risor/evaluator/evaluator.go— brief comment above thecase "function":branch pointing to the README section.engines/starlark/evaluator/evaluator.go— brief comment above thestarlarkLib.Callablebranch with the same pointer.CHANGELOG.md—[Unreleased] > Documentationentry.Existing tests already cover both behaviors:
engines/starlark/evaluator/evaluator_test.go:437-457(the_ = boompattern)engines/risor/evaluator/evaluator_test.go:615-629(thex => x + 1pattern)This closes the "Function-case alignment" backlog item as intentional divergence, documented.
Test plan
go build ./...cleango vet ./...cleango test -count=1 ./engines/risor/evaluator/ ./engines/starlark/evaluator/greenhttps://claude.ai/code/session_01C61VEAmjxSnX5Xhbab8NvL
Generated by Claude Code