Function: treesit-range-rules

treesit-range-rules is a byte-compiled function defined in treesit.el.gz.

Signature

(treesit-range-rules &rest QUERY-SPECS)

Documentation

Produce settings for treesit-range-settings.

QUERY-SPECS are a series of QUERY-SPECs, where each QUERY-SPEC is a QUERY preceded by zero or more pairs of :KEYWORD and VALUE, like this:

    :KEYWORD VALUE... QUERY

Each QUERY is a tree-sitter query in either the string, s-expression or compiled form.

Capture names generally don't matter, but names that starts with an underscore are ignored.

For each QUERY, :KEYWORD and VALUE pairs add meta information to it. For example,

    (treesit-range-rules
     :embed 'javascript
     :host 'html
     :offset '(1 . -1)
     '((script_element (raw_text) @cap)))

The :embed keyword specifies the embedded language, and the
:host keyword specifies the host language. They are used in
this way: Emacs queries QUERY in the host language's parser, computes the ranges spanned by the captured nodes, and applies these ranges to parsers for the embedded language.

If there's a :local keyword with value t, the range computed by this QUERY is given a dedicated local parser. Otherwise, the range shares the same parser with other ranges.

If there's an :offset keyword with a pair of numbers, each captured range is offset by those numbers. For example, an offset of (1 . -1) will update a captured range of (2 . 8) to be (3 . 7). This can be used to exclude things like surrounding delimiters from being included in the range covered by an embedded parser.

QUERY can also be a function that takes two arguments, START and END. If QUERY is a function, it doesn't need the :KEYWORD VALUE pair preceding it. This function should set the ranges for parsers in the current buffer in the region between START and END. It is OK for this function to set ranges in a larger region that encompasses the region between START and END.

View in manual

Source Code

;; Defined in /usr/src/emacs/lisp/treesit.el.gz
(defun treesit-range-rules (&rest query-specs)
  "Produce settings for `treesit-range-settings'.

QUERY-SPECS are a series of QUERY-SPECs, where each QUERY-SPEC is
a QUERY preceded by zero or more pairs of :KEYWORD and VALUE,
like this:

    :KEYWORD VALUE... QUERY

Each QUERY is a tree-sitter query in either the string,
s-expression or compiled form.

Capture names generally don't matter, but names that starts with
an underscore are ignored.

For each QUERY, :KEYWORD and VALUE pairs add meta information to
it.  For example,

    (treesit-range-rules
     :embed \\='javascript
     :host \\='html
     :offset \\='(1 . -1)
     \\='((script_element (raw_text) @cap)))

The `:embed' keyword specifies the embedded language, and the
`:host' keyword specifies the host language.  They are used in
this way: Emacs queries QUERY in the host language's parser,
computes the ranges spanned by the captured nodes, and applies
these ranges to parsers for the embedded language.

If there's a `:local' keyword with value t, the range computed by
this QUERY is given a dedicated local parser.  Otherwise, the
range shares the same parser with other ranges.

If there's an `:offset' keyword with a pair of numbers, each
captured range is offset by those numbers.  For example, an
offset of (1 . -1) will update a captured range of (2 . 8) to
be (3 . 7).  This can be used to exclude things like surrounding
delimiters from being included in the range covered by an
embedded parser.

QUERY can also be a function that takes two arguments, START and
END.  If QUERY is a function, it doesn't need the :KEYWORD VALUE
pair preceding it.  This function should set the ranges for
parsers in the current buffer in the region between START and
END.  It is OK for this function to set ranges in a larger region
that encompasses the region between START and END."
  (let (host embed offset result local)
    (while query-specs
      (pcase (pop query-specs)
        (:local (when (eq t (pop query-specs))
                  (setq local t)))
        (:host (let ((host-lang (pop query-specs)))
                 (unless (symbolp host-lang)
                   (signal 'treesit-error (list "Value of :host option should be a symbol" host-lang)))
                 (setq host host-lang)))
        (:embed (let ((embed-lang (pop query-specs)))
                  (unless (symbolp embed-lang)
                    (signal 'treesit-error (list "Value of :embed option should be a symbol" embed-lang)))
                  (setq embed embed-lang)))
        (:offset (let ((range-offset (pop query-specs)))
                   (unless (and (consp range-offset)
                                (numberp (car range-offset))
                                (numberp (cdr range-offset)))
                     (signal 'treesit-error (list "Value of :offset option should be a pair of numbers" range-offset)))
                   (setq offset range-offset)))
        (query (if (functionp query)
                   (push (list query nil nil) result)
                 (when (null embed)
                   (signal 'treesit-error (list "Value of :embed option cannot be omitted")))
                 (when (null host)
                   (signal 'treesit-error (list "Value of :host option cannot be omitted")))
                 (push (list (treesit-query-compile host query)
                             embed local offset)
                       result))
               (setq host nil embed nil offset nil local nil))))
    (nreverse result)))