\section{Buffer edit protocol}
\label{sec-buffer-edit-protocol}

\subsection{Protocol classes}

\Defclass {buffer}

This is the base class for all buffers.  It should not itself be
instantiated.  Instead, \sysname{} contains different modules, each
providing a different subclass of this class that can be instantiated.

By default, it is recommended that client code instantiate the class
\texttt{buffer} in the package \texttt{cluffer-standard-buffer}.
\seesec{sec-implementation-standard-buffer}

\subsection{Operations on buffers}

\Defgeneric {beginning-of-buffer-p} {cursor}

Return \textit{true} if and only if \textit{cursor} is located at the
beginning of a buffer.

\Defgeneric {end-of-buffer-p} {cursor}

Return \textit{true} if and only if \textit{cursor} is located at the
end of a buffer.

\Defgeneric {beginning-of-buffer} {cursor}

Position \textit{cursor} at the very beginning of the buffer.

\Defgeneric {end-of-buffer} {cursor}

Position \textit{cursor} at the very end of the buffer.

\Defgeneric {split-line-at-position} {line position}

Split \textit{line} into two lines, the first cone containing the
items preceding \textit{position} and the second one containing the
items following \textit{position}.  After this operation, any
left-sticky cursor located at \textit{position} will be located at the
end of the first line, and any right-sticky cursor located at
\textit{position} will be located at the beginning of the second line.

This operation is implemented in one of two ways:

\begin{enumerate}
\item Either the prefix is moved from the original line to a new line.
  In this case, the second of the two resulting lines is \texttt{eq}
  to the original one.
\item Or the suffix is moved from the original line to a new line.
  In this case, the first of the two resulting lines is \texttt{eq} to
  the original one.
\end{enumerate}

However, it is not specified which of the two techniques is used, and
it is not specified what value is returned from this operation.

\Defgeneric {split-line} {cursor}

Calling this function is equivalent to calling
\texttt{split-line-at-position}, passing it the line to which
\textit{cursor} is attached, and the position of \textit{cursor}.

\ifdetached{}

\Defgeneric {join-line} {entity}

The argument \textit{entity} may be a cursor or a line.

If \textit{entity} is a line, then join that line with the line
following it in the buffer to which the line is attached.  If
\textit{entity} is a cursor, join the line to which the cursor is
attached with the line following it in the buffer to which the line is
attached.

If \textit{entity} is a cursor that is not currently attached to a
line, a condition of type \texttt{cursor-detached} is signaled.

If \textit{entity} is a line that is not currently attached to a
buffer, a condition of type \texttt{line-detached} is signaled.

If \textit{entity} is a cursor and it is attached to the last line of
the buffer, the error condition \texttt{end-of-buffer} will be
signaled.

\Defgeneric {line-count} {buffer}

Return the number of lines in \textit{buffer}.

\Defgeneric {line-number} {entity}

The argument \textit{entity} may be a cursor or a line.

If \textit{entity} is a cursor and that cursor is not attached to any
line, a condition of type \texttt{cursor-detached} is signaled.

If \textit{entity} is a cursor and that cursor is attached to a line,
then the generic function \texttt{line} \seesec{sec-edit-protocol} is
called with \textit{entity} as an argument and the return value is
used as argument in a recursive call to \texttt{line-number}.

If \textit{entity} is a line and that line is not attached to a
buffer, then \texttt{nil} is returned.

If \textit{entity} is a line and that line is attached to a buffer,
then the line number of \textit{line} in that buffer is returned.  The
first line of the buffer has the number $0$.

\Defgeneric {find-line} {buffer line-number}

Return the line in the buffer with the given \textit{line-number}.  If
\textit{line-number} is less than $0$ then the error
\texttt{beginning-of-buffer} is signaled.  If \textit{line-number} is
greater than or equal to the number of lines in the buffer, then the
error \texttt{end-of-buffer} is signaled.

Notice that the edit protocol does not contain any
\texttt{delete-line} operation.  This design decision was made on
purpose.  By only providing \texttt{join-line}, we guarantee that
removing a line leaves a \emph{trace} in the buffer in the form of a
modification operation on the first of the two lines that were
joined.  This features is essential in order for the \emph{update
  protocol} to work correctly.
