To install this package, run in Emacs:
M-x package-install RET ilist RET
This is a little library package that can "display a list in an ibuffer fashion". The core functionality it provides is a function that can accept a list, and produce a string showing the contents of the list according to the specifications of columns and groups.
The one main function this package provides is
ilist-string. It is
called as follows.
(ilist-string LIST COLUMNS GROUPS &optional DISCARD-EMPTY-P SORTER NO-TRAILING-SPACE)
Like in Ibuffer, the user can specify columns to display. Each column comprises the following specifications:
Like in Ibuffer, we can group elements together in the display. One difference with Ibuffer is that elements that are not in any group are ignored. If one wants a "default" group, specify that explicitly. The specifications of GROUPS are as follows.
So a default group just uses a function that always returns t, and is put at the end of the list GROUPS.
Empty groups might or might not be displayed, depending on the value of DISCARD-EMPTY-P.
An automatic filter group is a function that can give labels to elements in a list. These labels will be used to group elements automatically: the elements with the same label will be grouped together, automagically. Besides, an automatic filter group is also responsible for sorting group labels, and for giving a default label, if no labels are specified for some element.
To be precise, an automatic filter group is a function with the
(ELEMENT &optional TYPE). The optional argument
says what the caller wants from the function:
default, the function should return a default label.
sorter, the function should return a function with two arguments,
Y. This returned function should return a non-nil value if and only if group
Xshould be placed earlier than group
So, for example, the call
(FUN t 'default) should produce the
(FUN t 'sorter) should return the function used to
sort groups, and
(FUN ELEMENT) should return the label for
FUN is an automatic filter group.
If one wants to define ones own automatic filter group, then the macro
ilist-define-automatic-group, or the shorter alias
ilist-dag, might come in handy.
In case you wonder, this dag has nothing to do with an directed acyclic graph; it is just an abbreviation to save some typing. The coincidence of the names is a misfortune.
This macro is called as follows.
(ilist-dag NAME DEFAULT SORTER &rest BODY)
DEFAULT: This is also a string. It is used to label elements for which this automatic group returns nil as its label.
Why not just let the automatic group function give the default label instead of nil, then? Well, people make mistakes all the time, at least I do. So I think this mechanism can help people to remember give a default label for elements.
SORTER: This can be a symbol, or an s-expression.
If it is a symbol, it will be used as the sorting function of the group labels. Note that one does not have to quote this symbol, though you can still quote it.
If it is an s-expression., it will be used to define a function
ilist-automatic-group-NAME-sorter, which then becomes the sorting
function. The variables
Y are bound to the labels to sort
in this expression. The sorter function should return a non-nil
value if and only if the group labelled
X should be displayed
before the group labelled
For the convenience of package-users, this package also provides some
auxiliary functions to operate on the displayed list. One is
ilist-map-lines. It is called as follows.
(ilist-map-lines FUN PREDICATE START END NO-SKIP-INVISIBLE)
It might be desired to move between the displayed list items in a
cyclic manner, that is, assuming the top of the buffer is identified
with the bottom of the buffer. So the package provides four functions
for moving. These functions all have an argument
if that argument is non-nil, then invisible lines won't skipped.
ilist-forward-line: Move between lines. One can control whether to skip group headers or to move cyclicly, through the function parameters.
ilist-forward-group-header: Move between group headers.