* 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]].