\section{Buffer update protocol}
\label{sec-update-protocol}

The purpose of the buffer update protocol is to allow for a number of
edit operations to the buffer without updating the view of the buffer.
This functionality is important because a single command may result in
an arbitrary number of edit operations to the buffer, and we typically
want the view to be updated only once, when all those edit operations
have been executed.

At the center of the update protocol is the concept of a \emph{time
  stamp}.  The nature of this time stamp is not specified, other than
the fact that its value is incremented for each operation that alters
the contents of the buffer.  The only operation allowed by client code
on a time stamp is to store it and pass it as an argument to the
protocol function \texttt{update}.

\Defgeneric {items} {line \key start end}

Return the items of \textit{line} as a vector.  The keyword parameters
\textit{start} and \textit{end} have the same interpretation as for
\commonlisp{} sequence functions.

\Defgeneric {update} {buffer time sync skip modify create}

The \textit{buffer} parameter is a buffer that might have been
modified since the last update operation.  The \textit{time} parameter
is the time stamp of the last time the update operation was called, so
that the \texttt{update} function will report modifications since that
time.  In addition to time stamps, the \textit{time} argument can also
be \texttt{nil}, which is interpreted as the beginning of time.  Thus,
when \texttt{nil} is given as a value of this argument, the operations
generated correspond to the creation of the buffer.

The \texttt{update} function returns a new time stamp to be used as
the \textit{time} argument in the next call to \texttt{update}.

The time stamp is specific to each buffer, and more importantly, to
each \emph{buffer implementation}.  The consequences are unspecified
if a time stamp returned by calling \texttt{update} on one buffer is
used in a call to \texttt{update} with a different buffer.

The parameters \textit{sync}, \textit{skip}, \textit{modify}, and
\textit{create}, are functions that are called by the \texttt{update}
function.  They are to be considered as \emph{edit operations} on some
representation of the buffer as it was after the previous call to
\texttt{update}.  The operations have the following meaning:

\begin{itemize}
\item \textit{create} indicates a line that has been created.  The
  function is called with that line as an argument.
\item \textit{modify} indicates a line that has been modified.  The
  function is called with that line as an argument.  Client code must
  compare the current line of its view to the argument, and delete the
  current line repeatedly until the two are \texttt{eq}.  It
  must then take whatever action is needed for the modified contents
  of the line, and finally it must make the immediately following line
  the current one.
\item \textit{sync} indicates the first unmodified line after a
  sequence of new or modified lines.  Accordingly, this function is
  called once, following one or more calls to \textit{create} or
  \textit{modify}.  This function is called with a single argument:
  the unmodified line.  Client code must compare the current line of
  its view to the argument, and delete the current line repeatedly
  until the two are \texttt{eq}.  Finally, it must make the
  immediately following line the current one.
\item \textit{skip} indicates that a number of lines have not been
  subject to any modifications since the last update.  The function
  takes a single argument, the number of lines to skip.  This function
  is called \emph{first} to indicate that a \emph{prefix} of the
  buffer is unmodified, or after a \emph{sync} operation to indicate
  that that many lines following the one given as argument to the
  \textit{sync} operation are unmodified.  This operation is also
  called when there are unmodified lines at the end of the buffer so
  that the total line count of the buffer corresponds to the total
  number of lines mentioned in the sequence of operations.
\end{itemize}

