\chapter{Introduction}
\pagenumbering{arabic}

\sysname{} is a library for representing the buffer of a text editor.
As such, it defines a set of \clos{} \emph{protocols} for client code
to interact with the buffer contents in various ways, and it supplies
different \emph{implementations} of those protocols for different
purposes.

The buffer protocols have been chosen so that they can fit a variety
of editors.  As a consequence, they are not particularly
Emacs-centric.  For example, in Emacs, a newline character is just
another character, so that moving past it using the
\texttt{forward-char} command changes the line in which \emph{point}
is located, and using the \texttt{delete-char} command when
\emph{point} is to the left of a newline character joins the line to
the next one.

In contrast, the buffer protocols documented here are \emph{line
  oriented} and there is no newline character; only a sequence of
lines.  At some level, it is of course desirable to have
Emacs-compatible commands, but these commands are written separately,
using this buffer protocol to accomplish the effects.  For example,
the Emacs-compatible \texttt{forward-item} command checks whether it
is at the end of a line, and if so, detaches the cursor from that line
and attaches it to the next one.  Similarly, the Emacs compatible
\texttt{delete-item} command calls \texttt{join-line} in the buffer
protocol to obtain the desired effect when it is at the end of a line.

By writing the editor commands in two levels like this, we hope it
will be easier to use the buffer protocols to write emulators for
other editors, such as \texttt{VIM}.

The buffer participates in two different buffer protocols:

\begin{enumerate}
\item The \emph{edit protocol}, used by client editing and
  cursor-motion operations.
\item The \emph{update protocol}, used by redisplay operations to
  determine what items are contained in the buffer.
\end{enumerate}

The operations in the edit protocol were designed to be \emph{fast}
(typically around 10 $\mu s$) so that it is practical to use these
operations in a loop, say to insert or delete a region, or to
accomplish several operations inside a keyboard macro.  The exceptions
are the operations \texttt{split-line} and \texttt{join-line} that
take time proportional to the number of items in the second line.%
\footnote{We may improve on this performance in the future.}

The operations in the update protocol were designed to be called at
the frequency of the \emph{event loop} of an application, typically
once for each character typed, but also when a window is resized or
scrolled (in which case, these operations are very fast since no
modifications to the buffer have occurred).

The buffer edit protocols expose two levels of abstraction to client
code:

\begin{enumerate}
\item The \emph{buffer} level represents the \emph{sequence of lines}
  independently of how the individual lines are represented.
\item The \emph{line} level represents individual lines.
\end{enumerate}

As mentioned above, the buffer protocols do not pretend to manage any
equivalence between line breaks and some sequence of characters.  It
is up to client code to model such an equivalence if desired.  As a
consequence, the buffer protocols do not allow for a cursor at the
beginning of a line to move backward or a cursor at the end of a line
to move forward.  An attempt at doing so will result in an error being
signaled.  If client code wants to impose a model where the line break
corresponds to (say) the \emph{newline} character, then it must
explicitly detach and reattach the cursor to a different line in these
cases.  It can manage that in two different ways: either by explicitly
testing for \texttt{beginning-of-line} or \texttt{end-of-line} before
calling the equivalent buffer function, or by handling the error that
results from the attempt.

The buffer also does not interpret the meaning of any of items
contained in it.  For instance, whether an item is to be considered
part of a \emph{word} or not, is not decided at the buffer level, but
at the level of the syntax.  As a consequence, the buffer protocol
does not offer any functions that require such interpretation, such as
\texttt{forward-word}, \texttt{end-of-paragraph}, etc.
