procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add manual entry for treesit-primary-parser

Browse source 
* doc/lispref/parsing.texi (Multiple Languages): Add entry.
* etc/NEWS (Example): Add news.
This commit is contained in:
Yuan Fu 2024-06-04 21:32:19 -07:00
parent 2ee3edce3f
commit 636461686f
No known key found for this signature in database
GPG key ID: 56E19BC57664A442
2 changed files with 26 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

22
doc/lispref/parsing.texi
View file

@ -1683,16 +1683,34 @@ instead to specify regions of buffer text (i.e., ranges) in which a
parser will operate. This section describes functions for setting and
getting ranges for a parser.
@cindex primary parser
Generally when there are multiple languages at play, there is a
``primary'', or ``host'' language. The parser for this language---the
@dfn{primary parser}, parses the entire buffer. Parsers for other
languages are ``embedded'' or ``guest'' parsers, which only work on part
of the buffer. The parse tree of the primary parser is usually used to
determine the ranges in which the embedded parsers operate.
@vindex treesit-primary-parser
Major modes should set @var{treesit-primary-parser} to the primary
parser before calling @code{treesit-major-mode-setup}, so that Emacs can
configure the primary parser correctly for font-lock and other features.
Lisp programs should call @code{treesit-update-ranges} to make sure
the ranges for each parser are correct before using parsers in a
buffer, and call @code{treesit-language-at} to figure out the language
responsible for the text at some position. These two functions don't
work by themselves, they need major modes to set
@code{treesit-range-settings} and
@code{treesit-language-at-point-function}, which do the actual work.
@var{treesit-range-settings} and
@var{treesit-language-at-point-function}, which do the actual work.
These functions and variables are explained in more detail towards the
end of the section.
@b{In short}, multi-language major modes should set
@var{treesit-primary-parser}, @var{treesit-range-settings}, and
@var{treesit-language-at-point-function} before calling
@code{treesit-major-mode-setup}.
@heading Getting and setting ranges
@defun treesit-parser-set-included-ranges parser ranges

6
etc/NEWS
View file

@ -2872,6 +2872,12 @@ only return parsers for that language. If TAG is given, only return
parsers with that tag. Note that passing nil as tag doesn't mean return
all parsers, but rather "all parsers with no tags".
+++
*** New variable 'treesit-primary-parser'.
This variable should be set by multi-langauge major modes before calling
'treesit-major-mode-setup', in order for tree-sitter integration
functionalities to operate correctly.
* Changes in Emacs 30.1 on Non-Free Operating Systems