File: vc-dispatcher.el.html

Goals:

There is a class of front-ending problems that Emacs might be used to address that involves selecting sets of files, or possibly directories, and passing the selection set to slave commands. The prototypical example, from which this code is derived, is talking to version-control systems.

vc-dispatcher.el is written to decouple the UI issues in such front ends from their application-specific logic. It also provides a service layer for running the slave commands either synchronously or asynchronously and managing the message/error logs from the command runs.

Similar UI problems can be expected to come up in applications areas other than VCSes; IDEs and document search are two obvious ones. This mode is intended to ensure that the Emacs interfaces for all such beasts are consistent and carefully designed. But even if nothing but VC ever uses it, getting the layer separation right will be a valuable thing.

Dispatcher's universe:

The universe consists of the file tree rooted at the current directory. The dispatcher's upper layer deduces some subset of the file tree from the state of the currently visited buffer and returns that subset, presumably to a client mode.

The user may be looking at either of two different views; a buffer visiting a file, or a directory buffer generated by vc-dispatcher.

The lower layer of this mode runs commands in subprocesses, either synchronously or asynchronously. Commands may be launched in one of two ways: they may be run immediately, or the calling mode can create a closure associated with a text-entry buffer, to be executed when the user types C-c to ship the buffer contents. In either case the command messages and error (if any) will remain available in a status buffer.

Special behavior of dispatcher directory buffers:

In dispatcher directory buffers, facilities to perform basic navigation and selection operations are provided by keymap and menu entries that dispatcher sets up itself, so they'll be uniform across all dispatcher-using client modes. Client modes are expected to append to these to provide mode-specific bindings.

The standard map associates a 'state' slot (that the client mode may set) with each directory entry. The dispatcher knows nothing about the semantics of individual states, but mark and unmark commands treat all entries with the same state as the currently selected one as a unit.

The interface:

The main interface to the lower level is vc-do-command. This launches a command, synchronously or asynchronously, making the output available in a command log buffer. Two other functions, (vc-start-logentry) and
(vc-finish-logentry), allow you to associate a command closure with an
annotation buffer so that when the user confirms the comment the closure is run (with the comment as part of its context).

The interface to the upper level has the two main entry points (vc-dir) and (vc-dispatcher-selection-set) and a couple of convenience functions.
(vc-dir) sets up a dispatcher browsing buffer; (vc-dispatcher-selection-set)
returns a selection set of files, either the marked files in a browsing buffer or the singleton set consisting of the file visited by the current buffer (when that is appropriate). It also does what is needed to ensure that on-disk files and the contents of their visiting Emacs buffers coincide.

When the client mode adds a local vc-mode-line-hook to a buffer, it will be called with the buffer file name as argument whenever the dispatcher resyncs the buffer.

Defined variables (8)

Defined functions (25)

Defined faces (0)