StumpBuffer

An IBuffer inspired tool to control Stumpwm from Emacs.

Uses a lot of Stumpwms internals. This can’t really be avoided since Stumpwm doesn’t expose everything for programmatic access. Using the built-in commands would generally not work as those tend to require the target to be focused, while StumpBuffer must be able to execute them remotely.

Installing

Ensure that you have stumpish available. Load emacs/stumpbuffer/ in Emacs and cl/stumpbuffer/ in Stumpwm.

Use

Use M-x stumpbuffer to open the buffer. This should show all groups and windows. M-x stumpbuffer-other-frame can be used to open the buffer in another frame, which will be killed when exiting the stumpbuffer.

Key	Command
n	Move to next line
p	Move to previous line
C-n	Move to next frame
C-p	Move to previous frame
TAB	Move to next group
BACKTAB	Move to previous group
g	Update
RET	Focus and switch to
m	Mark
u	Unmark
U	Unmark all
% r	Mark windows whose title matches a regex
% R	Mark windows by role (defaults to current windows role, use prefix arg to force prompt)
% c	Mark windows by class (same)
% i	Mark windows by instance (same)
% f	Mark windows in the same frame as the current window
% g	Mark windows in the same group as the current window
d	Mark for deletion (asks window to close itself)
k	Mark for kill (forces window to die; you should usually use delete instead)
*	Change all * marks to a different character
x	Execute marks
D	Delete window, frame or group
K	Kill window (force it to die)
N	Rename
P	Pull (move marked windows here)
T	Throw (move marked windows there)
q	Quit
s	Split frame vertically (only when point on frame name or window)
S	Split frame horizontally (only when point on frame name or window)
Q	Make a frame the only frame in the group
C	Create new group (takes marked windows with it)
f	Toggle frame name display
r	Renumber group, frame or window
`	Cycle filter groups
^	Select filter group by name
/ h	Push a quick filter to hide hidden groups
/ H	Push a quick filter to only show hidden groups
/ r	Push a quick filter to only show windows with a title matching a regex
/ c	Push a quick filter to only show windows with a specific class
/ R	Push a quick filter to only show windows with a specific role
/ i	Push a quick filter to only show windows with a specific instance
/ g	Push a quick filter to hide the current group
/ G	Push a quick filter to only show the current group
\	Pop the quick filter stack. Positive numeric argument pops multiple, negative pops all.
<	Dump group to file
>	Restore group from file

The customization option stumpbuffer-quit-window-after-command determines whether the buffer should be killed when executing certain commands (such as focusing a window). stumpbuffer-show-frames-p can be set to nil to hide frames from the list.

By default everything will be sorted by number. Set stumpbuffer-data-ordered-p to nil if you prefer to get it in whatever order Stumpwm uses (which should be by recency, but that’s an implementation detail).

Window row format

The variable stumpbuffer-window-format determines which fields to show for windows. It should be a list of three element lists in form

((field-key &optional width title format-fn)
 ...)

The field-key is the key returned by Stumpwm. width is the number of characters to show. The last field can have width of nil. title is the title to show in the header. format-fn can be a custom function to format the fields value. The function takes a single argument – the value – and returns a string that should be shown in its place.

Frame and group name format

The variables stumpbuffer-frame-name-format and stumpbuffer-group-name-format control the format of frame and group names. They should be lists of lists in form

((faces . things)
 ...)

Where faces is the name of a face or a list of face names. things is a list of things to insert. They can be

Strings

Inserted as they are.

Keywords

The key is looked up in the frame or group plist retrieved from Stumpwm.

A list (:call fn)

Call fn with the plist. If it returns nil, insert nothing. Otherwise insert the result.

Faces

Window names can be highlighted with custom faces. The variable stumpbuffer-window-faces is an alist of (filter . face) pairs. The face will be used for windows that match filter.

The filter can be either a function or a filter like described below.

For example, the default value

'((stumpbuffer-window-visible-p . bold)
  (stumpbuffer-window-hidden-p . shadow))

will highlight all visible windows with the bold face, and hidden windows (iconified windows) with shadow. If you wanted to highlight all Emacs windows with font-lock-string-face, you could put

(add-to-list 'stumpbuffer-window-faces
             '((:where :class :is "Emacs") . font-lock-string-face))

in you Emacs init-file. Notice that all matching faces will be added to the windows, in the order they appear in. So in this case visible Emacs windows will have both bold and font-lock-string-face.

Filters

The variable stumpbuffer-filter-groups contains an alist of filter groups. Each group should be a cons cell of a name (a string) and a list of filters in form (what . how). what should be either :hide-groups, :show-groups, :hide-windows or :show-windows. The :hide- variants hide matching windows or groups, while the :show- variants hide non-matching ones.

how is the actual filter. The currently implemented filters are:

(:satisfying fn)

Matches if calling fn on the group or window plist returns true.

(:where field :matches regex)

Matches if field in the group or window plist matches the regular expression regex.

(:where field :is value)

Matches if field in the group or window plist is equal to value.

(:or filter1 ... filtern)

Matches if one of the filters match.

(:and filter1 ... filtern)

Matches if all of the filters match.

(:not filter)

Matches if filter doesn’t match.

For example (the default value),

'(("Everything")
  ("No hidden groups"
   (:hide-groups :satisfying stumpbuffer-group-hidden-p))
  ("Only hidden groups"
   (:show-groups :satisfying stumpbuffer-group-hidden-p)))

This defines three filter groups. The first one (the default group) will show everything. The second one hides all hidden groups. The third one only shows hidden groups. stumpbuffer-group-hidden-p is a very simple function:

(defun stumpbuffer-group-hidden-p (group)
  (getf group :hiddenp))

Stumpwm provides :hiddenp in group plists to tell whether it is a hidden group.

Quick filters

Quick filters are filters that are pushed onto a buffer local stack. Their syntax is the same as predefined filters. They can be pushed to the stack with key bindings starting with / and popped with \.

For example, to quickly filter down to windows whose title contains the word “emacs”, use / r emacs RET. Using \ will remove the filter.

The customization option stumpbuffer-persistent-quick-filters-p can be set to t to keep quick filters when closing the buffer.

Extending

See the wiki.