Re: docs for ewoc.el

[Thien-Thi Nguyen]

Eli Zaretskii <address@hidden> writes:

> comments

thanks for the comments.
following is a revision taking them into account.

thi


___________________________________
@node Abstract Display
@section Abstract Display
@cindex display, abstract
@cindex display, arbitrary objects
@cindex model/view/controller
@cindex view part, model/view/controller

  Generally, to display an object in a buffer, you must decide on its
representation, as either text or image, and insert that representation in
the buffer.  When the object changes, you must update its representation
appropriately.  The common infrastructure of these tasks is the focus of the
@code{ewoc-} set of functions, which together form a utility to maintain a
view of a list of objects in a buffer.

  These functions define and pass around an @dfn{ewoc}, which is a data
structure encapsulating two strings, @dfn{header} and @dfn{footer}; a
@dfn{pretty-printer} function that is responsible for inserting object
representations in the buffer; and an ordered set of @dfn{nodes}, with one
node per object in your list.

  To define an ewoc, use @code{ewoc-create}.  To get an ewoc's buffer, header
and footer, use @code{ewoc-buffer} and @code{ewoc-get-hf}, respectively.  To
change the header and/or footer, use @code{ewoc-set-hf}.

@defun ewoc-create pretty-printer &optional header footer
This constructs and returns a new ewoc, with no data elements.
@var{pretty-printer} should be a function that takes one argument,
a data element, and inserts at point its string representation,
using @code{insert} (and not @code{insert-before-markers}).
@end defun

@defun ewoc-buffer ewoc
@defunx ewoc-get-hf ewoc
These return, respectively, the buffer where @var{ewoc} was created, and
its header and footer as a cons cell @code{(@var{header} . @var{footer})}.
@end defun

@defun ewoc-set-hf ewoc header footer
This sets the header and footer of @var{ewoc} to the strings @var{header}
and @var{footer}, respectively.
@end defun

  To add nodes, use the @address@hidden functions.  To refer to
a node's neighbor, use @code{ewoc-prev} and @code{ewoc-next}.  To refer to a
node by a modulo index into the ewoc, use @code{ewoc-nth}.  To access a node's
data, use @code{ewoc-data}.

@defun ewoc-enter-first ewoc data
@defunx ewoc-enter-last ewoc data
These construct a new node encapsulating @var{data}, adding it to @var{ewoc}
at the beginning or end, respectively, of the set of ordered nodes.
@end defun

@defun ewoc-enter-before ewoc node data
@defunx ewoc-enter-after ewoc node data
These construct a new node encapsulating @var{data}, adding it to @var{ewoc}
before or after @var{node}, respectively.
@end defun

@defun ewoc-prev ewoc node
@defunx ewoc-next ewoc node
These return the previous and next node, respectively, of @var{node}
in @var{ewoc}.
@end defun

@defun ewoc-nth ewoc n
This returns the node in @var{ewoc} found at zero-based index @var{n}.
A negative @var{n} means count from the end.  @code{ewoc-nth} returns
@code{nil} if there are less than @var{n} elements.
@end defun

@defun ewoc-data node
This extracts the data encapsulated by @var{node} and returns it.
@end defun

  To find out which node (if any) point is at in an ewoc, use
@code{ewoc-locate}.  If you already have a node, to find its start position,
use @code{ewoc-location}.  To move point from the start of one representation
to another, use the @address@hidden functions.

@defun ewoc-locate ewoc &optional pos guess
This determines the node in @var{ewoc} which contains point (or @var{pos} if
specified), and returns that node.  If @var{ewoc} is empty, it returns
@code{nil}.  If @var{pos} is before the first node or after the last node, it
returns that node.  Optional third arg @var{guess} should be a node that is
likely to be near @var{pos}.
@end defun

@defun ewoc-location node
This returns the start position of @var{node}.
@end defun

@defun ewoc-goto-prev ewoc arg
@defunx ewoc-goto-next ewoc arg
These move point to the previous or next, respectively, @var{arg}th node
in @var{ewoc}.  @code{ewoc-goto-prev} does not move if it is already at the
first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next} moves past
the last node, returning @code{nil}.  Excepting this special case, these
functions return the node moved to.
@end defun

@defun ewoc-goto-node ewoc node
This moves point to the start of @var{node} in @var{ewoc}.
@end defun

  To completely recompute and redisplay the representations of all nodes in an
ewoc, use @code{ewoc-refresh}.  For only a few, use @code{ewoc-invalidate}.
To delete nodes, use @code{ewoc-filter}.  To form a list of data elements
satisfying a certain predicate, use @code{ewoc-collect}.  To map a function
over all nodes, use @code{ewoc-map}.

@defun ewoc-refresh ewoc
This deletes the region bounded by the header end and the footer beginning in
@var{ewoc}, i.e., all the data elements' representations, and then calls the
pretty-printer function for each node, in order.
@end defun

@defun ewoc-invalidate ewoc &rest nodes
This is similar to @code{ewoc-refresh}, except that only @var{nodes} in
@var{ewoc} are updated instead of the entire set.
@end defun

@defun ewoc-filter ewoc predicate &rest args
This calls @var{predicate} for each data element in @var{ewoc} and
removes those nodes for which @var{predicate} returns @code{nil}.
Any @var{args} are passed to @var{predicate}.
@end defun

@defun ewoc-collect ewoc predicate &rest args
This calls @var{predicate} for each data element in @var{ewoc}
and returns a list of those elements for which @var{predicate}
returns address@hidden  The elements in the list are ordered
as in the buffer.  Any @var{args} are passed to @var{predicate}.
@end defun

@defun ewoc-map map-function ewoc &rest args
This calls @var{map-function} for each data element in @var{ewoc} and
updates those nodes for which @var{map-function} returns address@hidden
Any @var{args} are passed to @var{map-function}.
@end defun