Skip to content

juki-pub/stumpbuffer

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

KeyCommand
nMove to next line
pMove to previous line
C-nMove to next frame
C-pMove to previous frame
TABMove to next group
BACKTABMove to previous group
gUpdate
RETFocus and switch to
mMark
uUnmark
UUnmark all
% rMark windows whose title matches a regex
% RMark windows by role (defaults to current windows role, use prefix arg to force prompt)
% cMark windows by class (same)
% iMark windows by instance (same)
% fMark windows in the same frame as the current window
% gMark windows in the same group as the current window
dMark for deletion (asks window to close itself)
kMark for kill (forces window to die; you should usually use delete instead)
*Change all * marks to a different character
xExecute marks
DDelete window, frame or group
KKill window (force it to die)
NRename
PPull (move marked windows here)
TThrow (move marked windows there)
qQuit
sSplit frame vertically (only when point on frame name or window)
SSplit frame horizontally (only when point on frame name or window)
QMake a frame the only frame in the group
CCreate new group (takes marked windows with it)
fToggle frame name display
rRenumber group, frame or window
`Cycle filter groups
^Select filter group by name
/ hPush a quick filter to hide hidden groups
/ HPush a quick filter to only show hidden groups
/ rPush a quick filter to only show windows with a title matching a regex
/ cPush a quick filter to only show windows with a specific class
/ RPush a quick filter to only show windows with a specific role
/ iPush a quick filter to only show windows with a specific instance
/ gPush a quick filter to hide the current group
/ GPush 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.

About

An IBuffer inspired tool to control Stumpwm from Emacs

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published