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.

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.