core: Rename tree-traversal functions

- `tsc-traverse-depth-first-native`   -> `tsc-traverse-mapc`
- `tsc-traverse-depth-first-iterator` -> `tsc-traverse-iter`
- `tsc-do-tree`                       -> `tsc-traverse-do`

Author: ubolonton

core/src/cursor.rs

@@ -325,7 +325,7 @@ fn _current_node<'e>(cursor: &RCursor, props: Option<Vector<'e>>, output: Option
 }
 
 #[defun]
-fn _traverse_depth_first_native(tree_or_node: TreeOrNode, func: Value, props: Option<Vector>) -> Result<()> {
+fn _traverse_mapc(func: Value, tree_or_node: TreeOrNode, props: Option<Vector>) -> Result<()> {
     let mut iterator = DepthFirstIterator::new(tree_or_node);
     let env = func.env;
     let output = match props {

core/tsc.el

@@ -289,28 +289,29 @@ values.
 This wouldn't be necessary if the runtime supported stack-allocated objects.
 e.g. automatically through escape analysis. How about porting ELisp to GraalVM?")
 
-(defun tsc-traverse-depth-first-native (tree-or-node fn &optional props)
-  "Call FN for each node of TREE-OR-NODE.
+(defun tsc-traverse-mapc (func tree-or-node &optional props)
+  "Call FUNC for each node of TREE-OR-NODE.
 The traversal is depth-first pre-order.
 
-If the optional arg PROPS is a vector of keywords, FN is called with a vector
+If the optional arg PROPS is a vector of keywords, FUNC is called with a vector
 containing the corresponding node properties, instead of the node itself. For
-efficiency, this vector is reused across invocations of FN. *DO NOT* keep a
+efficiency, this vector is reused across invocations of FUNC. *DO NOT* keep a
 reference to it. It's recommended to use `pcase-let' to extract the properties.
 
 For example, to crudely render a syntax tree:
 
-    (tsc-traverse-depth-first-native
-     tree (lambda (props)
-            (pcase-let ((`[,type ,depth ,named-p] props))
-              (when named-p                     ;AST
-                (insert (make-string depth \\? ) ;indentation
-                        (format \"%S\" type) \"\\n\"))))
+    (tsc-traverse-mapc
+     (lambda (props)
+       (pcase-let ((`[,type ,depth ,named-p] props))
+         (when named-p                     ;AST
+           (insert (make-string depth \\? ) ;indentation
+                   (format \"%S\" type) \"\\n\"))))
+     tree
      [:type :depth :named-p])
 "
-  (tsc--traverse-depth-first-native tree-or-node fn props))
+  (tsc--traverse-mapc func tree-or-node props))
 
-(defun tsc-traverse-depth-first-iterator (tree-or-node &optional props)
+(defun tsc-traverse-iter (tree-or-node &optional props)
   "Return an iterator that traverse TREE-OR-NODE.
 The traversal is depth-first pre-order.
 
@@ -321,7 +322,7 @@ to it. It's recommended to use `pcase-let' to extract the properties.
 
 For example, to crudely render a syntax tree:
 
-    (iter-do (props (tsc-traverse-depth-first-iterator
+    (iter-do (props (tsc-traverse-iter
                      tree [:type :depth :named-p]))
       (pcase-let ((`[,type ,depth ,named-p] props))
         (when named-p                       ;AST
@@ -339,13 +340,13 @@ For example, to crudely render a syntax tree:
         (:close (setq iter nil))
         (_ (error "???"))))))
 
-(cl-defmacro tsc-do-tree ((vars tree-or-node) &rest body)
+(cl-defmacro tsc-traverse-do ((vars tree-or-node) &rest body)
   "Evaluate BODY with VARS bound to properties of each node in TREE-OR-NODE.
 The traversal is depth-first pre-order.
 
 VARS must be a vector of symbols. For example, to crudely render a syntax tree:
 
-    (tsc-do-tree ([type depth named-p] tree)
+    (tsc-traverse-do ([type depth named-p] tree)
       (when named-p                     ;AST
         (insert (make-string depth \\? ) ;identation
                 (format \"%S\" type) \"\\n\")))

doc/emacs-tree-sitter.org

@@ -630,26 +630,27 @@ These functions are high-level APIs that allow traversing the syntax tree in dep
 
 When dealing with a large number of nodes, working with node objects creates a huge pressure on the garbage collector. For better performance, it's advisable to extract and work with individual node properties.
 
-- ~tsc-do-tree~ /~(vars tree-or-node) body~/ :: Evaluate ~body~ with ~vars~ bound to corresponding properties of each traversed node.
+- ~tsc-traverse-do~ /~(vars tree-or-node) body~/ :: Evaluate ~body~ with ~vars~ bound to corresponding properties of each traversed node.
     #+begin_src emacs-lisp
-      (tsc-do-tree ([type depth named-p] tree)
+      (tsc-traverse-do ([type depth named-p] tree)
         (when named-p                         ;AST
           (insert (make-string depth \? )     ;indentation
                   (format "%S" type) "\n")))
     #+end_src
-- ~tsc-traverse-depth-first-native~ /~tree-or-node fn [props]~/ :: Call ~fn~ for each traversed node, passing the node as the argument. If the vector of keywords ~props~ is specified, ~fn~ receives a vector containing the node's properties instead. *Do not keep a reference to the vector*, as it is reused across invocations. Use ~pcase-let~ to extract the properties.
+- ~tsc-traverse-mapc~ /~func tree-or-node [props]~/ :: Call ~func~ for each traversed node, passing the node as the argument. If the vector of keywords ~props~ is specified, ~func~ receives a vector containing the node's properties instead. *Do not keep a reference to the vector*, as it is reused across invocations. Use ~pcase-let~ to extract the properties.
     #+begin_src emacs-lisp
-      (tsc-traverse-depth-first-native
-       tree (lambda (props)
-              (pcase-let ((`[,type ,depth ,named-p] props))
-                (when named-p                     ;AST
-                  (insert (make-string depth \? ) ;indentation
-                          (format "%S" type) "\n"))))
+      (tsc-traverse-mapc
+       (lambda (props)
+         (pcase-let ((`[,type ,depth ,named-p] props))
+           (when named-p                          ;AST
+             (insert (make-string depth \? )      ;indentation
+                     (format "%S" type) "\n"))))
+       tree
        [:type :depth :named-p])
     #+end_src
-- ~tsc-traverse-depth-first-iterator~ /~tree-or-node [props]~/ :: Create an iterator that yields traversed nodes. If the vector of keywords ~props~ is specified, the iterator yields a vector containing the node's properties instead. *Do not keep a reference to the vector*, as it is reused across iterations. Use ~pcase-let~ to extract the properties.
+- ~tsc-traverse-iter~ /~tree-or-node [props]~/ :: Create an iterator that yields traversed nodes. If the vector of keywords ~props~ is specified, the iterator yields a vector containing the node's properties instead. *Do not keep a reference to the vector*, as it is reused across iterations. Use ~pcase-let~ to extract the properties.
     #+begin_src emacs-lisp
-      (iter-do (props (tsc-traverse-depth-first-iterator
+      (iter-do (props (tsc-traverse-iter
                        tree [:type :depth :named-p]))
         (pcase-let ((`[,type ,depth ,named-p] props))
           (when named-p                       ;AST

lisp/tree-sitter-debug.el

@@ -69,7 +69,7 @@ This only takes effect if `tree-sitter-debug-jump-buttons' is non-nil."
                          'points-to `(,start-byte . ,end-byte))
         (insert node-text)))))
 
-(defvar tree-sitter-debug-traversal-method :do-tree)
+(defvar tree-sitter-debug-traversal-method :mapc)
 
 (defun tree-sitter-debug--display-tree (_old-tree)
   "Display the current `tree-sitter-tree'."
@@ -79,20 +79,21 @@ This only takes effect if `tree-sitter-debug-jump-buttons' is non-nil."
       (let (buffer-read-only)
         (erase-buffer)
         (pcase tree-sitter-debug-traversal-method
-          (:native (tsc-traverse-depth-first-native
-                    tree (lambda (props)
-                           (pcase-let ((`[,named-p ,type ,start-byte ,end-byte ,depth] props))
-                             (tree-sitter-debug--display-node
-                              named-p type start-byte end-byte depth)))
-                    [:named-p :type :start-byte :end-byte :depth]))
-          (:iterator (iter-do (props (tsc-traverse-depth-first-iterator
-                                      tree [:named-p :type :start-byte :end-byte :depth]))
-                       (pcase-let ((`[,named-p ,type ,start-byte ,end-byte ,depth] props))
-                         (tree-sitter-debug--display-node
-                          named-p type start-byte end-byte depth))))
-          (:do-tree (tsc-do-tree ([named-p type start-byte end-byte depth] tree)
+          (:mapc (tsc-traverse-mapc
+                  (lambda (props)
+                    (pcase-let ((`[,named-p ,type ,start-byte ,end-byte ,depth] props))
                       (tree-sitter-debug--display-node
-                       named-p type start-byte end-byte depth))))))))
+                       named-p type start-byte end-byte depth)))
+                  tree
+                  [:named-p :type :start-byte :end-byte :depth]))
+          (:iter (iter-do (props (tsc-traverse-iter
+                                  tree [:named-p :type :start-byte :end-byte :depth]))
+                   (pcase-let ((`[,named-p ,type ,start-byte ,end-byte ,depth] props))
+                     (tree-sitter-debug--display-node
+                      named-p type start-byte end-byte depth))))
+          (:do (tsc-traverse-do ([named-p type start-byte end-byte depth] tree)
+                 (tree-sitter-debug--display-node
+                  named-p type start-byte end-byte depth))))))))
 
 (defun tree-sitter-debug--setup ()
   "Set up syntax tree debugging in the current buffer."

tests/tree-sitter-tests.el

@@ -372,19 +372,19 @@ source_file (1 . 20)
          (string=
           rendered
           (tsc-test-capture-messages
-           (tsc-traverse-depth-first-native
-            tree
+           (tsc-traverse-mapc
             (lambda (props)
               (pcase-let ((`[,type ,named-p ,start-byte ,end-byte ,field ,depth] props))
                 (tsc-test-render-node type named-p start-byte end-byte field depth)))
+            tree
             [:type :named-p :start-byte :end-byte :field :depth])))))
       (ert-info ("Generator-based traversal should work")
         (should
          (string=
           rendered
           (tsc-test-capture-messages
            (cl-loop for item
-                    iter-by (tsc-traverse-depth-first-iterator
+                    iter-by (tsc-traverse-iter
                              tree [:type :named-p :start-byte :end-byte :field :depth])
                     do (pcase-let ((`[,type ,named-p ,start-byte ,end-byte ,field ,depth] item))
                          (tsc-test-render-node type named-p start-byte end-byte field depth)))))))
@@ -393,7 +393,7 @@ source_file (1 . 20)
          (string=
           rendered
           (tsc-test-capture-messages
-           (tsc-do-tree ([type named-p start-byte end-byte field depth] tree)
+           (tsc-traverse-do ([type named-p start-byte end-byte field depth] tree)
              (tsc-test-render-node type named-p start-byte end-byte field depth)))))))))
 
 (ert-deftest cursor::bench ()
@@ -405,24 +405,24 @@ source_file (1 . 20)
       (dolist (n '(1 10 100))
         (message "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~")
         (garbage-collect)
-        (message "    native %3d %s" n
+        (message "%10s %3d %s" :mapc n
                  (eval `(benchmark-run-compiled ,n
-                          (tsc-traverse-depth-first-native
-                           tree-sitter-tree
+                          (tsc-traverse-mapc
                            tsc-test-no-op
+                           tree-sitter-tree
                            ,props))))
         (garbage-collect)
-        (message "  iterator %3d %s" n
+        (message "%10s %3d %s" :iter n
                  (eval `(benchmark-run-compiled ,n
-                          (iter-do (_ (tsc-traverse-depth-first-iterator tree-sitter-tree ,props))
+                          (iter-do (_ (tsc-traverse-iter tree-sitter-tree ,props))
                             (tsc-test-no-op)))))
         (garbage-collect)
-        (message "   do-tree %3d %s" n
+        (message "%10s %3d %s" :do n
                  (eval `(benchmark-run-compiled ,n
-                          (tsc-do-tree ([named-p type start-byte end-byte] tree-sitter-tree)
+                          (tsc-traverse-do ([named-p type start-byte end-byte] tree-sitter-tree)
                             named-p type start-byte end-byte))))
         (garbage-collect)
-        (message "   funcall %3d %s" n
+        (message "%10s %3d %s" 'funcall n
                  (eval `(benchmark-run-compiled ,(* 3429 n)
                           (funcall tsc-test-no-op ,props 5))))))))
 
@@ -639,7 +639,7 @@ We know it should since it is the `source_file' node."
     (rust-mode)
     (dolist (n '(1 10 100))
       (message "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~")
-      (dolist (tree-sitter-debug-traversal-method '(:native :iterator :do-tree))
+      (dolist (tree-sitter-debug-traversal-method '(:mapc :iter :do))
         (garbage-collect)
         (message "%10s %3d %s" tree-sitter-debug-traversal-method n
                  (eval `(benchmark-run-compiled ,n