\chapter{Supplied implementations}
\label{chap-supplied-implementations}

\section{Standard line}
\label{sec-implementation-standard-line}

\subsection{Characteristics}

The \emph{standard line} implementation provides a
reasonably-efficient implementation of the line-edit protocol.  Two
different line classes are provided, one called \emph{open} and the
other one called \emph{closed}.

A line is open if it has been modified after the last time client code
asked for its contents (as provided by the protocol generic function
\texttt{items}).  Otherwise the line is closed.  Open lines are
typically efficient for a number of consecutive editing operations at
positions that are close to one another, as is typically the case when
a region of text is inserted or deleted.  Closed lines, on the other
hand, are efficient when client code asks for the items contained in
them.

Notice that for the typical scenario where an end user types text as
one character at a time, the line into which the text is typed is
going to be opened and closed once for every keystroke.  When the end
user types the character, the line will be opened in order to prepare
it for the editing operation.  Immediately after the editing operation
terminates, the visible part of the text buffer is going to be
\emph{displayed} in some window on the screen.  This display operation
requires the client code to ask for the contents of the line, which
will require the line to be closed.

While this alternate opening and closing of the line may seem
unreasonably inefficient, notice that it is happening at typing speed,
so that there is typically ample time for these operations between two
keystrokes typed.  More importantly, the scenario of an end user
typing text is not the one for which this design was optimized.
Instead, it was designed for cases where a single keystroke results in
multiple editing operations.  Typical such scenarios include inserting
and deleting a region of text, or executing a keyboard macro that
results in multiple editing operations.  The design of the standard
line allows such operations to be implemented as a sequence of
elementary editing operations without affecting performance.  As long
as the contents of the line is not asked for (presumably for that
contents to be displayed), the line remains open.

In addition to two different types of line, the \texttt{standard-line}
implementation provides two types of \emph{cursors}, namely
\emph{left-sticky} and \emph{right-sticky} cursors.  The two cursor
types differ in behavior when an item is inserted at the very position
of the cursor.  In this case, the left-sticky cursor keeps its old
position, whereas the position of any right-sticky cursor is
incremented.  A right-sticky cursor is typically used for the place
where end-user editing operations take place (the \emph{point} in the
terminology of \emacs{}).  A left-sticky cursor can be used to mark
the end of a region when the desired effect is that an insertion of an
item at the end of the region should not be included in the region.

\subsection{Package}

The package named \texttt{cluffer-standard-line} is used for all names
that are specific to the implementation of standard lines.

\subsection{Classes}

\Defclass {line}

This class is a subclass of the protocol class named \texttt{line} in
the package named \texttt{cluffer}.

\Defclass {open-line}

This class is a subclass of the class named \texttt{line}.  It is used
when the contents of the line is modified.

For this class, the contents is represented as a simple \emph{gap
  buffer} so that adding or deleting items is done at the beginning or
the end of the gap.

\Defclass {closed-line}

This class is a subclass of the class named \texttt{line}.  It is used
when the contents of the line has not been modified after an
invocation of the function \texttt{items}.

For this class, the contents is represented by a simple \commonlisp{}
vector.  Whenever \texttt{items} is invoked on a closed line and the
entire contents is asked for, this simple vector is returned, and no
copy is made.

\Defclass{cursor}

This class is the base class for the cursor classes provide by the
\texttt{standard-line} implementation.

\Defclass{left-sticky-cursor}

This class is used for cursors that should have their positions
unaltered when an item is inserted at the very position of the
cursor.   It is a subclass of the class \texttt{cursor}.

\Defclass{right-sticky-cursor}

This class is used for cursors that should have their positions
incremented when an item is inserted at the very position of the
cursor.   It is a subclass of the class \texttt{cursor}.

\section{Simple line}
\label{sec-implementation-simple-line}

\subsection{Characteristics}

The simple line implementation was written mainly for testing
purposes.  No attempt has been made to optimize the implementation of
the operations of a simple line.

A line in this implementation is implemented as \commonlisp{} simple
vector.  Every simple editing operation requires that this vector be
re-allocated with a different size.

Another use for this line implementation is as an illustration of the
semantics of the various protocol generic functions, so that it can be
used as a model for new implementations of the line-edit protocol.

\subsection{Package}

The package named \texttt{cluffer-simple-line} is used for all names
that are specific to the implementation of simple lines.

\subsection{Classes}

\Defclass {line}

This class is a subclass of the protocol class named \texttt{line} in
the package named \texttt{cluffer}.

Contrary to the standard line
\seesec{sec-implementation-standard-line} the simple line has no
concept of open or closed lines.  All lines are represented the same
way with the items stored in a simple \commonlisp{} vector.

\section{Standard buffer}
\label{sec-implementation-standard-buffer}

\subsection{Characteristics}

The standard buffer representation organizes the lines in a
\emph{splay tree} \cite{Sleator:1985:SBS:3828.3835}.  This
organization has several advantages:

\begin{itemize}
\item A line that is modified moves to the root of the tree, and
  recently used lines stay close to the root, making some editing
  operations more efficient.
\item It is computationally cheap to know the line number of the
  current line at all times.
\end{itemize}

\subsection{Package}

The package named \texttt{cluffer-standard-buffer} is used for all
names that are specific to the implementation of the standard buffer.

\subsection{Classes}

\Defclass {buffer}

This class is a subclass of the protocol class named \texttt{buffer} in
the package named \texttt{cluffer}.

\Definitarg {:initial-line}

This initarg must be supplied when the \texttt{buffer} class is
instantiated.  This initarg is the mechanism by which the otherwise
independent implementations of the buffer and the line protocols are
connected.

\section{Simple buffer}
\label{sec-implementation-simple-buffer}

\subsection{Characteristics}

The simple buffer implementation was written mainly for testing
purposes.  No attempt has been made to optimize the implementation of
the operations of a simple buffer.

The lines are stored in a \commonlisp{} simple vector.  Whenever a
line is added or removed, the vector is reallocated.  To compute the
number of items in the buffer, the sum of the items of each line is
computed.

\subsection{Package}

The package named \texttt{cluffer-simple-buffer} is used for all names
that are specific to the implementation of the simple buffer.

\subsection{Classes}

\Defclass {buffer}

This class is a subclass of the protocol class named \texttt{buffer} in
the package named \texttt{cluffer}.

\Definitarg {:initial-line}

Just as with the standard line, this initarg must be supplied when the
\texttt{buffer} class is instantiated.
