GNU-devel ELPA - ilist

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
	      SHOW-ITEM-NUM-P)

• LIST is the list that the user wants to display
• COLUMNS and GROUPS are described in the following sections
• DISCARD-EMPTY-P determines whether to display empty groups or not
• SORTER is either nil, or a function with two arguments which returns non-nil if and only if the first argument should be sorted before the second argument. This is used to sort the elements in the list, before grouping happens. To sort groups, see the section on groups.
• NO-TRAILING-SPACE is non-nil if there should be no trailing whitespaces in the resulting string.
• SHOW-ITEM-NUM-P determines whether to display the number of items in each group's header.

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)

• FUN: The function to execute on each matching line.
• PREDICATE: This should be a function with no arguments. It will be executed on each line. If it returns non-nil, that line is considered to be matched.
• START and END limit the range of the mapping.
• If NO-SKIP-INVISIBLE is non-nil, then we don’t skip invisible lines.

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.