Add doc/matlab-tree-sitter.org

Author: JohnC32

doc/matlab-tree-sitter.org

@@ -0,0 +1,160 @@
+# File: doc/matlab-tree-sitter.org
+
+# Copyright 2016-2025 Free Software Foundation, Inc.
+
+#+startup: showall
+#+options: toc:nil
+
+#+title: MATLAB and Tree-Sitter
+#+date: Jun-7-2025
+
+If you search the web for tree-sitter Emacs, you'll see conflicting information on tree-sitter
+because it is evolving quickly. tree-sitter is built into Emacs 30.1 and some of the older links are
+for earlier versions. [[https://tree-sitter.github.io/tree-sitter/][tree-sitter]] shared libraries, libtree-sitter-LANGUAGE.so (.so on Linux, .dll
+on Windows, .dylib on Mac) provide a syntax tree for Emacs:
+
+#+begin_example
+
+   +---------+           +----------------------------+
+   |         |           |                            |
+   |  Emacs  |<=========>| libtree-sitter-LANUGAGE.so |
+   |         |           |                            |
+   +---------+           +----------------------------+
+
+#+end_example
+
+A syntax tree is a formal representation of the MATLAB program, e.g.
+
+#+begin_example
+  MATLAB program             Syntax Tree
+
+   c = a + b                      =
+                                /   \
+                               c     +
+                                   a   b
+#+end_example
+
+*We need a matlab-ts-mode*. The current matlab-mode is classic Emacs major mode that uses Emacs'
+built-in mechanisms for syntax highlighting, indentation, and other language-specific features,
+relying on regular expressions and Emacs' internal parsing capabilities. Creating a new
+matlab-ts=mode based on tree-sitter will enable improved color syntax for the language elements
+(improved font-lock), improved editing/cursor movement, code folding, improved indentation,
+etc. Howwever, to leverage the syntax tree, we need to create a new matlab-ts-mode, see [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Tree_002dsitter-Major-Modes.html][Emacs
+manual, Developing major modes with tree-sitter]] and [[https://www.masteringemacs.org/article/lets-write-a-treesitter-major-mode][this article]]. matlab-ts-mode should also be
+faster than the classic matlab-mode. The cost of using tree-sitter is that it will take more memory
+for each matlab file, approximately 10 times the size of the file. The other cost will be in
+deploying libtree-sitter-matlab.so, which at present is best built from source and this requires a
+C11 compiler.
+
+* Using tree-sitter in Emacs 30.1 with matlab-mode
+
+We can use tree-sitter in Emacs to get improved font-lock and code-folding, though this is not
+ideal. As mentioned above, creating a new matlab-ts-mode would be better.
+
+1. Install matlab tree-sitter
+
+   Note to Windows Emacs users, see
+
+   #+begin_example
+     M-x treesit-install-language-grammar
+     Language: matlab
+     There is no recipe for matlab, do you want to build it interactively? (y or n) y
+     Enter the URL of the Git repository of the language grammar: https://github.com/acristoffers/tree-sitter-matlab
+     Enter the tag or branch (default: default branch): abi/14
+     Enter the subdirectory in which the parser.c file resides (default: "src"):
+     Enter the C compiler to use (default: auto-detect):
+     Enter the C++ compiler to use (default: auto-detect):
+     Install to (default: ~/.emacs.d/tree-sitter):
+   #+end_example
+
+   Notice, that I specified the =abi/14= branch. Emacs is using application binary interface, ABI,
+   version 14 and the current state of tree-sitter is version 15. If you install from the main
+   branch, you'll see /"Warning (treesit): The installed language grammar for matlab cannot be
+   located or has problems (version-mismatch): 15"/.  The ABI version used by Emacs is obtained via
+   =M-: (treesit-library-abi-version)=. See
+   https://github.com/acristoffers/tree-sitter-matlab/issues/24
+
+   After installing matlab tree-sitter open a =*.m= and run =M-: (treesit-available-p)= which
+   should return =t=.
+
+
+1. Make sure you have melpa available, i.e. your =~/.emacs= should contain:
+
+   #+begin_src emacs-lisp
+     (require 'package)
+     (add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/"))
+   #+end_src
+
+2. Install the older tree-sitter package (needed to get tree-sitter-hl-mode and ts-fold), =M-x
+   list-packages= and then click on the following and install them:
+
+   - tree-sitter
+   - tree-sitter-langs
+
+   and these which are needed for ts-fold:
+
+   - s
+   - fringe-helper
+
+3. Install ts-fold. The install uses https://github.com/radian-software/straight.el which isn't
+   provided with Emacs 30. To manually install, download the zip file and extract to some location,
+   e.g. ~/emacs-ts-fold, in Emacs
+
+   #+begin_example
+     M-: (add-to-list 'load-path "~/emacs-ts-fold")
+     M-: (byte-recompile-directory "~/emacs-ts-fold" 0)
+     M-: (require 'ts-fold)
+   #+end_example
+
+   and add to =~/.emacs=
+
+   #+begin_src emacs-lisp
+     (add-to-list 'load-path "~/emacs-ts-fold")
+     (require 'ts-fold)
+   #+end_src
+
+4. Now the tree-sitter capabilities are available. For example,
+
+   - Visit some_file.m
+   - M-x tree-sitter-mode
+   - M-x tree-sitter-hl-mode (for improved font-lock)
+   - Place the point on a 'function' keyword and then =M-x ts-fold-close= and
+     then =M-x ts-fold-open=.
+
+* treesit-fold with matlab-mode in Emacs 30.1 doesn't work
+
+1. Start with no customizations
+
+   #+begin_src bash
+     rm -rf ~/.emacs.d
+     rm ~/.emacs
+   #+end_src
+
+3. Install tree-sitter-matlab
+
+   #+begin_example
+     M-x treesit-install-language-grammar
+     Language: matlab
+     There is no recipe for matlab, do you want to build it interactively? (y or n) y
+     Enter the URL of the Git repository of the language grammar: https://github.com/acristoffers/tree-sitter-matlab
+     Enter the tag or branch (default: default branch): abi/14
+     Enter the subdirectory in which the parser.c file resides (default: "src"):
+     Enter the C compiler to use (default: auto-detect):
+     Enter the C++ compiler to use (default: auto-detect):
+     Install to (default: ~/.emacs.d/tree-sitter):
+   #+end_example
+
+4. Install treesit-fold
+
+   treesit-fold from M-x list-packages
+
+5. Visit foo.m containing:
+
+   #+begin_src matlab
+     function out = foo(in)
+         out = in
+     end
+   #+end_src
+
+Running =M-x treesit-fold-close= on the function keyword results in error: "Ignored, no tree-sitter
+   parser in current buffer"