programming languages.
@defun treesit-available-p
-This function returns non-nil if tree-sitter features are available
-for the current Emacs session.
+This function returns non-@code{nil} if tree-sitter features are
+available for the current Emacs session.
@end defun
To be able to parse the program source using the tree-sitter library
details about the failure.
@defun treesit-language-available-p language &optional detail
-This function returns non-nil if the language definitions for
+This function returns non-@code{nil} if the language definitions for
@var{language} exist and can be loaded.
-If @var{detail} is non-nil, return @code{(t . nil)} when
-@var{language} is available, and @code{(nil . @var{date})} when it's
+If @var{detail} is non-@code{nil}, return @code{(t . nil)} when
+@var{language} is available, and @code{(nil . @var{data})} when it's
unavailable. @var{data} is the signal data of
@code{treesit-load-language-error}.
@end defun
@var{library-base-name} is the basename of the dynamic library's file name,
(usually, @file{libtree-sitter-@var{language}}), and
@var{function-name} is the function provided by the library
-(usually, @code{tree_sitter_@var{language}}). For example,
+(usually, @code{tree_sitter_@var{language}}). For example,
@example
(cool-lang "libtree-sitter-coool" "tree_sitter_cooool")
@section Using Tree-sitter Parser
@cindex tree-sitter parser, using
-This section described how to create and configure a tree-sitter
+This section describes how to create and configure a tree-sitter
parser. In Emacs, each tree-sitter parser is associated with a
buffer. As the user edits the buffer, the associated parser and the
syntax tree are automatically kept up-to-date.
to handle a multi-language buffer; instead, set the ranges in which the
parser should operate. @xref{Multiple Languages}.
-Because a parser parses lazily, when the user or a Lisp programs
+Because a parser parses lazily, when the user or a Lisp program
narrows the buffer, the parser is not affected immediately; as long as
the mode doesn't query for a node while the buffer is narrowed, the
parser is oblivious of the narrowing.
When @var{pos} is after all the text in the buffer, technically there
is no node after @var{pos}. But for convenience, this function will
return the last leaf node in the parse tree. If @var{strict} is
-non-nil, this function will strictly comply to the semantics and
+non-@code{nil}, this function will strictly comply to the semantics and
return @var{nil}.
Example:
is the string text.
This function returns @code{nil} if there is no @var{n}'th child.
-@var{n} could be negative, e.g., -1 represents the last child.
+@var{n} could be negative, e.g., @code{-1} represents the last child.
@end defun
@defun treesit-node-children node &optional named
@defun treesit-search-forward-goto node predicate &optional start backward all
This function moves point to the start or end of the next node after
@var{node} in the buffer that matches @var{predicate}. If @var{start}
-is non-nil, stop at the beginning rather than the end of a node.
+is non-@code{nil}, stop at the beginning rather than the end of a node.
This function guarantees that the matched node it returns makes
progress in terms of buffer position: the start/end position of the
@end group
@end example
-If @var{process-fn} is non-nil, instead of returning the matched
+If @var{process-fn} is non-@code{nil}, instead of returning the matched
nodes, this function passes each node to @var{process-fn} and uses the
returned value instead. If non-@code{nil}, @var{limit} is the number of
levels to go down from @var{root}.
the @var{n}'th child doesn't have a field name.
Note that @var{n} counts both named and anonymous child. And @var{n}
-could be negative, e.g., -1 represents the last child.
+could be negative, e.g., @code{-1} represents the last child.
@end defun
@defun treesit-child-count node &optional named
@end group
@end example
-As mentioned earlier, @var{query} could contain multiple patterns. For
-example, it could have two top-level patterns:
+As mentioned earlier, @var{query} could contain multiple patterns.
+For example, it could have two top-level patterns:
@example
@group
@noindent
tree-sitter only matches arrays where the first element equals to
the last element. To attach a predicate to a pattern, we need to
-group then together. A predicate always starts with a @samp{#}.
+group them together. A predicate always starts with a @samp{#}.
Currently there are two predicates, @code{#equal} and @code{#match}.
@deffn Predicate equal arg1 arg2
@cindex multiple languages, parsing with tree-sitter
@cindex parsing multiple languages with tree-sitter
Sometimes, the source of a programming language could contain snippets
-of other languages; HTML + CSS + JavaScript is one example. In that
-case, text segments written in different languages need to be assigned
-different parsers. Traditionally, this is achieved by using
-narrowing. While tree-sitter works with narrowing (@pxref{tree-sitter
-narrowing, narrowing}), the recommended way is instead to set regions
-of buffer text in which a parser will operate.
+of other languages; @acronym{HTML} + @acronym{CSS} + JavaScript is one
+example. In that case, text segments written in different languages
+need to be assigned different parsers. Traditionally, this is
+achieved by using narrowing. While tree-sitter works with narrowing
+(@pxref{tree-sitter narrowing, narrowing}), the recommended way is
+instead to set regions of buffer text in which a parser will operate.
@defun treesit-parser-set-included-ranges parser ranges
This function sets up @var{parser} to operate on @var{ranges}. The
ranges for the embedded languages, and then parses the embedded
languages.
-Suppose we need to parse a very simple document that mixes HTML, CSS
-and JavaScript:
+Suppose we need to parse a very simple document that mixes
+@acronym{HTML}, @acronym{CSS} and JavaScript:
@example
@group
@end group
@end example
-We first parse with HTML, then set ranges for CSS and JavaScript:
+We first parse with @acronym{HTML}, then set ranges for @acronym{CSS}
+and JavaScript:
@example
@group
@end group
@end example
-We use a query pattern @w{@code{(style_element (raw_text) @@capture)}} to
-find CSS nodes in the HTML parse tree. For how to write query
-patterns, @pxref{Pattern Matching}.
+We use a query pattern @w{@code{(style_element (raw_text) @@capture)}}
+to find @acronym{CSS} nodes in the @acronym{HTML} parse tree. For how
+to write query patterns, @pxref{Pattern Matching}.
@node Tree-sitter major modes
@section Developing major modes with tree-sitter
@section Tree-sitter C API Correspondence
Emacs' tree-sitter integration doesn't expose every feature
-provided by the tree-sitter's C API. Missing features include:
+provided by tree-sitter's C API. Missing features include:
@itemize
@item
@item
Setting the logger for a parser.
@item
-Printing a DOT graph of the syntax tree to a file.
+Printing a @acronym{DOT} graph of the syntax tree to a file.
@item
-Coping and modifying a syntax tree. (Emacs doesn't expose a tree
+Copying and modifying a syntax tree. (Emacs doesn't expose a tree
object.)
@item
Using (row, column) coordinates as position.
@item
-Updating a node with changes. (In Emacs, retrieve a new node instead
+Updating a node with changes. (In Emacs, retrieve a new node instead
of updating the existing one.)
@item
Querying statics of a language definition.
projects / emacs.git / commitdiff