[elpa] externals/ilist d03de0ea64 02/24: README

[ELPA Syncer]

branch: externals/ilist
commit d03de0ea640c2abb16c548f6e3066818dbf93d7d
Author: JSDurand <mmemmew@gmail.com>
Commit: JSDurand <mmemmew@gmail.com>

    README
---
 README.org | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..cb060d07f0
--- /dev/null
+++ b/README.org
@@ -0,0 +1,114 @@
+#+TITLE: IList
+#+AUTHOR: Durand
+#+DATE: <2021-09-12 Dim 11:00>
+
+* About
+
+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.
+
+* Entry point
+
+The one main function this package provides is =ilist-string=.  It is
+called as follows.
+
+#+begin_src emacs-lisp :eval no :exports code
+(ilist-string LIST COLUMNS GROUPS DISCARD-EMPTY-P)
+#+end_src
+
+Here the LIST is the list that the user wants to display.
+
+And DISCARD-EMPTY-P determines whether to display empty groups or not.
+
+** Columns
+
+Like in ibuffer, the user can specify columns to display.  Each column
+comprises the following specifications:
+
+- NAME: The name to display in the header.
+- FUN: A function that will be given the elements of the list (one at
+  a time) that should return a string as the representation of that
+  element in this column.
+- MIN: The minimal number of width this column takes.
+- MAX
+- ALIGN: Either :left, :right, or :center.  How the contents of the
+  column are aligned.
+- ELIDE: If the content of an element takes more space than the MAX,
+  whether to substitute the last few characters of that content by a
+  fixed "eliding string".  If this ELIDE is not a string, then it
+  means not to elide, but to truncate the contents.
+
+**  GROUPS
+
+*** Fixed groups
+
+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.
+
+- NAME: The name of the group.  This will be enclosed in square
+  brackets and displayed on a separate line.
+- FUN: A function with one argument.  If the function returns non-nil,
+  then that element is considered to pertain to the group.
+
+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.
+
+*** Automatic groups (planned)
+
+I plan to add support for automatic groups.  This means that, instead
+of providing a list of groups, one provides a function with one
+argument.  That argument will be fed the list of elements.  Then the
+function is supposed to return a list of the following form:
+
+#+begin_src emacs-lisp :eval no :exports code
+  (list
+   (NAME
+    (INDEX1 . ELEMENT1)
+    (INDEX2 . ELEMENT2)
+    ...)
+   ...)
+#+end_src
+
+That is, it should return cons cells of indices and elements, where
+the indices mean the indices of the corresponding element, in the
+original list.
+
+Then the user can provide functions to automatically group elements
+based on the criteria that fit the domain of application.
+
+* Mapping over lines
+
+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.
+
+#+begin_src emacs-lisp :eval no :exports code
+  (ilist-map-lines FUN PREDICATE START END)
+#+end_src
+
+- 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.
+
+* Moving
+
+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.
+
+- =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.