Add Node::unparse and tweak the cursor creation API

[Xanewok]

Closes #583
Ref #628 for the modified cursor/offset API

Changes are best reviewed commit-by-commit.

[changeset-bot]

🦋 Changeset detected

Latest commit: 1007589

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@nomicfoundation/slang	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[OmarTawfik]

Left a few questions.

[OmarTawfik]

Possibly unrelated to this PR, but asking since it is addressing API feedback:

For as_rule_matching(...) .. I wonder how is that different from .as_rule().filter(...), given it is the same characters/effort to type?

Are we duplicating Rust std:: methods? what new scenarios does it enable?

Same question for as_token_matching().

[Xanewok]

You're right that this is merely a convenience/"combined" method.

This API is from when, as I understand it, we wanted to have parity in the Rust/TS API. Since we decided against that recently, we can start thinking whether we want it or not on Rust side (AIUI it's more performant to keep that on TS side).

My first reaction was the same as yours, i.e as_{rule,token}_matching is probably redundant on the Rust side, now that we have introduced convenience as_{rule,token} at some point.

I do see some point in the convenience _with_kind functions, as as_{rule,token}_with_kind reads and formats better than the as_{rule,token}().filter(|node| &[some,kinds].contains(node.kind)) chain. WDYT?

[AntonyBlakey]

I like these semantically rich apis that match common use cases. I'm also happy to have them in a separate trait, such as RichXXXAPI or EnhancedXXX etc, simply for the sake of having a 'core' minimal API and then a layered convenience API.

[AntonyBlakey]

Specifically because it reads well in the code to express clearly the higher-level intent. And I like descriptive precise names, with no concern at all about the length of names.

[AntonyBlakey]

For as_rule_matching(...) .. I wonder how is that different from .as_rule().filter(...), given it is the same characters/effort to type?

Same to type, but less to understand.

[OmarTawfik]

I do see some point in the convenience _with_kind functions, as as_{rule,token}_with_kind reads and formats better than the as_{rule,token}().filter(|node| &[some,kinds].contains(node.kind)) chain. WDYT?

Same to type, but less to understand.

@Xanewok @AntonyBlakey

with_kind() makes sense. The alternative doesn't have a good Rust standard library alternative, and I imagine it is a common use case, enough to have a helper for.

But on the other hand, as_rule_matching() here is longer than the Rust standard library alternative (.as_rule().filter()), which most Rust users are already familiar with, and is used extensively in all projects, so I feel we are only replacing the language built-in API with a longer/less idiomatic one, that is not really easier to use (both accept the same kind of callback).

[Xanewok]

Agree, I'm not so sure about the _matching variant, especially since as(...).filter(...) does the same and filter is bread-and-butter idiomatic Rust.

I can understand the readability context a bit but then again, if it's not using the std impls then that might imply something non-standard, actually.

I'm fine either way, to be honest!

[OmarTawfik]

Left one suggestion about removing as_XXX_matching(), but otherwise, LGTM!

[Xanewok]

I think it makes sense to drop the individual as_*matching() for the tokens/rules, as as_*() followed by filter() should be equally readable for a Rust reader and this means there are less surprises (we're using std combinators) comparing to, let's say, Cursor's find_*_matching that does not consume the first item, unlike std::iter::Iterator::find.