;;; treesit.el --- tree-sitter utilities -*- lexical-binding: t -*-
-;; Copyright (C) 2021 Free Software Foundation, Inc.
+;; Copyright (C) 2021-2022 Free Software Foundation, Inc.
;; This file is part of GNU Emacs.
;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
-;;
-;; This file is the lisp counterpart of treesit.c, together they
+
+;; This file is the Lisp counterpart of treesit.c. Together they
;; provide tree-sitter integration for Emacs. This file contains
;; convenient functions that are more idiomatic and flexible than the
;; exposed C API of tree-sitter. It also contains frameworks for
-;; integrating tree-sitter with font-lock, indent, activate/deactivate
-;; tree-sitter, debugging tree-sitter, etc.
+;; integrating tree-sitter with font-lock, indentation, activating and
+;; deactivating tree-sitter, debugging tree-sitter, etc.
;;; Code:
(defcustom treesit-settings '((t nil t))
"Tree-sitter toggle settings for major modes.
-A list of (MODE ACTIVATE INHERIT). MODE is a major mode, ACTIVATE
-can be one of the following:
+A list of (MODE ACTIVATE INHERIT) where MODE is a major mode, and
+ACTIVATE can be one of the following:
- demand => Demand the use of tree-sitter, warn if it can't activate
- t => Enable if available
- nil => Don't enable
+ `demand' Demand the use of tree-sitter, and warn if it can't
+ be activated.
+ t Enable tree-sitter if it is available.
+ nil Don't enable tree-sitter.
If INHERIT is t, the setting for MODE is inherited by all its
derived modes. For a derived mode, closer ancestor mode's
This is used by `treesit-language-at', which is used by various
functions to determine which parser to use at point.
-The function is called with the position of point.")
+The function is called with one argument, the position of point.")
-(defun treesit-language-at (pos)
- "Return the language at POS.
+(defun treesit-language-at (position)
+ "Return the language at POSITION.
Assumes parser ranges are up-to-date."
(when treesit-language-at-point-function
- (funcall treesit-language-at-point-function pos)))
+ (funcall treesit-language-at-point-function position)))
(defun treesit-set-ranges (parser-or-lang ranges)
"Set the ranges of PARSER-OR-LANG to RANGES."
;;; Node API supplement
(defun treesit-node-buffer (node)
- "Return the buffer in where NODE belongs."
+ "Return the buffer in which NODE belongs."
(treesit-parser-buffer
(treesit-node-parser node)))
(defun treesit-node-at (pos &optional parser-or-lang named strict)
"Return the smallest node that starts at or after buffer position POS.
-\"Starts at or after POS\" means the start of the node is greater or
-equal than POS.
+\"Starts at or after POS\" means the start of the node is greater
+than or equal to POS.
-Return nil if none find. If NAMED is non-nil, only look for named node.
+Return nil if none was found. If NAMED is non-nil, only look for
+named node.
If PARSER-OR-LANG is nil, use the first parser in
-\(`treesit-parser-list'); if PARSER-OR-LANG is a parser, use
+`treesit-parser-list'; if PARSER-OR-LANG is a parser, use
that parser; if PARSER-OR-LANG is a language, find a parser using
that language in the current buffer, and use that.
"Return the smallest node covering BEG to END.
BEWARE! Calling this function on an empty line that is not
-inside any top-level construct (function definition, etc) most
+inside any top-level construct (function definition, etc.) most
probably will give you the root node, because the root node is
the smallest node that covers that empty line. You probably want
to use `treesit-node-at' instead.
-Return nil if none find. If NAMED non-nil, only look for named
-node.
+Return nil if none was found. If NAMED is non-nil, only look for
+named node.
If PARSER-OR-LANG is nil, use the first parser in
-(`treesit-parser-list'); if PARSER-OR-LANG is a parser, use
+`treesit-parser-list'; if PARSER-OR-LANG is a parser, use
that parser; if PARSER-OR-LANG is a language, find a parser using
that language in the current buffer, and use that."
(let ((root (if (treesit-parser-p parser-or-lang)
(treesit-node-descendant-for-range root beg (or end beg) named)))
(defun treesit-node-top-level-p (node &optional type)
- "Return non-nil if NODE is top-level, nil otherwise.
+ "Return non-nil if NODE is top-level, and nil otherwise.
Being top-level means there is no parent of NODE that has the
same type.
(defun treesit-buffer-root-node (&optional language)
"Return the root node of the current buffer.
-Use the first parser in (`treesit-parser-list'), if LANGUAGE is
-non-nil, use the first parser for LANGUAGE."
+Use the first parser in `treesit-parser-list'.
+
+If optional argument LANGUAGE is non-nil, use the first parser
+for LANGUAGE."
(if-let ((parser
(or (if language
(or (treesit-parser-create language)
(treesit-parser-root-node parser)))
(defun treesit-filter-child (node pred &optional named)
- "Return children of NODE that satisfies PRED.
-PRED is a function that takes one argument, the child node. If
-NAMED non-nil, only search for named node."
+ "Return children of NODE that satisfies predicate PRED.
+PRED is a function that takes one argument, the child node.
+If optional argument NAMED is non-nil, only search for named
+node."
(let ((child (treesit-node-child node 0 named))
result)
(while child
(defun treesit-node-text (node &optional no-property)
"Return the buffer (or string) content corresponding to NODE.
-If NO-PROPERTY is non-nil, remove text properties."
+If optional argument NO-PROPERTY is non-nil, remove text
+properties."
(when node
(with-current-buffer (treesit-node-buffer node)
(if no-property
(defun treesit-parent-until (node pred)
"Return the closest parent of NODE that satisfies PRED.
-Return nil if none found. PRED should be a function that takes
-one argument, the parent node."
+Return nil if none was found. PRED should be a function that
+takes one argument, the parent node."
(let ((node (treesit-node-parent node)))
(while (and node (not (funcall pred node)))
(setq node (treesit-node-parent node)))
(defun treesit-parent-while (node pred)
"Return the furthest parent of NODE that satisfies PRED.
-Return nil if none found. PRED should be a function that takes
-one argument, the parent node."
+Return nil if none was found. PRED should be a function that
+takes one argument, the parent node."
(let ((last nil))
(while (and node (funcall pred node))
(setq last node
Removing a feature symbol from this list disables the
corresponding query during font-lock.
-Common feature names (for general programming language) include
+Common feature names (for general programming languages) include
function-name, type, variable-name (LHS of assignments), builtin,
constant, keyword, string-interpolation, comment, doc, string,
operator, preprocessor, escape-sequence, key (in key-value
For SETTING to be activated for font-lock, ENABLE must be t. To
disable this SETTING, set ENABLE to nil.
-FEATURE is the \"feature name\" of the query, users can control
+FEATURE is the \"feature name\" of the query. Users can control
which features are enabled with `font-lock-maximum-decoration'
and `treesit-font-lock-feature-list'.
(defun treesit-font-lock-recompute-features ()
"Enable/disable font-lock settings according to decoration level.
-Sets the ENABLE flag for each setting in
+Set the ENABLE flag for each setting in
`treesit-font-lock-settings', according to
`treesit-font-lock-feature-list' and
`font-lock-maximum-decoration'."
(defun treesit-font-lock-fontify-region
(start end &optional loudly)
"Fontify the region between START and END.
-If LOUDLY is non-nil, message some debugging information."
+If LOUDLY is non-nil, display some debugging information."
(treesit-update-ranges start end)
(font-lock-unfontify-region start end)
(dolist (setting treesit-font-lock-settings)
(node predicate &optional start backward all)
"Search forward for a node and move to its end position.
-Stops at the first node after NODE that matches PREDICATE.
+Stop at the first node after NODE that matches PREDICATE.
PREDICATE can be either a regexp that matches against each node's
type case-insensitively, or a function that takes a node and
returns nil/non-nil for match/no match.
(defun treesit-beginning-of-defun (&optional arg)
"Tree-sitter `beginning-of-defun' function.
-ARG is the same as in `beginning-of-defun."
+ARG is the same as in `beginning-of-defun'."
(let ((arg (or arg 1))
(node (treesit-node-at (point))))
(if (> arg 0)
If MODE is nil, don't check for user setting and assume the
setting is t.
-LANGUAGE is languages symbol we want check for availability. It
-can also be a list of language symbols."
+LANGUAGE is the language symbol we want check for availability.
+It can also be a list of language symbols."
(let ((language-list (if (consp language)
language
(list language)))
;;; Debugging
(defvar-local treesit--inspect-name nil
- "treesit-inspect-mode uses this to show node name in mode-line.")
+ "Used by `treesit-inspect-mode' to show node name in mode-line.")
(defun treesit-inspect-node-at-point (&optional arg)
"Show information of the node at point.
If called interactively, show in echo area, otherwise set
`treesit--inspect-name' (which will appear in the mode-line
if `treesit-inspect-mode' is enabled). Uses the first parser
-in (`treesit-parser-list')."
+in `treesit-parser-list'."
(interactive "p")
;; NODE-LIST contains all the node that starts at point.
(let* ((node-list
(message "No node at point")))))
(define-minor-mode treesit-inspect-mode
- "Shows the node that _starts_ at point in the mode-line.
+ "Show the node that _starts_ at point in the mode-line.
The mode-line displays
CHILD.
If no node starts at point, i.e., point is in the middle of a
-node, then we just display the smallest node that spans point and
+node, then just display the smallest node that spans point and
its immediate parent.
This minor mode doesn't create parsers on its own. It simply
-uses the first parser in (`treesit-parser-list')."
+uses the first parser in `treesit-parser-list'."
:lighter nil
(if treesit-inspect-mode
(progn
(defun treesit-query-validate (language query)
"Check if QUERY is valid for LANGUAGE.
-If QUERY is invalid, display the query in a popup buffer, jumps
+If QUERY is invalid, display the query in a popup buffer, jump
to the offending pattern and highlight the pattern."
(cl-assert (or (consp query) (stringp query)))
(let ((buf (get-buffer-create "*tree-sitter check query*")))
projects / emacs.git / commitdiff