Make it clear in cursor-related doc that they are scoped to the starting node

[ubolonton]

There seems to be a bug with ts_tree_cursor_goto_parent when the cursor is initialized on a non-root node.

I got it in the Emacs Lisp binding, but can reproduce it with the NodeJS binding (0.16.0):

const Parser = require('tree-sitter');
const Rust = require('tree-sitter-rust');

parser = new Parser();
parser.setLanguage(Rust);

tree = parser.parse("fn foo() {}");

> c0 = tree.rootNode.walk(); c0.gotoFirstChild();
true
>
> c1 = c0.currentNode.walk(); c0.currentNode === c1.currentNode;
true
>
> c0.gotoParent();
true
>
> c1.gotoParent();
false
>
> c0.currentNode.type;
'source_file'
>
> c1.currentNode.type;
'function_item'
>

[maxbrunsfeld]

Yeah, this is actually the expected behavior. The cursor only "walks" within the node that it started from, and it can't go outside of it. This is possible to change, but it would add some complexity. Maybe it's worth it though, because this has confused people before.

[ubolonton]

The cursor only "walks" within the node that it started from, and it can't go outside of it.

Oh, it makes sense now. Maybe we can update the doc to clear up the confusion?

My current use case is getting the "path" from the root node to a given node, to restore cursor position after code formatting: emacs-tree-sitter/elisp-tree-sitter#28. Would ts_node_parent be more suitable, at least for now?

[maxbrunsfeld]

I think you could use TreeCursor::goto_first_child_for_byte to walk the cursor to the leaf node at a given byte offset (based on the cursor position) keeping track of the steps along the way.

But ts_node_parent is also fine. There is some caching done in that method to make sure it performs well in the common case of walking repeatedly up the tree.

[ubolonton]

Thanks!

[Enter-tainer]

I've encountered the same issue yesterday. Maybe we should make it clear in the document to end the confusion.

See #1485