traxys/tree-sitter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(lib): improve documentation on ts_tree_get_changed_ranges and ts_query_cursor_set_{byte,point}_range

Browse source
This commit is contained in:
Amaan Qureshi 2025-01-12 13:44:23 -05:00
parent 3414bbd48e
commit f941277a9d
2 changed files with 28 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

6
lib/binding_rust/bindings.rs
View file

@ -309,7 +309,7 @@ extern "C" {
pub fn ts_tree_edit(self_: *mut TSTree, edit: *const TSInputEdit);
}
extern "C" {
#[doc = " Compare an old edited syntax tree to a new syntax tree representing the same\n document, returning an array of ranges whose syntactic structure has changed.\n\n For this to work correctly, the old syntax tree must have been edited such\n that its ranges match up to the new tree. Generally, you'll want to call\n this function right after calling one of the [`ts_parser_parse`] functions.\n You need to pass the old tree that was passed to parse, as well as the new\n tree that was returned from that function.\n\n The returned array is allocated using `malloc` and the caller is responsible\n for freeing it using `free`. The length of the array will be written to the\n given `length` pointer."]
#[doc = " Compare an old edited syntax tree to a new syntax tree representing the same\n document, returning an array of ranges whose syntactic structure has changed.\n\n For this to work correctly, the old syntax tree must have been edited such\n that its ranges match up to the new tree. Generally, you'll want to call\n this function right after calling one of the [`ts_parser_parse`] functions.\n You need to pass the old tree that was passed to parse, as well as the new\n tree that was returned from that function.\n\n The returned ranges indicate areas where the hierarchical structure of syntax\n nodes (from root to leaf) has changed between the old and new trees. Characters\n outside these ranges have identical ancestor nodes in both trees.\n\n Note that the returned ranges may be slightly larger than the exact changed areas,\n but Tree-sitter attempts to make them as small as possible.\n\n The returned array is allocated using `malloc` and the caller is responsible\n for freeing it using `free`. The length of the array will be written to the\n given `length` pointer."]
pub fn ts_tree_get_changed_ranges(
old_tree: *const TSTree,
new_tree: *const TSTree,
@ -708,7 +708,7 @@ extern "C" {
pub fn ts_query_cursor_timeout_micros(self_: *const TSQueryCursor) -> u64;
}
extern "C" {
#[doc = " Set the range of bytes in which the query will be executed.\n\n This will return `false` if the start byte is greater than the end byte, otherwise\n it will return `true`."]
#[doc = " Set the range of bytes in which the query will be executed.\n\n The query cursor will return matches that intersect with the given point range.\n This means that a match may be returned even if some of its captures fall\n outside the specified range, as long as at least part of the match\n overlaps with the range.\n\n For example, if a query pattern matches a node that spans a larger area\n than the specified range, but part of that node intersects with the range,\n the entire match will be returned.\n\n This will return `false` if the start byte is greater than the end byte, otherwise\n it will return `true`."]
pub fn ts_query_cursor_set_byte_range(
self_: *mut TSQueryCursor,
start_byte: u32,
@ -716,7 +716,7 @@ extern "C" {
) -> bool;
}
extern "C" {
#[doc = " Set the range of (row, column) positions in which the query will be executed.\n\n This will return `false` if the start point is greater than the end point, otherwise\n it will return `true`."]
#[doc = " Set the range of (row, column) positions in which the query will be executed.\n\n The query cursor will return matches that intersect with the given point range.\n This means that a match may be returned even if some of its captures fall\n outside the specified range, as long as at least part of the match\n overlaps with the range.\n\n For example, if a query pattern matches a node that spans a larger area\n than the specified range, but part of that node intersects with the range,\n the entire match will be returned.\n\n This will return `false` if the start point is greater than the end point, otherwise\n it will return `true`."]
pub fn ts_query_cursor_set_point_range(
self_: *mut TSQueryCursor,
start_point: TSPoint,

25
lib/include/tree_sitter/api.h
View file

@ -477,6 +477,13 @@ void ts_tree_edit(TSTree *self, const TSInputEdit *edit);
* You need to pass the old tree that was passed to parse, as well as the new
* tree that was returned from that function.
*
* The returned ranges indicate areas where the hierarchical structure of syntax
* nodes (from root to leaf) has changed between the old and new trees. Characters
* outside these ranges have identical ancestor nodes in both trees.
*
* Note that the returned ranges may be slightly larger than the exact changed areas,
* but Tree-sitter attempts to make them as small as possible.
*
* The returned array is allocated using `malloc` and the caller is responsible
* for freeing it using `free`. The length of the array will be written to the
* given `length` pointer.
@ -1102,6 +1109,15 @@ uint64_t ts_query_cursor_timeout_micros(const TSQueryCursor *self);
/**
* Set the range of bytes in which the query will be executed.
*
* The query cursor will return matches that intersect with the given point range.
* This means that a match may be returned even if some of its captures fall
* outside the specified range, as long as at least part of the match
* overlaps with the range.
*
* For example, if a query pattern matches a node that spans a larger area
* than the specified range, but part of that node intersects with the range,
* the entire match will be returned.
*
* This will return `false` if the start byte is greater than the end byte, otherwise
* it will return `true`.
*/
@ -1110,6 +1126,15 @@ bool ts_query_cursor_set_byte_range(TSQueryCursor *self, uint32_t start_byte, ui
/**
* Set the range of (row, column) positions in which the query will be executed.
*
* The query cursor will return matches that intersect with the given point range.
* This means that a match may be returned even if some of its captures fall
* outside the specified range, as long as at least part of the match
* overlaps with the range.
*
* For example, if a query pattern matches a node that spans a larger area
* than the specified range, but part of that node intersects with the range,
* the entire match will be returned.
*
* This will return `false` if the start point is greater than the end point, otherwise
* it will return `true`.
*/