Homepage: https://www.gnu.org/software/emacs
Author: Inge Wallin, Per Cederqvist
Utility to maintain a view of a list of objects in a buffer
Ewoc Was Once Cookie
But now it's Emacs's Widget for Object Collections
As the name implies this derives from the `cookie' package (part
of Elib). The changes are pervasive though mostly superficial:
- uses CL (and its `defstruct')
- separate from Elib.
- uses its own version of a doubly-linked list which allows us
to merge the elib-wrapper and the elib-node structures into ewoc-node
- dropping functions not used by PCL-CVS (the only client of ewoc at the
time of writing)
- removing unused arguments
- renaming:
elib-node ==> ewoc--node
collection ==> ewoc
tin ==> ewoc--node
cookie ==> data or element or elem
Introduction
============
Ewoc is a package that implements a connection between an
dll (a doubly linked list) and the contents of a buffer.
Possible uses are Dired (have all files in a list, and show them),
buffer-list, kom-prioritize (in the LysKOM elisp client) and
others. pcl-cvs.el and vc.el use ewoc.el.
Ewoc can be considered as the `view' part of a model-view-controller.
An `element' can be any Lisp object. When you use the ewoc
package you specify a pretty-printer, a function that inserts
a printable representation of the element in the buffer. (The
pretty-printer should use "insert" and not
"insert-before-markers").
A `ewoc' consists of a doubly linked list of elements, a
header, a footer and a pretty-printer. It is displayed at a
certain point in a certain buffer. (The buffer and point are
fixed when the ewoc is created). The header and the footer
are constant strings. They appear before and after the elements.
Ewoc does not affect the mode of the buffer in any way. It
merely makes it easy to connect an underlying data representation
to the buffer contents.
A `ewoc--node' is an object that contains one element. There are
functions in this package that given an ewoc--node extract the data, or
give the next or previous ewoc--node. (All ewoc--nodes are linked together
in a doubly linked list. The `previous' ewoc--node is the one that appears
before the other in the buffer.) You should not do anything with
an ewoc--node except pass it to the functions in this package.
An ewoc is a very dynamic thing. You can easily add or delete elements.
You can apply a function to all elements in an ewoc, etc, etc.
Remember that an element can be anything. Your imagination is the
limit! It is even possible to have another ewoc as an
element. In that way some kind of tree hierarchy can be created.
The Emacs Lisp Reference Manual documents ewoc.el's "public interface".
Coding conventions
==================
All functions of course start with `ewoc'. Functions and macros
starting with the prefix `ewoc--' are meant for internal use,
while those starting with `ewoc-' are exported for public use.