Where parallels cross

Interesting bits of life

Moldable Emacs: what is the public API of this Elisp buffer?

Lately I have been reading the Elisp source code that ships with Emacs 29. The addition (and the general excitement) of treesit.el made me willing to come up with a plan to support that in my moldable-emacs.

I like that Emacs contributors keep a stoic discipline in distinguish public and private functions in a library. The convention is that my-function belongs to the public API while my--function is not.

As a user often I care only about the public interface. So I thought: wouldn't be nice to have a view/mold that shows me only what I need?

You can see in the below video how the resulting mold helped me exploring cl-lib.

The code was just some filtering of the tree-sitter concrete tree really.

For instance, this is how I filer defcustoms:

(defun me-elisp-defcustoms (tree)
  "Extract defcustoms from TREE.

>> (me-elisp-defcustoms
  '((:type something-else)
    (:type list
     :text \"(defcustom test 1 \\\"HI\\\")\"
     :begin 321 :end 354
     :buffer \"test.el\"
     :buffer-file \"/tmp/test.el\"
     :mode emacs-lisp-mode
     :level 0)))
=> ((:type list
     :text \"(defcustom test 1 \\\"HI\\\")\"
     :begin 321 :end 354
     :buffer \"test.el\"
     :buffer-file \"/tmp/test.el\"
     :mode emacs-lisp-mode
     :level 0))"
   (and (equal 'list (plist-get it :type))
        (s-starts-with-p "(defcustom " (plist-get it :text)))

It feels a hack but it is working fine :) Note the doctest in the documentation!

This filters out some of the complexity of Elisp libraries I don't know.

I hope to generalize this little by little for other languages so I can get the essence of the files I need to read.

And I wonder if this could help me evaluate the quality of an API as well. It may be of help if Emacs warns me while I write my library and tells me that the API is getting bloated, no?

Anyway, this has been good for my Elisp exploration.

Happy exploring!