core: Add node property names validation to tree traversal functions

Author: ubolonton

core/src/cursor.rs

@@ -340,9 +340,12 @@ fn _iter_next_node(iterator: &mut DepthFirstIterator, props: Vector, output: Vec
 
 /// Return CURSOR's current node, if PROPS is nil.
 ///
-/// If PROPS is a vector of keywords, this function returns a vector containing the
-/// corresponding node properties instead of the node itself. If OUTPUT is also a
-/// vector, this function overwrites its contents instead of creating a new vector.
+/// If PROPS is a vector of property names, this function returns a vector
+/// containing the node's corresponding properties instead of the node itself. If
+/// OUTPUT is also a vector, this function overwrites its contents instead of
+/// creating a new vector.
+///
+/// See `tsc-valid-node-props' for the list of available properties.
 #[defun]
 fn _current_node<'e>(cursor: &RCursor, props: Option<Vector<'e>>, output: Option<Vector<'e>>, env: &'e Env) -> Result<Value<'e>> {
     macro_rules! sugar {

core/tsc.el

@@ -260,20 +260,14 @@ QUERY. Otherwise, a newly created query-cursor is used."
 
 ;;; Traversal.
 
-(defconst tsc-valid-node-props '(field
-                                 type
-                                 named-p
-                                 extra-p
-                                 error-p
-                                 missing-p
-                                 has-error-p
-                                 start-byte
-                                 start-point
-                                 end-byte
-                                 end-point
-                                 range
-                                 byte-range
-                                 depth)
+(defconst tsc-valid-node-props
+  '(:type
+    :field ;node's field name within the parent node
+    :depth ;node's depth, relative to the iterator's start
+    :named-p :extra-p :error-p :missing-p :has-error-p
+    :start-byte :end-byte
+    :start-point :end-point
+    :range :byte-range)
   "Node properties that the traversal functions can return.
 
 When dealing with a large number of nodes, working with node objects creates a
@@ -285,14 +279,23 @@ 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--check-node-props (props)
+  "Validate that PROPS are valid node properties."
+  (when props
+    (when-let ((invalid-props (seq-filter (lambda (kw)
+                                            (not (memq kw tsc-valid-node-props)))
+                                          props)))
+      (error "Invalid node properties %s" invalid-props))))
+
 (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, 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 FUNC. *DO NOT* keep a
-reference to it. It's recommended to use `pcase-let' to extract the properties.
+If the optional arg PROPS is a vector of property names, FUNC is called with a
+vector containing the node's corresponding properties, instead of the node
+itself. For 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. See `tsc-valid-node-props' for the list of available properties.
 
 For example, to crudely render a syntax tree:
 
@@ -305,16 +308,18 @@ For example, to crudely render a syntax tree:
      tree
      [:type :depth :named-p])
 "
+  (tsc--check-node-props props)
   (tsc--traverse-mapc func tree-or-node 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.
 
-If the optional arg PROPS is a vector of keywords, the iterator yields a vector
-containing corresponding node properties, instead of the node itself. For
-efficiency, this vector is reused across iterations. *DO NOT* keep a reference
-to it. It's recommended to use `pcase-let' to extract the properties.
+If the optional arg PROPS is a vector of property names, the iterator yields a
+vector containing the node's corresponding properties, instead of the node
+itself. For efficiency, this vector is reused across iterations. *DO NOT KEEP* a
+reference to it. It's recommended to use `pcase-let' to extract the properties.
+See `tsc-valid-node-props' for the list of available properties.
 
 For example, to crudely render a syntax tree:
 
@@ -325,6 +330,7 @@ For example, to crudely render a syntax tree:
           (insert (make-string depth \\? )   ;indentation
                   (format \"%S\" type) \"\\n\"))))
 "
+  (tsc--check-node-props props)
   (let ((iter (tsc--iter tree-or-node))
         (output (when props
                   (make-vector (length props) nil))))
@@ -340,7 +346,10 @@ For example, to crudely render a syntax tree:
   "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:
+VARS must be a vector of symbols. See `tsc-valid-node-props' for the list of
+available properties. (In VARS, they must be symbols, not keywords.)
+
+For example, to crudely render a syntax tree:
 
     (tsc-traverse-do ([type depth named-p] tree)
       (when named-p                     ;AST
@@ -351,17 +360,13 @@ VARS must be a vector of symbols. For example, to crudely render a syntax tree:
            (debug ((vectorp form) body)))
   (unless (vectorp vars)
     (error "Var bindings must be a vector"))
-  (let* ((invalid-props (seq-filter (lambda (symbol)
-                                      (not (memq symbol tsc-valid-node-props)))
-                                    vars))
-         (_ (when invalid-props
-              (error "Invalid bindings %s" invalid-props)))
-         (iter (gensym "iter"))
-         (output (gensym "output"))
-         (props (cl-map 'vector
-                        (lambda (symbol)
-                          (intern (format ":%s" symbol)))
-                        vars)))
+  (let ((props (cl-map 'vector
+                       (lambda (symbol)
+                         (intern (format ":%s" symbol)))
+                       vars))
+        (iter (make-symbol "iter"))
+        (output (make-symbol "output")))
+    (tsc--check-node-props props)
     `(let ((,iter (tsc--iter ,tree-or-node))
            (,output ,(when props
                        (make-vector (length props) nil))))

doc/emacs-tree-sitter.org

@@ -628,7 +628,17 @@ Tree-walking functions enable efficient traversal of the syntax tree.
 *** Traversing All Descendant Nodes
 These functions are high-level APIs that allow traversing the syntax tree in depth-first pre-order.
 
-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.
+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. The constant ~tsc-valid-node-props~ holds the list of all available property names.
+# TODO: Make :exports results work with ox-hugo.
+#+begin_src emacs-lisp
+  '(:type
+    :field ;node's field name within the parent node
+    :depth ;node's depth, relative to the iterator's start
+    :named-p :extra-p :error-p :missing-p :has-error-p
+    :start-byte :end-byte
+    :start-point :end-point
+    :range :byte-range)
+#+end_src
 
 - ~tsc-traverse-do~ /~(vars tree-or-node) body~/ :: Evaluate ~body~ with ~vars~ bound to corresponding properties of each traversed node.
     #+begin_src emacs-lisp
@@ -637,7 +647,7 @@ When dealing with a large number of nodes, working with node objects creates a h
           (insert (make-string depth \? )     ;indentation
                   (format "%S" type) "\n")))
     #+end_src
-- ~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.
+- ~tsc-traverse-mapc~ /~func tree-or-node [props]~/ :: Call ~func~ for each traversed node, passing the node as the argument. If ~props~ is a vector of property names, ~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-mapc
        (lambda (props)
@@ -648,7 +658,7 @@ When dealing with a large number of nodes, working with node objects creates a h
        tree
        [:type :depth :named-p])
     #+end_src
-- ~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.
+- ~tsc-traverse-iter~ /~tree-or-node [props]~/ :: Create an iterator that yields traversed nodes. If ~props~ is a vector of property names, 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-iter
                        tree [:type :depth :named-p]))