Verbs plugins offer

(commands:define (name) "doc" body …)plugin

Does. Defines a command: a procedure you can call as (name), bind to a key by its name, and run with M-x.

Underneath. A macro exported by commands. It expands to one definition, (define name (commands:register! 'name "doc" (lambda () body …))); register! adds the command to commands’ table as the caller’s entry and returns the procedure. Keys bind the name, so evaluating the form again with C-M-x changes what the key runs.

(commands:define (say-hello)
  "Insert a greeting at point."
  (buffers:insert! "Hello, world!"))

(defun say-hello ()
  "Insert a greeting at point."
  (interactive)
  (insert "Hello, world!"))

Where Tuna differs. A command goes when the plugin that defined it turns off. An Emacs function stays defined until fmakunbound or restart.

(commands:run! name arg …)plugin

Does. Runs a command by its name.

(commands:run! 'magit-status)

(call-interactively #'magit-status)

(keys:bind! key command [mode]), (keys:unbind! key [mode])plugin

Does. Binds a key in the global map, or in a mode’s map when mode is given. command is a command’s name (a symbol) or a procedure. unbind! removes your binding, or hides another owner’s while you are on.

(keys:bind! "C-c h" 'say-hello)
(keys:bind! "g" 'magit-status 'git-status-mode)
(keys:unbind! "C-z")

(keymap-global-set "C-c h" #'say-hello)
(keymap-set git-status-mode-map "g" #'magit-status)
(keymap-global-unset "C-z")

Where Tuna differs. A mode’s bindings are named by the mode, not by a keymap variable the mode must define. Removing the line, or turning the plugin off, removes the binding and shows the one it covered.

(modes:define-major name "doc" [parent]), (modes:define-minor name "doc")plugin

Does. Declares a major or minor mode. The declaration is how modes knows which plugin a mode came from: while that plugin is off, a buffer in its major mode is treated as Fundamental mode, and gets its mode back when the plugin returns.

(modes:define-major git-status-mode "Shows the repository's status.")
(modes:define-minor flymake-mode "Checks the buffer as you type.")

(define-derived-mode git-status-mode special-mode "Git-Status"
  "Shows the repository's status.")
(define-minor-mode flymake-mode "Checks the buffer as you type.")

Where Tuna differs. An Emacs mode is a function that sets up the buffer when called. A Tuna mode is a declared name; what it means (bindings, faces, scoped options and hooks) is attached to the name by whoever wants to, through the verbs here.

(modes:set-major! id mode), (modes:enable-minor! id mode), (modes:disable-minor! id mode), (modes:major id)plugin

Does. Set and read a buffer’s modes. A minor mode enabled through enable-minor! is the caller’s: it is tied with on-caller-end, so it goes when the caller turns off.

(modes:set-major! id 'git-status-mode)
(modes:enable-minor! id 'flymake-mode)
(modes:major id)   ; => git-status-mode

(with-current-buffer buf (git-status-mode))
(with-current-buffer buf (flymake-mode 1))
(buffer-local-value 'major-mode buf)

(modes:set! 'mode option v) is described with options.

(faces:define name attributes "doc"), (faces:set! face attributes), (faces:attributes face)plugin

Does. define declares a face with its default look; set! gives it your look, as a layer, so a theme that turns off leaves the default; attributes returns the winning look, for the display. Attributes are a property list of plain data: foreground, background, bold, italic, underline. The display turns them into CSS.

Underneath. Faces are their own contract, not the display’s, because highlighters, checkers and themes use them whatever the display is.

(faces:define flymake-error '(underline (wave "#dc322f"))
  "Text a checker found an error in.")
(faces:set! 'highlight '(foreground "#b58900"))

(defface flymake-error '((t :underline (:style wave :color "Red1")))
  "Face used for marking error regions.")
(set-face-attribute 'highlight nil :foreground "#b58900")

Where Tuna differs. A theme in Emacs is a set of face settings applied with enable-theme and removed with disable-theme. In Tuna any faces:set! is a layer, so every plugin’s face settings behave like a theme’s.

buffers:current, (buffers:with id body …)plugin

Does. current is the current buffer’s id, a dynamic value. with runs the body with id current.

(buffers:with view
  (buffers:erase!)
  (buffers:insert! (render)))

(with-current-buffer view
  (erase-buffer)
  (insert (my-render)))

Text in the current bufferplugin

(buffers:insert! string), (buffers:erase!), (buffers:delete! from to), (buffers:goto! pos), (buffers:point), (buffers:size), (buffers:text), (buffers:line).

Does. Insert at point, empty the buffer, delete a range, move point, and read point, size, the whole text and the current line. Positions count characters from 0.

(buffers:insert! "Hello")
(buffers:goto! (buffers:size))
(buffers:delete! 0 5)
(buffers:line)

(insert "Hello")
(goto-char (point-max))
(delete-region 1 6)
(thing-at-point 'line)

Where Tuna differs. Emacs positions start at 1; Tuna’s at 0, as Scheme strings do.

(buffers:create name) and (buffers:view name)plugin

Does. create returns the user’s buffer of that name, made if needed; no plugin closes it. view returns the caller’s view of that name, made if needed; it goes when the caller turns off and stays across its reloads. A buffer the user made with that name is never taken by a view.

(buffers:create "*shell*")
(buffers:view "*git-status*")

(get-buffer-create "*shell*")
(get-buffer-create "*git-status*")

Where Tuna differs. Emacs has one procedure for both, and a package’s status buffer stays after the package is unloaded.

A buffer as a wholeplugin

(buffers:list), (buffers:live? id), (buffers:name id), (buffers:file id), (buffers:internal? id), (buffers:text id), (buffers:kill! id), (buffers:scope).

Does. List the buffers; ask whether one is live; its name, its visited file, whether it is internal (its name starts with a space); its text; kill it (the hook kill-query-hook may refuse); and scope, the current buffer’s scope, for a hook entry or layer meant for that buffer only.

(remp buffers:internal? (buffers:list))
(buffers:kill! id)

(seq-remove (lambda (b) (string-prefix-p " " (buffer-name b))) (buffer-list))
(kill-buffer buf)

(buffers:set-faces! id spans), (buffers:set-margin! id marks)plugin

Does. Give a buffer your faces, each span (from to face), or your margin marks, each (line text face). Each call replaces your whole set for that buffer; '() removes it. On a dead buffer they do nothing, so a late worker result is harmless. When the buffer is killed, every plugin’s faces and marks on it go.

(buffers:set-faces! id '((0 5 flymake-error) (12 17 flymake-error)))
(buffers:set-margin! id '((3 "!" flymake-error)))

(let ((ov (make-overlay 1 6 buf)))
  (overlay-put ov 'face 'flymake-error))
(overlay-put ov 'before-string
  (propertize "!" 'display '((margin left-margin) "!")))

Where Tuna differs. Emacs makes one overlay object at a time and the package must delete its overlays itself. Tuna replaces a caller’s whole set at once, which suits a worker that computes a buffer’s spans in one go, and removes it with the caller.

buffers:after-change-hook, buffers:killed-hook, buffers:kill-query-hookplugin

Does. Called after each change (with id, position, deleted text, inserted text); after a kill (with the id); before a kill (with the id; an entry returning #f refuses).

(add-hook! buffers:after-change-hook (lambda (id . _) (highlight! id)))

(add-hook 'after-change-functions #'my-after-change)

(display:add-mode-line! procedure), (display:show-popup! items selected), (display:hide-popup!)plugin

Does. Contribute to what is drawn: a mode-line item (procedure gets a buffer id and returns a string or #f); a popup list with one selected item; hide the popup. Each is the caller’s and goes with it. Because these write core state, the next frame is drawn with them.

(display:add-mode-line! (lambda (id) (and (modified? id) "**")))
(display:show-popup! '("apple" "apricot") 0)

(add-to-list 'mode-line-misc-info '(:eval (and (buffer-modified-p) "**")))
(company-pseudo-tooltip-show-at-point 0 (length candidates) 0)

(layout:show! id [window]), (layout:selected-buffer)plugin

Does. Show a buffer in a window (the selected one by default); the buffer of the selected window.

(layout:show! view)

(pop-to-buffer view)

(processes:start! id command), (processes:start-own name command)plugin

Does. start! starts the user’s process for buffer id; killing that buffer ends it. start-own starts a process the caller needs for itself (a language server), which ends when the caller does; it makes something new, hence no !.

(processes:start! id "bash -i")
(define server (processes:start-own "lsp" "clangd"))

(make-process :name "shell" :buffer buf :command '("bash" "-i"))
(make-process :name "lsp" :command '("clangd"))

Where Tuna differs. Emacs ends its processes at exit, asking first. Tuna keeps the user’s processes and reattaches them at the next start, as tmux does.

(processes:follow! id on-output), (processes:send! id string), (processes:running? id)plugin

Does. follow! calls on-output with each new piece of the process’s output, once, in order, on the editor thread. send! writes to its input. running? asks whether it runs.

Underneath. Each process lives in a small helper program that owns its pipes and keeps its output with offsets. follow! starts the service’s reader worker as the caller, so a reload of the terminal stops the reader and the next run’s follow! resumes from the offset already delivered. Nothing is lost or repeated, across reloads and crashes.

(processes:follow! id (lambda (text) (buffers:with id (buffers:insert! text))))
(processes:send! id "ls\n")

(set-process-filter proc (lambda (p s) (with-current-buffer (process-buffer p) (insert s))))
(process-send-string proc "ls\n")

list-processesplugin

Does. A command listing every running process.

(commands:run! 'list-processes)

(list-processes)