From 7cbcb4ed1dce2f8a6938a66fd66f8d5608e6798b Mon Sep 17 00:00:00 2001
From: Wang Rongfei <xrowii@outlook.com>
Date: Thu, 12 Oct 2023 02:57:21 +0800
Subject: [PATCH] doc(query): add docs for queries, cursors, matches and
 captures

---
 config.ld             |  4 ++++
 ldoc/Query.lua        | 23 ++++++++++++++++++++++
 ldoc/QueryCapture.lua | 34 ++++++++++++++++++++++++++++++++
 ldoc/QueryCursor.lua  | 45 +++++++++++++++++++++++++++++++++++++++++++
 ldoc/QueryMatch.lua   | 32 ++++++++++++++++++++++++++++++
 5 files changed, 138 insertions(+)
 create mode 100644 ldoc/Query.lua
 create mode 100644 ldoc/QueryCapture.lua
 create mode 100644 ldoc/QueryCursor.lua
 create mode 100644 ldoc/QueryMatch.lua

diff --git a/config.ld b/config.ld
index 02c786f..9775e78 100644
--- a/config.ld
+++ b/config.ld
@@ -4,6 +4,10 @@ file = {
 	'ldoc/Node.lua',
 	'ldoc/Parser.lua',
 	'ldoc/Point.lua',
+	'ldoc/Query.lua',
+	'ldoc/QueryCapture.lua',
+	'ldoc/QueryCursor.lua',
+	'ldoc/QueryMatch.lua',
 	'ldoc/Range.lua',
 	'ldoc/RangeArray.lua',
 	'ldoc/Tree.lua',
diff --git a/ldoc/Query.lua b/ldoc/Query.lua
new file mode 100644
index 0000000..37bc154
--- /dev/null
+++ b/ldoc/Query.lua
@@ -0,0 +1,23 @@
+---
+-- A query that can be ran on `Node`s of a given `Language`.
+-- Analogous to `TSQuery`.
+-- @classmod Query
+-- @pragma nostrip
+
+---
+-- Functions
+-- @section Functions
+
+
+---
+-- Create a new query for a given `Language` from a source `string`.
+-- @tparam Language lang
+-- @tparam string source
+-- @treturn Query
+-- @raise Invalid pattern in the source.
+function Query.new(lang, source) end
+
+---
+-- Methods
+-- @section Methods
+
diff --git a/ldoc/QueryCapture.lua b/ldoc/QueryCapture.lua
new file mode 100644
index 0000000..8cf8232
--- /dev/null
+++ b/ldoc/QueryCapture.lua
@@ -0,0 +1,34 @@
+---
+-- A capture of a `Query`.
+-- Analogous to `TSQueryCapture`.
+-- @classmod QueryCapture
+-- @pragma nostrip
+
+---
+-- Methods
+-- @section Methods
+
+---
+-- Get the `Node` of the capture.
+-- @treturn Node
+function QueryCapture:node() end
+
+---
+-- Get the index of the capture.
+-- @treturn integer
+function QueryCapture:index() end
+
+---
+-- Get the `QueryMatch` the capture belongs to.
+-- @treturn QueryMatch
+function QueryCapture:match() end
+
+---
+-- Get the `Query` the capture belongs to.
+-- @treturn Query
+function QueryCapture:query() end
+
+---
+-- Get the name of the capture.
+-- @treturn Node
+function QueryCapture:name() end
diff --git a/ldoc/QueryCursor.lua b/ldoc/QueryCursor.lua
new file mode 100644
index 0000000..48ef2fc
--- /dev/null
+++ b/ldoc/QueryCursor.lua
@@ -0,0 +1,45 @@
+---
+-- A cursor for executing a given `Query`.
+-- Analogous to `TSQueryCursor`.
+-- @classmod QueryCursor
+-- @pragma nostrip
+
+---
+-- Functions
+-- @section Functions
+
+---
+-- Create a new cursor for executing a given `Query` on a given `Node`.
+-- @tparam Query query
+-- @tparam Node node
+-- @treturn QueryCursor
+function QueryCursor.new(query, node) end
+
+---
+-- Methods
+-- @section Methods
+
+---
+-- Get the `Query` the cursor is executing.
+-- @treturn Query
+function QueryCursor:query() end
+
+---
+-- Set the range of `Point`s in which the `Query` will be executed.
+-- @tparam Point start_point
+-- @tparam Point end_point
+function QueryCursor:set_point_range(start_point, end_point) end
+
+---
+-- Advance to and get the next match.
+--
+-- This method may return `nil` if there are no more matches.
+-- @treturn QueryMatch|nil
+function QueryCursor:next_match() end
+
+---
+-- Advance to and get the next capture.
+--
+-- This method may return `nil` if there are no more captures.
+-- @treturn QueryCapture|nil
+function QueryCursor:next_capture() end
diff --git a/ldoc/QueryMatch.lua b/ldoc/QueryMatch.lua
new file mode 100644
index 0000000..7312804
--- /dev/null
+++ b/ldoc/QueryMatch.lua
@@ -0,0 +1,32 @@
+---
+-- A match of a `Query`.
+-- Analogous to `TSQueryMatch`.
+-- @classmod QueryMatch
+-- @pragma nostrip
+
+---
+-- Methods
+-- @section Methods
+
+---
+-- Get the pattern index of the match.
+-- @treturn integer
+function QueryMatch:pattern_index() end
+
+---
+-- Get the number of `QueryCapture`s in the match.
+-- @treturn integer
+function QueryCursor:capture_count() end
+
+---
+-- Get the `QueryCapture` at a given index.
+-- @tparam integer index
+-- @treturn QueryCapture
+-- @raise Indexing a negative index.  
+-- Indexing beyond last element.
+function QueryCursor:capture_at(index) end
+
+---
+-- Get the `Query` to which the match belongs.
+-- @treturn Query
+function QueryMatch:query() end