clarify cursor API initial offsets

[OmarTawfik]

functions vs getters

I also suggest also not using getters, but functions, with a prefix like create_ instead of get_, since cursors returned should be persisted long-term and reused. Additionally, it is meant to be mutated, so it is no longer a property of the node that creates it. And last, that prevents bugs because of patterns like below, where users can wrongly expect the cursor to be persisted on the node:

root_node.cursor.next();
root_node.cursor.next();

• Fixed in public API overhaul #647

initial cursor offset

currently calling node.cursor would create one at offset ZERO. This is correct for the root node, but problematic for any sub-nodes, and can cause user confusion. Let's replace this API with a few distinct methods:

• node.create_cursor_at(offset)
• parse_result.create_root_cursor() that would call self.root_node.create_cursor_at(ZERO) for convenience.

This way, the user is informed with the expected offset during creation.

• Fixed in public API overhaul #647

fast cursors (no offsets)

There are use cases that need to analyze the CST without tracking offsets. This means they shouldn't pay the cost of maintaining these numbers as the cursor is running. One idea is to provide another node.create_*() API that creates a fast Cursor that can implement all same API, but won't track or provide offset values.

However, this is a nice-to-have feature, and we can put it aside for later if it will result in two divergent implementations.

[Xanewok]

We'd have to think a bit more how we could expose different cursors as the different logic would have to impact the Path(Rule)Node types used internally by the cursor. I've separated #691 as this is a nice-to-have at the moment and the core issue outlined here has been fixed in #647 and #666.