Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/juki-pub/stumpbuffer
An IBuffer inspired tool to control Stumpwm from Emacs
https://github.com/juki-pub/stumpbuffer
emacs stumpwm
Last synced: 3 months ago
JSON representation
An IBuffer inspired tool to control Stumpwm from Emacs
- Host: GitHub
- URL: https://github.com/juki-pub/stumpbuffer
- Owner: juki-pub
- License: gpl-2.0
- Created: 2017-11-24T11:42:55.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2017-12-09T14:06:16.000Z (about 7 years ago)
- Last Synced: 2024-08-02T21:38:34.764Z (6 months ago)
- Topics: emacs, stumpwm
- Language: Emacs Lisp
- Homepage:
- Size: 153 KB
- Stars: 14
- Watchers: 6
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: readme.org
- License: COPYING
Awesome Lists containing this project
- awesome-stumpwm - stumpbuffer - An IBuffer inspired tool to control Stumpwm from Emacs (Modules)
README
* 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
#+BEGIN_EXAMPLE
((field-key &optional width title format-fn)
...)
#+END_EXAMPLE
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
#+BEGIN_EXAMPLE
((faces . things)
...)
#+END_EXAMPLE
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
#+BEGIN_EXAMPLE
'((stumpbuffer-window-visible-p . bold)
(stumpbuffer-window-hidden-p . shadow))
#+END_EXAMPLE
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
#+BEGIN_EXAMPLE
(add-to-list 'stumpbuffer-window-faces
'((:where :class :is "Emacs") . font-lock-string-face))
#+END_EXAMPLE
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),
#+BEGIN_EXAMPLE
'(("Everything")
("No hidden groups"
(:hide-groups :satisfying stumpbuffer-group-hidden-p))
("Only hidden groups"
(:show-groups :satisfying stumpbuffer-group-hidden-p)))
#+END_EXAMPLE
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:
#+BEGIN_EXAMPLE
(defun stumpbuffer-group-hidden-p (group)
(getf group :hiddenp))
#+END_EXAMPLE
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 [[https://github.com/juki-pub/stumpbuffer/wiki/Extending][the wiki]].