feat(query)!: improve implementation

- Implement more methods - Support custom predicates - Add custom QueryError exception
tree-sitter · Aug 22, 2024 · c70d44f · c70d44f
1 parent 722862b
commit c70d44f
Show file tree

Hide file tree

Showing 21 changed files with 1,436 additions and 937 deletions.
diff --git a/.clang-format b/.clang-format
@@ -5,5 +5,6 @@ PointerAlignment: Right
 IndentWidth: 4
 ColumnLimit: 100
 IncludeBlocks: Preserve
-StatementMacros: [PyObject_HEAD, PyObject_VAR_HEAD, _PyObject_HEAD_EXTRA]
+StatementMacros: [PyObject_HEAD]
 BinPackArguments: true
+IndentCaseLabels: true
diff --git a/.editorconfig b/.editorconfig
@@ -12,6 +12,6 @@ indent_size = 2
 [*.rst]
 indent_size = 3
 
-[*.{c,h,py}]
+[*.{c,h,py,pyi}]
 indent_size = 4
 max_line_length = 100
diff --git a/docs/classes/tree_sitter.Language.rst b/docs/classes/tree_sitter.Language.rst
@@ -7,7 +7,6 @@ Language
 
       The argument can now be a `capsule <https://docs.python.org/3/c-api/capsule.html>`_.
 
-
    Methods
    -------
 
@@ -33,7 +32,6 @@ Language
    .. automethod:: __ne__
    .. automethod:: __repr__
 
-
    Attributes
    ----------
 

diff --git a/docs/classes/tree_sitter.LookaheadIterator.rst b/docs/classes/tree_sitter.LookaheadIterator.rst
@@ -2,14 +2,15 @@ LookaheadIterator
 =================
 
 .. autoclass:: tree_sitter.LookaheadIterator
+   :show-inheritance:
 
    Methods
    -------
 
    .. automethod:: iter_names
    .. automethod:: reset_state
 
-   Special methods
+   Special Methods
    ---------------
 
    .. automethod:: __iter__

diff --git a/docs/classes/tree_sitter.Parser.rst b/docs/classes/tree_sitter.Parser.rst
@@ -6,7 +6,6 @@ Parser
    Methods
    -------
 
-
    .. automethod:: parse
 
       .. versionchanged:: 0.23.0

diff --git a/docs/classes/tree_sitter.Point.rst b/docs/classes/tree_sitter.Point.rst
@@ -2,6 +2,7 @@ Point
 =====
 
 .. autoclass:: tree_sitter.Point
+   :show-inheritance:
 
    Attributes
    ----------

diff --git a/docs/classes/tree_sitter.Query.rst b/docs/classes/tree_sitter.Query.rst
@@ -3,8 +3,95 @@ Query
 
 .. autoclass:: tree_sitter.Query
 
+   .. seealso:: `Query Syntax`_
+
+   .. _Query Syntax: https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax
+
+   .. note::
+
+      The following predicates are supported by default:
+
+      * ``#eq?``, ``#not-eq?``, ``#any-eq?``, ``#any-not-eq?``
+      * ``#match?``, ``#not-match?``, ``#any-match?``, ``#any-not-match?``
+      * ``#any-of?``, ``#not-any-of?``
+      * ``#is?``, ``#is-not?``
+      * ``#set!``
+
    Methods
    -------
 
    .. automethod:: captures
+
+      .. important::
+
+         Predicates cannot be used if the tree was parsed from a callback.
+
+      .. versionchanged:: 0.23.0
+
+         Range arguments removed, :class:`predicate <QueryPredicate>` argument added,
+         return type changed to ``dict[str, list[Node]]``.
+   .. automethod:: disable_capture
+
+      .. versionadded:: 0.23.0
+   .. automethod:: disable_pattern
+
+      .. versionadded:: 0.23.0
+   .. automethod:: end_byte_for_pattern
+
+      .. versionadded:: 0.23.0
+   .. automethod:: is_pattern_guaranteed_at_step
+
+      .. versionadded:: 0.23.0
+   .. automethod:: is_pattern_non_local
+
+      .. versionadded:: 0.23.0
+   .. automethod:: is_pattern_rooted
+
+      .. versionadded:: 0.23.0
    .. automethod:: matches
+
+      .. important::
+
+         Predicates cannot be used if the tree was parsed from a callback.
+
+      .. versionchanged:: 0.23.0
+
+         Range arguments removed, :class:`predicate <QueryPredicate>` argument added,
+         return type changed to ``list[tuple[int, dict[str, list[Node]]]]``.
+   .. automethod:: pattern_assertions
+
+      .. versionadded:: 0.23.0
+   .. automethod:: pattern_settings
+
+      .. versionadded:: 0.23.0
+   .. automethod:: set_byte_range
+
+      .. versionadded:: 0.23.0
+   .. automethod:: set_point_range
+
+      .. versionadded:: 0.23.0
+   .. automethod:: start_byte_for_pattern
+
+      .. versionadded:: 0.23.0
+   .. automethod:: set_match_limit
+
+      .. versionadded:: 0.23.0
+   .. automethod:: set_max_start_depth
+
+      .. versionadded:: 0.23.0
+
+   Attributes
+   ----------
+
+   .. autoattribute:: capture_count
+
+      .. versionadded:: 0.23.0
+   .. autoattribute:: did_exceed_match_limit
+
+      .. versionadded:: 0.23.0
+   .. autoattribute:: match_limit
+
+      .. versionadded:: 0.23.0
+   .. autoattribute:: pattern_count
+
+      .. versionadded:: 0.23.0
diff --git a/docs/classes/tree_sitter.QueryError.rst b/docs/classes/tree_sitter.QueryError.rst
@@ -0,0 +1,7 @@
+QueryError
+==========
+
+.. autoclass:: tree_sitter.QueryError
+   :show-inheritance:
+
+   .. versionadded:: 0.23.0
diff --git a/docs/classes/tree_sitter.QueryPredicate.rst b/docs/classes/tree_sitter.QueryPredicate.rst
@@ -0,0 +1,12 @@
+QueryPredicate
+==============
+
+.. autoclass:: tree_sitter.QueryPredicate
+   :show-inheritance:
+
+   .. versionadded:: 0.23.0
+
+   Special Methods
+   ---------------
+
+   .. automethod:: __call__
diff --git a/docs/classes/tree_sitter.TreeCursor.rst b/docs/classes/tree_sitter.TreeCursor.rst
@@ -1,4 +1,4 @@
-TreeCursor
+TreeCursor
 ----------
 
 .. autoclass:: tree_sitter.TreeCursor
@@ -10,19 +10,27 @@
    .. automethod:: goto_descendant
    .. automethod:: goto_first_child
    .. automethod:: goto_first_child_for_byte
+
+      .. versionchanged:: 0.23.0
+
+         Returns the child index instead of a `bool`.
    .. automethod:: goto_first_child_for_point
+
+      .. versionchanged:: 0.23.0
+
+         Returns the child index instead of a `bool`.
    .. automethod:: goto_last_child
    .. automethod:: goto_next_sibling
    .. automethod:: goto_parent
    .. automethod:: goto_previous_sibling
    .. automethod:: reset
    .. automethod:: reset_to
 
-   Special methods
+   Special Methods
    ---------------
 
    .. automethod:: __copy__
- 
+
    Attributes
    ----------
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -66,6 +66,8 @@ def process_signature(_app, _what, name, _obj, _options, _signature, return_anno
         return "(language, *, included_ranges=None, timeout_micros=None)", return_annotation
     if name == "tree_sitter.Range":
         return "(start_point, end_point, start_byte, end_byte)", return_annotation
+    if name == "tree_sitter.QueryPredicate":
+        return None, return_annotation
 
 
 def process_docstring(_app, what, name, _obj, _options, lines):
@@ -78,6 +80,14 @@ def process_docstring(_app, what, name, _obj, _options, lines):
             lines[0] = f"Implements ``{special_doc.search(lines[0]).group(0)}``."
 
 
+def process_bases(_app, name, _obj, _options, bases):
+    if name == "tree_sitter.Point":
+        bases[-1] = ":class:`~typing.NamedTuple`"
+    if name == "tree_sitter.LookaheadIterator":
+        bases[-1] = ":class:`~collections.abc.Iterator`"
+
+
 def setup(app):
     app.connect("autodoc-process-signature", process_signature)
     app.connect("autodoc-process-docstring", process_docstring)
+    app.connect("autodoc-process-bases", process_bases)
diff --git a/docs/index.rst b/docs/index.rst
@@ -35,6 +35,8 @@ Classes
    tree_sitter.Parser
    tree_sitter.Point
    tree_sitter.Query
+   tree_sitter.QueryError
+   tree_sitter.QueryPredicate
    tree_sitter.Range
    tree_sitter.Tree
    tree_sitter.TreeCursor
diff --git a/setup.py b/setup.py
@@ -19,6 +19,7 @@
                 "tree_sitter/binding/node.c",
                 "tree_sitter/binding/parser.c",
                 "tree_sitter/binding/query.c",
+                "tree_sitter/binding/query_predicates.c",
                 "tree_sitter/binding/range.c",
                 "tree_sitter/binding/tree.c",
                 "tree_sitter/binding/tree_cursor.c",