Tweak query interface

* Rename TSQueryContext -> TSQueryCursor
* Remove the permanent association between the cursor and its query. The 
cursor can now be used again for a different query.

lib/binding_rust/bindings.rs

@@ -26,7 +26,7 @@ pub struct TSQuery {
 }
 #[repr(C)]
 #[derive(Debug, Copy, Clone)]
-pub struct TSQueryContext {
+pub struct TSQueryCursor {
     _unused: [u8; 0],
 }
 pub const TSInputEncoding_TSInputEncodingUTF8: TSInputEncoding = 0;
@@ -604,56 +604,52 @@ extern "C" {
     ) -> ::std::os::raw::c_int;
 }
 extern "C" {
-    #[doc = " Create a new context for executing a given query."]
+    #[doc = " Create a new cursor for executing a given query."]
     #[doc = ""]
-    #[doc = " The context stores the state that is needed to iteratively search"]
-    #[doc = " for matches. To use the query context:"]
-    #[doc = " 1. First call `ts_query_context_exec` to start running the query"]
-    #[doc = "    on a particular syntax node."]
-    #[doc = " 2. Then repeatedly call `ts_query_context_next` to iterate over"]
-    #[doc = "    the matches."]
-    #[doc = " 3. After each successful call to `ts_query_context_next`, you can call"]
-    #[doc = "    `ts_query_context_matched_pattern_index` to determine which pattern"]
-    #[doc = "     matched. You can also call `ts_query_context_matched_captures` to"]
-    #[doc = "     determine which nodes were captured by which capture names."]
+    #[doc = " The cursor stores the state that is needed to iteratively search"]
+    #[doc = " for matches. To use the query cursor:"]
+    #[doc = " 1. First call `ts_query_cursor_exec` to start running a given query on"]
+    #[doc = "a given syntax node."]
+    #[doc = " 2. Then repeatedly call `ts_query_cursor_next` to iterate over the matches."]
+    #[doc = "    This will return `false` when there are no more matches left."]
+    #[doc = " 3. After each successful call to `ts_query_cursor_next`, you can call"]
+    #[doc = "    `ts_query_cursor_matched_pattern_index` to determine which pattern"]
+    #[doc = "     matched. You can also call `ts_query_cursor_matched_captures` to"]
+    #[doc = "     determine which nodes were captured, and by which capture names."]
     #[doc = ""]
     #[doc = " If you don\'t care about finding all of the matches, you can stop calling"]
-    #[doc = " `ts_query_context_next` at any point. And you can start executing the"]
-    #[doc = "  query against a different node by calling `ts_query_context_exec` again."]
-    pub fn ts_query_context_new(arg1: *const TSQuery) -> *mut TSQueryContext;
+    #[doc = " `ts_query_cursor_next` at any point. And you can start executing another"]
+    #[doc = "  query on another node by calling `ts_query_cursor_exec` again."]
+    pub fn ts_query_cursor_new() -> *mut TSQueryCursor;
 }
 extern "C" {
-    #[doc = " Delete a query context, freeing all of the memory that it used."]
-    pub fn ts_query_context_delete(arg1: *mut TSQueryContext);
+    #[doc = " Delete a query cursor, freeing all of the memory that it used."]
+    pub fn ts_query_cursor_delete(arg1: *mut TSQueryCursor);
 }
 extern "C" {
-    #[doc = " Start running a query on a given node."]
-    pub fn ts_query_context_exec(arg1: *mut TSQueryContext, arg2: TSNode);
+    #[doc = " Start running a given query on a given node."]
+    pub fn ts_query_cursor_exec(arg1: *mut TSQueryCursor, arg2: *const TSQuery, arg3: TSNode);
 }
 extern "C" {
     #[doc = " Set the range of bytes or (row, column) positions in which the query"]
     #[doc = " will be executed."]
-    pub fn ts_query_context_set_byte_range(arg1: *mut TSQueryContext, arg2: u32, arg3: u32);
+    pub fn ts_query_cursor_set_byte_range(arg1: *mut TSQueryCursor, arg2: u32, arg3: u32);
 }
 extern "C" {
-    pub fn ts_query_context_set_point_range(
-        arg1: *mut TSQueryContext,
-        arg2: TSPoint,
-        arg3: TSPoint,
-    );
+    pub fn ts_query_cursor_set_point_range(arg1: *mut TSQueryCursor, arg2: TSPoint, arg3: TSPoint);
 }
 extern "C" {
     #[doc = " Advance to the next match of the currently running query."]
-    pub fn ts_query_context_next(arg1: *mut TSQueryContext) -> bool;
+    pub fn ts_query_cursor_next(arg1: *mut TSQueryCursor) -> bool;
 }
 extern "C" {
     #[doc = " Check which pattern matched."]
-    pub fn ts_query_context_matched_pattern_index(arg1: *const TSQueryContext) -> u32;
+    pub fn ts_query_cursor_matched_pattern_index(arg1: *const TSQueryCursor) -> u32;
 }
 extern "C" {
     #[doc = " Check which pattern matched."]
-    pub fn ts_query_context_matched_captures(
-        arg1: *const TSQueryContext,
+    pub fn ts_query_cursor_matched_captures(
+        arg1: *const TSQueryCursor,
         arg2: *mut u32,
     ) -> *const TSQueryCapture;
 }

lib/binding_rust/lib.rs

@@ -142,9 +142,9 @@ pub struct Query {
     capture_names: Vec<String>,
 }
 
-pub struct QueryContext<'a>(*mut ffi::TSQueryContext, PhantomData<&'a ()>);
+pub struct QueryCursor(*mut ffi::TSQueryCursor);
 
-pub struct QueryMatch<'a>(&'a QueryContext<'a>);
+pub struct QueryMatch<'a>(*mut ffi::TSQueryCursor, PhantomData<&'a ()>);
 
 #[derive(Debug, PartialEq, Eq)]
 pub enum QueryError<'a> {
@@ -989,22 +989,21 @@ impl Query {
     pub fn capture_names(&self) -> &[String] {
         &self.capture_names
     }
-
-    pub fn context(&self) -> QueryContext {
-        let context = unsafe { ffi::ts_query_context_new(self.ptr) };
-        QueryContext(context, PhantomData)
-    }
 }
 
-impl<'a> QueryContext<'a> {
-    pub fn exec(&'a self, node: Node<'a>) -> impl Iterator<Item = QueryMatch<'a>> + 'a {
+impl QueryCursor {
+    pub fn new() -> Self {
+        QueryCursor(unsafe { ffi::ts_query_cursor_new() })
+    }
+
+    pub fn exec<'a>(&'a mut self, query: &'a Query, node: Node<'a>) -> impl Iterator<Item = QueryMatch<'a>> + 'a {
         unsafe {
-            ffi::ts_query_context_exec(self.0, node.0);
+            ffi::ts_query_cursor_exec(self.0, query.ptr, node.0);
         }
         std::iter::from_fn(move || -> Option<QueryMatch<'a>> {
             unsafe {
-                if ffi::ts_query_context_next(self.0) {
-                    Some(QueryMatch(self))
+                if ffi::ts_query_cursor_next(self.0) {
+                    Some(QueryMatch(self.0, PhantomData))
                 } else {
                     None
                 }
@@ -1014,14 +1013,14 @@ impl<'a> QueryContext<'a> {
 
     pub fn set_byte_range(&mut self, start: usize, end: usize) -> &mut Self {
         unsafe {
-            ffi::ts_query_context_set_byte_range(self.0, start as u32, end as u32);
+            ffi::ts_query_cursor_set_byte_range(self.0, start as u32, end as u32);
         }
         self
     }
 
     pub fn set_point_range(&mut self, start: Point, end: Point) -> &mut Self {
         unsafe {
-            ffi::ts_query_context_set_point_range(self.0, start.into(), end.into());
+            ffi::ts_query_cursor_set_point_range(self.0, start.into(), end.into());
         }
         self
     }
@@ -1029,14 +1028,14 @@ impl<'a> QueryContext<'a> {
 
 impl<'a> QueryMatch<'a> {
     pub fn pattern_index(&self) -> usize {
-        unsafe { ffi::ts_query_context_matched_pattern_index((self.0).0) as usize }
+        unsafe { ffi::ts_query_cursor_matched_pattern_index(self.0) as usize }
     }
 
     pub fn captures(&self) -> impl ExactSizeIterator<Item = (usize, Node)> {
         unsafe {
             let mut capture_count = 0u32;
             let captures =
-                ffi::ts_query_context_matched_captures((self.0).0, &mut capture_count as *mut u32);
+                ffi::ts_query_cursor_matched_captures(self.0, &mut capture_count as *mut u32);
             let captures = slice::from_raw_parts(captures, capture_count as usize);
             captures
                 .iter()
@@ -1057,9 +1056,9 @@ impl Drop for Query {
     }
 }
 
-impl<'a> Drop for QueryContext<'a> {
+impl Drop for QueryCursor {
     fn drop(&mut self) {
-        unsafe { ffi::ts_query_context_delete(self.0) }
+        unsafe { ffi::ts_query_cursor_delete(self.0) }
     }
 }