branch: externals/ilist
commit b2bf67c5d86914d9139e89945e57e78cde5d205b
Author: JSDurand <mmem...@gmail.com>
Commit: JSDurand <mmem...@gmail.com>
Add changelog, and update documentation
* README.org:
* ilist.texinfo: Update documentation files.
* .gitignore: Ignore some files produced whie making documentation
files.
* ChangeLog: A change log is now present, yay!
---
.gitignore | 5 ++
ChangeLog | 7 +++
README.org | 98 +++++++++++++++++++++---------
ilist.info | 188 +++++++++++++++++++++++++++++++++++++++++++-------------
ilist.pdf | Bin 167330 -> 185921 bytes
ilist.texinfo | 192 +++++++++++++++++++++++++++++++++++++++++++++++-----------
6 files changed, 386 insertions(+), 104 deletions(-)
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000000..355f8ae924
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+*.aux
+*.cp
+*.cps
+*.log
+*.toc
\ No newline at end of file
diff --git a/ChangeLog b/ChangeLog
new file mode 100644
index 0000000000..4d48b89d02
--- /dev/null
+++ b/ChangeLog
@@ -0,0 +1,7 @@
+2021-12-28 李俊緯 <mmem...@gmail.com>
+
+ Update documentation.
+
+ Also add the options to skip invisible lines to some primitive
+ commands.
+
diff --git a/README.org b/README.org
index a75ab71ab1..8c0ecfb30b 100644
--- a/README.org
+++ b/README.org
@@ -15,8 +15,8 @@ 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
- SORTER NO-TRAILING-SPACE)
+ (ilist-string LIST COLUMNS GROUPS
+ &optional DISCARD-EMPTY-P SORTER NO-TRAILING-SPACE)
#+end_src
- LIST is the list that the user wants to display
@@ -24,13 +24,15 @@ called as follows.
- 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
-- NO-TRAILING-SPACE is non-nil if the function should not produce
- trailing whitespaces
+ 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.
** Columns
-Like in ibuffer, the user can specify columns to display. Each column
+Like in Ibuffer, the user can specify columns to display. Each column
comprises the following specifications:
- NAME: The name to display in the header.
@@ -49,8 +51,8 @@ comprises the following specifications:
*** 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
+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.
@@ -65,28 +67,70 @@ 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)
+*** Automatic groups
-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:
+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.
-#+begin_src emacs-lisp :eval no :exports code
- (list
- (NAME
- (INDEX1 . ELEMENT1)
- (INDEX2 . ELEMENT2)
- ...)
- ...)
+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:
+
+- nil: If it is omitted or nil, the function should just return the
+ label for =ELEMENT=.
+- default: If it is the symbol =default=, the function should return a
+ default label.
+- sorter: If it is the symbol =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.
+
+*** Define automatic filter groups
+
+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.
+
+#+begin_src emacs-lisp
+ (ilist-dag NAME DEFAULT SORTER &rest BODY)
#+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.
+- NAME: This is a string. The resulting function defined by this
+ macro will be named as =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 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.
-Then the user can provide functions to automatically group elements
-based on the criteria that fit the domain of application.
+ 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 =X= and =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 =Y=.
* Mapping over lines
@@ -110,8 +154,8 @@ auxiliary functions to operate on the displayed list. One
is
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. If the argument =NO-SKIP-INVISIBLE= is non-nil, then we
-don’t skip invisible lines.
+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
diff --git a/ilist.info b/ilist.info
index 2cb4056abb..9d17879cad 100644
--- a/ilist.info
+++ b/ilist.info
@@ -69,22 +69,24 @@ File: ilist.info, Node: Entry point, Next: Mapping over
lines, Prev: About,
The one main function this package provides is 'ilist-string'. It is
called as follows.
- (ilist-string LIST COLUMNS GROUPS DISCARD-EMPTY-P)
+ (ilist-string LIST COLUMNS GROUPS
+ &optional DISCARD-EMPTY-P SORTER NO-TRAILING-SPACE)
'LIST'
This denotes the list that the user wants to display.
'COLUMNS'
'GROUPS'
- They are described in the following sections.
+ See *note Columns:: and *note Groups::.
'DISCARD-EMPTY-P'
This determines whether to display empty groups or not.
'SORTER'
This 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.
+ the second argument. This is used to sort the elements in the
+ list, before grouping happens. To sort groups, see *note Groups::.
'NO-TRAILING-SPACE'
- This is non-nil if the function should not produce trailing
- whitespaces.
+ If this is non-nil then there will be no trailing whitespaces in
+ the resulting string.
* Menu:
@@ -124,17 +126,17 @@ File: ilist.info, Node: Groups, Prev: Columns, Up:
Entry point
2.2 Groups
==========
-The first subsection of this section describes the specifications of
-groups. And the second describes a planned feature that is not yet
-implemented.
+There are two types of filter groups: the fixed and the automatic filter
+groups.
* Menu:
* Fixed groups::
-* Automatic groups (planned)::
+* Automatic groups::
+* Define automatic filter groups::
-File: ilist.info, Node: Fixed groups, Next: Automatic groups (planned),
Prev: Groups, Up: Groups
+File: ilist.info, Node: Fixed groups, Next: Automatic groups, Prev: Groups,
Up: Groups
2.2.1 Fixed groups
------------------
@@ -158,29 +160,81 @@ is put at the end of the list 'GROUPS'.
of 'DISCARD-EMPTY-P'.
-File: ilist.info, Node: Automatic groups (planned), Prev: Fixed groups, Up:
Groups
+File: ilist.info, Node: Automatic groups, Next: Define automatic filter
groups, Prev: Fixed groups, Up: Groups
+
+2.2.2 Automatic groups
+----------------------
+
+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:
+
+'nil'
+ If it is omitted or nil, the function should just return the label
+ for 'ELEMENT'.
+'default'
+ If it is the symbol 'default', the function should return a default
+ label.
+'sorter'
+ If it is the symbol '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.
-2.2.2 Automatic groups (planned)
---------------------------------
+
+File: ilist.info, Node: Define automatic filter groups, Prev: Automatic
groups, Up: Groups
+
+2.2.3 Define automatic filter groups
+------------------------------------
+
+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.
-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:
+ 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.
- (list
- (NAME
- (INDEX1 . ELEMENT1)
- (INDEX2 . ELEMENT2)
- ...)
- ...)
+ This macro is called as follows.
+
+ (ilist-dag NAME DEFAULT SORTER &rest BODY)
+
+'NAME'
+ This is a string. The resulting function defined by this macro
+ will be named as '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 can be a symbol, or an s-expression.
- 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.
+ 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.
- Then the user can provide functions to automatically group elements
-based on the criteria that fit the domain of application.
+ 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 'X' and '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 'Y'.
File: ilist.info, Node: Mapping over lines, Next: Moving, Prev: Entry
point, Up: Top
@@ -190,7 +244,11 @@ File: ilist.info, Node: Mapping over lines, Next:
Moving, Prev: Entry point,
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'. Its return value is the list of execution results on
+the lines over which the function is executed. By default it skips
+invisible lines, but this behaviour can be alterred.
+
+ It is called as follows.
(ilist-map-lines FUN &optional PREDICATE START END NO-SKIP-INVISIBLE)
@@ -215,8 +273,8 @@ File: ilist.info, Node: Moving, Next: Copying This
Manual, Prev: Mapping over
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. If the argument 'NO-SKIP-INVISIBLE' is non-nil, then we
-don’t skip invisible lines.
+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'
@@ -711,8 +769,55 @@ their use in free software.
File: ilist.info, Node: Index, Prev: Copying This Manual, Up: Top
-Index
-*****
+Appendix B Index
+****************
+
+s which returns
non-nil if and only if the first argument should be sorted before the
-second argument.
+second argument. This is used to sort the elements in the list,
+before grouping happens. To sort groups, see @ref{Groups}.
@item NO-TRAILING-SPACE
-This is non-nil if the function should not produce trailing
-whitespaces.
+If this is non-nil then there will be no trailing whitespaces in the
+resulting string.
@end table
@menu
@@ -102,10 +119,13 @@ whitespaces.
@comment node-name, next, previous, up
@section Columns
+@cindex columns of the display
+@cindex column, specification
+
Like in Ibuffer, the user can specify columns to display. Each column
comprises the following specifications:
-@table @code
+@table@code
@item NAME
The name to display in the header.
@item FUN
@@ -119,6 +139,7 @@ The minimal (resp. maximal) width this column takes.
Either :left, :right, or :center. How the contents of the column are
aligned.
@item ELIDE
+@cindex eliding string
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
@emph{eliding string}. If this ELIDE is not a string, then it means
@@ -129,24 +150,30 @@ not to elide, but to truncate the contents.
@comment node-name, next, previous, up
@section Groups
-The first subsection of this section describes the specifications of
-groups. And the second describes a planned feature that is not yet
-implemented.
+@cindex filter groups
+
+There are two types of filter groups: the fixed and the automatic
+filter groups.
@menu
* Fixed groups::
-* Automatic groups (planned)::
+* Automatic groups::
+* Define automatic filter groups::
@end menu
-@node Fixed groups, Automatic groups (planned), Groups, Groups
+@node Fixed groups, Automatic groups, Groups, Groups
@comment node-name, next, previous, up
@subsection Fixed groups
+@cindex fixed filter 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 @code{GROUPS} are as follows.
+@cindex fixed filter groups, specification
+
@table @code
@item NAME
The name of the group. This will be enclosed in square brackets and
@@ -156,44 +183,127 @@ A function with one argument. If the function returns
non-nil, then
that element is considered to pertain to the group.
@end table
+@cindex fixed filter groups, default group
+
So a default group just uses a function that always returns @code{t},
and is put at the end of the list @code{GROUPS}.
Empty groups might or might not be displayed, depending on the value
of @code{DISCARD-EMPTY-P}.
-@node Automatic groups (planned), , Fixed groups, Groups
+@node Automatic groups, Define automatic filter groups, Fixed groups, Groups
+@comment node-name, next, previous, up
+@subsection Automatic groups
+
+@cindex automatic filter groups, mechanism
+
+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: @code{(ELEMENT &optional TYPE)}. The optional argument
+@code{TYPE} says what the caller wants from the function:
+
+@cindex automatic filter groups, types
+
+@table@code
+@item nil
+If it is omitted or nil, the function should just return the label for
+@code{ELEMENT}.
+@item default
+If it is the symbol @code{default}, the function should return a
+default label.
+@item sorter
+If it is the symbol @code{sorter}, the function should return a
+function with two arguments, @code{X} and @code{Y}. This returned
+function should return a non-nil value if and only if group @code{X}
+should be placed earlier than group @code{Y}.
+@end table
+
+@cindex automatic filter groups, example call
+
+So, for example, the call @code{(FUN t 'default)} should produce the
+default label, @code{(FUN t 'sorter)} should return the function used
+to sort groups, and @code{(FUN ELEMENT)} should return the label for
+@code{ELEMENT}, where @code{FUN} is an automatic filter group.
+
+@node Define automatic filter groups, , Automatic groups, Groups
@comment node-name, next, previous, up
-@subsection Automatic groups (planned)
+@subsection Define automatic filter groups
-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:
+@cindex custom automatic filter groups
+@cindex define automatic filter groups
+@findex ilist-define-automatic-group
+@findex ilist-dag
+
+If one wants to define ones own automatic filter group, then the macro
+@code{ilist-define-automatic-group}, or the shorter alias
+@code{ilist-dag}, might come in handy.
+
+In case you wonder, this @emph{dag} has nothing to do with an
+@emph{directed acyclic graph}; it is just an abbreviation to save some
+typing. The coincidence of the names is a misfortune.
+
+@cindex signature of ilist-define-automatic-group
+
+This macro is called as follows.
@lisp
-(list
- (NAME
- (INDEX1 . ELEMENT1)
- (INDEX2 . ELEMENT2)
- ...)
- ...)
+(ilist-dag NAME DEFAULT SORTER &rest BODY)
@end lisp
-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.
+@table @code
+@item NAME
+This is a string. The resulting function defined by this macro will
+be named as @code{ilist-automatic-group-NAME}.
+@item DEFAULT
+This is also a string. It is used to label elements for which this
+automatic group returns nil as its label.
+
+@cindex reason for using default in automatic groups
+
+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.
+@item 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.
-Then the user can provide functions to automatically group elements
-based on the criteria that fit the domain of application.
+@cindex ilist-dag sorter convention
+
+If it is an s-expression., it will be used to define a function
+@code{ilist-automatic-group-NAME-sorter}, which then becomes the
+sorting function. The variables @code{X} and @code{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 @code{X}
+should be displayed before the group labelled @code{Y}.
+@end table
@node Mapping over lines, Moving, Entry point, Top
@comment node-name, next, previous, up
@chapter Mapping over lines
+@cindex mapping
+@cindex loop through display
+@findex ilist-map-lines
+
For the convenience of package-users, this package also provides some
auxiliary functions to operate on the displayed list. One is
-@code{ilist-map-lines}. It is called as follows.
+@code{ilist-map-lines}. Its return value is the list of execution
+results on the lines over which the function is executed. By default
+it skips invisible lines, but this behaviour can be alterred.
+
+It is called as follows.
+
+@cindex signature of ilist-map-lines
@lisp
(ilist-map-lines FUN &optional PREDICATE START END NO-SKIP-INVISIBLE)
@@ -217,11 +327,21 @@ If non-nil, then we don’t skip invisible lines.
@comment node-name, next, previous, up
@chapter Moving
+@cindex moving around
+@cindex navigations
+@cindex round buffer
+
It might be desired to move between the displayed list items in a
@emph{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. If the argument @code{NO-SKIP-INVISIBLE}
-is non-nil, then we don’t skip invisible lines.
+four functions for moving. These functions all have an argument
+@code{NO-SKIP-INVISIBLE}; if that argument is non-nil, then invisible
+lines won't skipped.
+
+@findex ilist-forward-line
+@findex ilist-backward-line
+@findex ilist-forward-group-header
+@findex ilist-backward-group-header
@table @code
@item ilist-backward-line
@@ -240,7 +360,7 @@ Move between group headers.
@include fdl-1.3.texi
@node Index, , Copying This Manual, Top
-@unnumbered Index
+@appendix Index
@printindex cp
