Skip to main content

39.20.1 Abstract Display Functions

In this subsection, ewoc and node stand for the structures described above (see Abstract Display), while data stands for an arbitrary Lisp object used as a data element.

This constructs and returns a new ewoc, with no nodes (and thus no data elements). pretty-printer should be a function that takes one argument, a data element of the sort you plan to use in this ewoc, and inserts its textual description at point using insert (and never insert-before-markers, because that would interfere with the Ewoc package’s internal mechanisms).

Normally, a newline is automatically inserted after the header, the footer and every node’s textual description. If nosep is non-nil, no newline is inserted. This may be useful for displaying an entire ewoc on a single line, for example, or for making nodes invisible by arranging for pretty-printer to do nothing for those nodes.

An ewoc maintains its text in the buffer that is current when you create it, so switch to the intended buffer before calling ewoc-create.

function ewoc-buffer ewoc​

This returns the buffer where ewoc maintains its text.

function ewoc-get-hf ewoc​

This returns a cons cell (header . footer) made from ewoc’s header and footer.

This sets the header and footer of ewoc to the strings header and footer, respectively.

function ewoc-enter-first ewoc data​

function ewoc-enter-last ewoc data​

These add a new node encapsulating data, putting it, respectively, at the beginning or end of ewoc’s chain of nodes.

function ewoc-enter-before ewoc node data​

function ewoc-enter-after ewoc node data​

These add a new node encapsulating data, adding it to ewoc before or after node, respectively.

function ewoc-prev ewoc node​

function ewoc-next ewoc node​

These return, respectively, the previous node and the next node of node in ewoc.

function ewoc-nth ewoc n​

This returns the node in ewoc found at zero-based index n. A negative n means count from the end. ewoc-nth returns nil if n is out of range.

function ewoc-data node​

This extracts the data encapsulated by node and returns it.

function ewoc-set-data node data​

This sets the data encapsulated by node to data.

function ewoc-locate ewoc \&optional pos guess​

This determines the node in ewoc which contains point (or pos if specified), and returns that node. If ewoc has no nodes, it returns nil. If pos is before the first node, it returns the first node; if pos is after the last node, it returns the last node. The optional third arg guess should be a node that is likely to be near pos; this doesn’t alter the result, but makes the function run faster.

function ewoc-location node​

This returns the start position of node.

function ewoc-goto-prev ewoc arg​

function ewoc-goto-next ewoc arg​

These move point to the previous or next, respectively, argth node in ewoc. ewoc-goto-prev does not move if it is already at the first node or if ewoc is empty, whereas ewoc-goto-next moves past the last node, returning nil. Excepting this special case, these functions return the node moved to.

function ewoc-goto-node ewoc node​

This moves point to the start of node in ewoc.

function ewoc-refresh ewoc​

This function regenerates the text of ewoc. It works by deleting the text between the header and the footer, i.e., all the data elements’ representations, and then calling the pretty-printer function for each node, one by one, in order.

function ewoc-invalidate ewoc \&rest nodes​

This is similar to ewoc-refresh, except that only nodes in ewoc are updated instead of the entire set.

function ewoc-delete ewoc \&rest nodes​

This deletes each node in nodes from ewoc.

function ewoc-filter ewoc predicate \&rest args​

This calls predicate for each data element in ewoc and deletes those nodes for which predicate returns nil. Any args are passed to predicate.

function ewoc-collect ewoc predicate \&rest args​

This calls predicate for each data element in ewoc and returns a list of those elements for which predicate returns non-nil. The elements in the list are ordered as in the buffer. Any args are passed to predicate.

function ewoc-map map-function ewoc \&rest args​

This calls map-function for each data element in ewoc and updates those nodes for which map-function returns non-nil. Any args are passed to map-function.