Function: treesit-font-lock-rules
treesit-font-lock-rules is a byte-compiled function defined in
treesit.el.gz.
Signature
(treesit-font-lock-rules &rest QUERY-SPECS)
Documentation
Return a value suitable for treesit-font-lock-settings.
QUERY-SPECS is a series of QUERY-SPECs. Each QUERY-SPEC is a QUERY preceded by multiple pairs of :KEYWORD and VALUE:
:KEYWORD VALUE... QUERY
QUERY is a tree-sitter query in either the string, s-expression or compiled form. For each query, captured nodes are highlighted with the capture name as its face. QUERY is compiled automatically when it's first used in a major mode.
:KEYWORD and VALUE pairs preceding a QUERY add meta information
to QUERY. For example,
(treesit-font-lock-rules
:language 'javascript
:override t
:feature'constant
'((true) @font-lock-constant-face
(false) @font-lock-constant-face)
:language 'html
:feature 'script
"(script_element) @font-lock-builtin-face")
For each QUERY, a :language keyword and a :feature keyword are
required. Each query's :feature is a symbol summarizing what the
query fontifies. It is used to allow users to enable/disable
certain features. See treesit-font-lock-feature-list for more.
Other keywords include:
KEYWORD VALUE DESCRIPTION
:override nil If the region already has a face,
discard the new face.
t Always apply the new face.
append Append the new face to existing ones.
prepend Prepend the new face to existing ones.
keep Fill-in regions without an existing face.
:reversed t Enable the query only if the feature is
NOT in feature list.
:default-language LANGUAGE Every QUERY after this keyword
will use LANGUAGE by default.
Capture names in QUERY should be face names like
font-lock-keyword-face. The captured node will be fontified
with that face.
Capture names can also be function names, in which case the function will be called with the following argument list:
(NODE OVERRIDE START END &rest _)
where NODE is the tree-sitter node object, OVERRIDE is the override option of that rule, and START and END specify the region to be fontified. This function should accept more arguments as optional arguments for future extensibility, and it shouldn't fontify text outside the region given by START and END.
If a capture name is both a face and a function, the face takes priority. If a capture name is not a face name nor a function name, it is ignored.
Probably introduced at or before Emacs version 30.1.
Source Code
;; Defined in /usr/src/emacs/lisp/treesit.el.gz
(defun treesit-font-lock-rules (&rest query-specs)
"Return a value suitable for `treesit-font-lock-settings'.
QUERY-SPECS is a series of QUERY-SPECs. Each QUERY-SPEC is a
QUERY preceded by multiple pairs of :KEYWORD and VALUE:
:KEYWORD VALUE... QUERY
QUERY is a tree-sitter query in either the string, s-expression or
compiled form. For each query, captured nodes are highlighted with the
capture name as its face. QUERY is compiled automatically when it's
first used in a major mode.
:KEYWORD and VALUE pairs preceding a QUERY add meta information
to QUERY. For example,
(treesit-font-lock-rules
:language \\='javascript
:override t
:feature\\='constant
\\='((true) @font-lock-constant-face
(false) @font-lock-constant-face)
:language \\='html
:feature \\='script
\"(script_element) @font-lock-builtin-face\")
For each QUERY, a :language keyword and a :feature keyword are
required. Each query's :feature is a symbol summarizing what the
query fontifies. It is used to allow users to enable/disable
certain features. See `treesit-font-lock-feature-list' for more.
Other keywords include:
KEYWORD VALUE DESCRIPTION
:override nil If the region already has a face,
discard the new face.
t Always apply the new face.
`append' Append the new face to existing ones.
`prepend' Prepend the new face to existing ones.
`keep' Fill-in regions without an existing face.
:reversed t Enable the query only if the feature is
NOT in feature list.
:default-language LANGUAGE Every QUERY after this keyword
will use LANGUAGE by default.
Capture names in QUERY should be face names like
`font-lock-keyword-face'. The captured node will be fontified
with that face.
Capture names can also be function names, in which case the
function will be called with the following argument list:
(NODE OVERRIDE START END &rest _)
where NODE is the tree-sitter node object, OVERRIDE is the
override option of that rule, and START and END specify the region
to be fontified. This function should accept more arguments as
optional arguments for future extensibility, and it shouldn't
fontify text outside the region given by START and END.
If a capture name is both a face and a function, the face takes
priority. If a capture name is not a face name nor a function
name, it is ignored."
;; Other tree-sitter function don't tend to be called unless
;; tree-sitter is enabled, which means tree-sitter must be compiled.
;; But this function is usually call in `defvar' which runs
;; regardless whether tree-sitter is enabled. So we need this
;; guard.
(when (treesit-available-p)
(let (;; Tracks the current :language/:override/:toggle/:level value
;; that following queries will apply to.
current-language current-override
current-feature
;; DEFAULT-LANGUAGE will be chosen when current-language is
;; not set.
default-language
current-reversed
;; The list this function returns.
(result nil))
(while query-specs
(let ((token (pop query-specs)))
(pcase token
;; (1) Process keywords.
(:default-language
(let ((lang (pop query-specs)))
(when (or (not (symbolp lang)) (null lang))
(signal 'treesit-font-lock-error
`("Value of :default-language should be a symbol"
,lang)))
(setq default-language lang)))
(:language
(let ((lang (pop query-specs)))
(when (or (not (symbolp lang)) (null lang))
(signal 'treesit-font-lock-error
`("Value of :language should be a symbol"
,lang)))
(setq current-language lang)))
(:override
(let ((flag (pop query-specs)))
(when (not (memq flag '(t nil append prepend keep)))
(signal 'treesit-font-lock-error
`("Value of :override should be one of t, nil, append, prepend, keep"
,flag))
(signal 'wrong-type-argument
`((or t nil append prepend keep)
,flag)))
(setq current-override flag)))
(:feature
(let ((var (pop query-specs)))
(when (or (not (symbolp var))
(memq var '(t nil)))
(signal 'treesit-font-lock-error
`("Value of :feature should be a symbol"
,var)))
(setq current-feature var)))
(:reversed
(let ((var (pop query-specs)))
(when (not (memq var '(t nil)))
(signal 'treesit-font-lock-error
`("Value of :reversed can only be t or nil"
,var)))
(setq current-reversed var)))
;; (2) Process query.
((pred treesit-query-p)
(let ((lang (or default-language current-language)))
(when (null lang)
(signal 'treesit-font-lock-error
`("Language unspecified, use :language keyword or :default-language to specify a language for this query" ,token)))
(when (null current-feature)
(signal 'treesit-font-lock-error
`("Feature unspecified, use :feature keyword to specify the feature name for this query" ,token)))
(push (list token
t
current-feature
current-override
current-reversed
lang)
result)
;; Clears any configurations set for this query.
(setq current-language nil
current-override nil
current-feature nil
current-reversed nil)))
(_ (signal 'treesit-font-lock-error
`("Unexpected value" ,token))))))
(nreverse result))))