[NU-1836] Add casting and conversions docs

[lukasz-bigorajski]

Describe your changes

Checklist before merge

• Related issue ID is placed at the beginning of PR title in [brackets] (can be GH issue or Nu Jira issue)
• Code is cleaned from temporary changes and commented out lines
• Parts of the code that are not easy to understand are documented in the code
• Changes are covered by automated tests
• Showcase in dev-application.conf added to demonstrate the feature
• Documentation added or updated
• Added entry in Changelog.md describing the change from the perspective of a public distribution user
• Added MigrationGuide.md entry in the appropriate subcategory if introducing a breaking change
• Verify that PR will be squashed during merge

Summary by CodeRabbit

• Documentation
  • Enhanced clarity and detail in the SpEL (Spring Expression Language) documentation.
  • Added new sections on explicit conversions and a matrix for data type conversions.
  • Updated terminology from "cast" to "convert" for consistency.
  • Improved document structure and formatting for better readability.

[ZbyszekMM]

The behavior of functions prefixed with "is" is a surprise to me. Prefix "canBe" would fit better. Under normal circumstances I would not bother reading docs, because the name of the function offers a whole explanation.

Unfortunately, this is an incorrect explanation.

Now, I wonder whether this is an important difference. Whether something is "truly" a "Class", or just is convertable to the class. May be we do not need this distinction, I do not know. But I was really surprised.

[lukasz-bigorajski]

Changed to 'canBe'

[ZbyszekMM]

in built-in --> as built-in (??)

in utility classes - in which utility classes? #CONV?

[lukasz-bigorajski]

Done

[ZbyszekMM]

The is, to and toOrNull functions are slightly different

What are they different from? More and more I see, that somewhere I missed an important point.

[lukasz-bigorajski]

Done

[ZbyszekMM]

If the cast fails and there is a defined conversion ...

This is even more tricky for me, I simply do not understand. I am not sure whether the subtle differences you describe here come from the difference between casting (explicit) and conversion (often implicit, hidden); however you mention conversion functions, so I am lost.

[lukasz-bigorajski]

I rephrased it a little. I hope it's better or if it's not we will try to fix it.

[arkadius]

@coderabbitai review please

[coderabbitai]

@arkadius: I will review the changes.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Walkthrough

The modifications to Spel.md focus on enhancing the clarity and detail of the Spring Expression Language (SpEL) documentation. Key updates include the addition of explicit conversion functions, an expanded section on type conversions with a matrix illustrating data type compatibility, and improved terminology. The document structure has been refined for better readability, with clearer headings and organized sections, providing a more comprehensive understanding of SpEL syntax and conversion mechanisms.

Changes

File Path	Change Summary
docs/scenarios_authoring/Spel.md	- Added section on explicit conversions with built-in functions. - Included a matrix for data type conversions. - Updated terminology from "cast" to "convert". - Clarified behavior of implicit conversions. - Improved document formatting and structure for readability.

Poem

In the land of SpEL, where data types play,
Conversions now dance in a clearer way.
With matrices bright and functions so neat,
Understanding grows, oh what a treat!
So hop with delight, let knowledge abound,
In the world of expressions, new treasures are found! 🐇✨

---

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 0

🧹 Outside diff range and nitpick comments (3)

docs/scenarios_authoring/Spel.md (3)

267-267: Add a comma for better readability

Add a comma after "Unknown data type" to improve sentence structure.

-Every unknown accessed field/element will produce `Unknown` data type which can be further navigated or [converted](#type-conversions) to a desired type.
+Every unknown accessed field/element will produce `Unknown` data type, which can be further navigated or [converted](#type-conversions) to a desired type.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~267-~267: Possible missing comma found.
Context: ...eld/element will produce Unknown data type which can be further navigated or [conv...

(AI_HYDRA_LEO_MISSING_COMMA)

---

273-294: Consider adding usage examples

The explanation of conversion functions is clear, but adding practical examples would help users better understand when and how to use each type of function (canBe/to/toOrNull).

Consider adding examples like:

Examples:
```python
canBeDouble("123")     # returns true
toDouble("123")        # returns 123.0
toDoubleOrNull("abc")  # returns null

---

`345-345`: **Improve sentence structure**

Revise the phrase for better readability.

```diff
-Some conversions example:
+Some examples of conversions:

🧰 Tools

🪛 LanguageTool

[uncategorized] ~345-~345: Possible missing preposition found.
Context: ...to the desired type). Some conversions example: | Input value ...

(AI_HYDRA_LEO_MISSING_IN)

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL

📥 Commits

Reviewing files that changed from the base of the PR and between 89ed14a and 39e2788.

📒 Files selected for processing (1)

• docs/scenarios_authoring/Spel.md (2 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/scenarios_authoring/Spel.md

[uncategorized] ~267-~267: Possible missing comma found.
Context: ...eld/element will produce Unknown data type which can be further navigated or [conv...

(AI_HYDRA_LEO_MISSING_COMMA)

---

[uncategorized] ~345-~345: Possible missing preposition found.
Context: ...to the desired type). Some conversions example: | Input value ...

(AI_HYDRA_LEO_MISSING_IN)

🔇 Additional comments (2)

docs/scenarios_authoring/Spel.md (2)

271-272: LGTM!

The introduction clearly sets up the distinction between implicit and explicit conversions.

---

295-336: LGTM!

The conversion matrix is comprehensive and well-formatted, using emojis effectively to visualize conversion possibilities. The legend clearly explains the symbols used.

[coderabbitai]

Actionable comments posted: 0

🧹 Outside diff range and nitpick comments (3)

docs/scenarios_authoring/Spel.md (3)

271-272: Improve sentence structure for better readability

Consider revising the sentence structure:

-It is possible to cast or convert from a type to another type and this can be done by implicit and explicit conversion.
+It is possible to cast or convert from one type to another, and this can be done through implicit and explicit conversion.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~271-~271: Possible missing comma found.
Context: ... cast or convert from a type to another type and this can be done by implicit and ex...

(AI_HYDRA_LEO_MISSING_COMMA)

---

273-296: Consider adding a comparative example

The documentation clearly explains the different function variants. Consider adding a small example that demonstrates the behavior difference between canBe, to, and toOrNull using the same input:

Example:
| Expression              | Result                      |
|------------------------|----------------------------- |
| `"abc".canBeDouble`    | false                       |
| `"abc".toDouble`       | throws exception            |
| `"abc".toDoubleOrNull` | null                        |

---

313-328: Consider reorganizing the conversion matrix

Based on the previous review comment from arkadius, consider swapping the rows and columns in the matrix. This would make it more intuitive to read as "Can I cast to " by finding the source type in the row and target type in the column. This matches the convention used in other documentation, such as Flink's type system documentation.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL

📥 Commits

Reviewing files that changed from the base of the PR and between 39e2788 and 3c2de37.

📒 Files selected for processing (1)

• docs/scenarios_authoring/Spel.md (2 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/scenarios_authoring/Spel.md

[uncategorized] ~271-~271: Possible missing comma found.
Context: ... cast or convert from a type to another type and this can be done by implicit and ex...

(AI_HYDRA_LEO_MISSING_COMMA)

🔇 Additional comments (3)

docs/scenarios_authoring/Spel.md (3)

267-267: LGTM!

The addition provides valuable information about handling unknown field types.

---

297-309: LGTM!

The examples effectively demonstrate various conversion scenarios, including success cases, null handling, and runtime exceptions.

---

Line range hint 334-371: LGTM!

The documentation of utility classes and implicit conversions is clear, accurate, and well-supported with examples.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~271-~271: Possible missing comma found.
Context: ... cast or convert from a type to another type and this can be done by implicit and ex...

(AI_HYDRA_LEO_MISSING_COMMA)

🪛 Markdownlint

264-264: Expected: dash; Actual: asterisk
Unordered list style

(MD004, ul-style)

---

265-265: Expected: dash; Actual: asterisk
Unordered list style

(MD004, ul-style)