To install this package from Emacs, use package-install
or list-packages
.
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
signature: (ELEMENT &optional TYPE)
. The optional argument TYPE
says what the caller wants from the function:
ELEMENT
.default
, the function should return a
default label.sorter
, the function should return a
function with two arguments, X
and Y
. This returned function
should return a non-nil value if and only if group X
should be
placed earlier than group Y
.
So, for example, the call (FUN t 'default)
should produce the
default label, (FUN t 'sorter)
should return the function used to
sort groups, and (FUN ELEMENT)
should return the label for
ELEMENT
, where 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)
ilist-automatic-group-NAME
.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 should be a function, or the symbol of a function.
This will be used as the sorting function of the group labels. The sorter function should accept two arguments, and should return a non-nil value if and only if the group labelled by the first argument should be displayed before the group labelled by the second argument.
Emacs is old, and its age shows from time to time.
As an example, Emacs usually measures lengths of strings by the numbers of characters contained in the strings. In most situations this is not a problem, but in some cases, for example when the string contains Chinese characters, this measurement is insufficient for the correct alignment inside tables.
In the beginning, I used the function string-width
to measure the
widths of strings, but as its documentation says, this function only
returns an approximation to the actual width. This is changed in the
version 0.2 of the package.
Now the package uses the function string-pixel-width
to measure the
widths of strings in pixels. Since working with actual pixels
requires more computation, and as it does not improve the user
experience for users who are fine with the approximation provided by
string-width
, I decide to let the users control whether or not to
work with pixels by the variable: ilist-pixel-precision
. If this
variable is not nil
, the package works with pixels rather than
characters, and should provide better alignment and truncation.
Moreover, if the value of this variable is the symbol precise
, then
the paddings will use display properties to produce pixel-exact spaces
so that the alignment is precise and perfect. See the Info node
"(elisp) Display Property" for more details.
However, on text terminals, this may not work as expected, as Emacs has no control over exact pixels on a text terminal (my guess).
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 NO-SKIP-INVISIBLE
;
if that argument is non-nil, then invisible lines won't skipped.
ilist-backward-line
ilist-forward-line
: Move between lines. One can control whether
to skip group headers or to move cyclicly, through the function
parameters.ilist-backward-group-header
ilist-forward-group-header
: Move between group headers.The packages that use this library IList, which I know of, are listed here:
If you know about other packages that use IList, or if you write a package using IList, it is welcomed to suggest to list those packages here.
ilist-0.2.tar.lz | 2024-Feb-13 | 37.1 KiB |
ilist-0.1.tar.lz | 2021-Dec-29 | 221 KiB |