Update of /project/climacs/cvsroot/climacs/Doc
In directory clnet:/tmp/cvs-serv14113
Modified Files:
climacs-internals.texi
Log Message:
Removed parts of internals documentation that have been moved to Drei.
--- /project/climacs/cvsroot/climacs/Doc/climacs-internals.texi 2006/09/14 14:24:01 1.24
+++ /project/climacs/cvsroot/climacs/Doc/climacs-internals.texi 2008/01/13 08:49:09 1.25
@@ -50,2057 +50,6 @@
detailed description of various Climacs protocols and other internal
details.
-@chapter Buffer protocol
-
-@section Introduction
-
-The Climacs buffer is what holds textual and other objects to be
-edited and displayed. Conceptually, the buffer is a potentially
-large sequence of objects, most of which are expected to be
-characters (the full Unicode character set is supported). However,
-Climacs buffers can contain any Common Lisp objects, as long as the
-syntax module knows how to render them.
-
-The Climacs buffer implementation differs from that of a vector,
-because it allows for very efficient editing operations, such as
-inserting and removing objects at arbitrary offsets.
-
-In addition, the Climacs buffer protocols defines that concept of a
-mark.
-
-@section General
-
-@deftp {Protocol Class} buffer
-
-The base class for all buffers. A buffer conceptually contains a
-large array of arbitrary objects. Lines of objects are separated by
-newline characters. The last object of the buffer is not
-necessarily a newline character.
-@end deftp
-
-@deftp {Class} standard-buffer
-
-The standard instantiable class for buffers. A subclass of buffer.
-@end deftp
-
-@deftp {Protocol Class} mark
-
-The base class for all marks.
-@end deftp
-
-@deftp {Initarg} :buffer
-
-The :buffer initarg is mandatory because no mark can exist without a
-buffer. When the :offset initarg is not given, it defaults to zero.
-@end deftp
-
-@deftp {Initarg} :offset
-
-If an :offset initarg is given that is less than zero or greater than
-the size of the buffer, a no-such-offset condition is signaled.
-@end deftp
-
-@deftp {Protocol Class} left-sticky-mark
-
-A subclass of mark. A mark of this type will "stick" to the object
-to the left of it, i.e. when an object is inserted at this mark, the
-mark will be positioned to the left of the object.
-@end deftp
-
-@deftp {Protocol Class} right-sticky-mark
-
-A subclass of mark. A mark of this type will "stick" to the object
-to the right of it, i.e. when an object is inserted at this mark, the
-mark will be positioned to the right of the object.
-@end deftp
-
-@deffn {Generic Function} {clone-mark} (mark &optional stick-to)
-
-Clone a mark. By default (when stick-to is NIL) the same type of mark
-is returned. Otherwise stick-to is either :left, indicating that a
-left-sticky-mark should be created, or :right indicating that a
-right-sticky-mark should be created.
-@end deffn
-
-@deffn {Generic Function} {buffer} mark
-
-Return the buffer that the mark is positioned in.
-@end deffn
-
-@deftp {Error Condition} no-such-offset
-
-This condition is signaled whenever an attempt is made to access an
-object that is before the beginning or after the end of the buffer.
-@end deftp
-
-@deftp {Error Condition} offset-before-beginning
-
-This condition is signaled whenever an attempt is made to access
-buffer contents that is before the beginning of the buffer.
-This condition is a subclass of no-such-offset
-@end deftp
-
-@deftp {Error Condition} offset-after-end
-
-This condition is signaled whenever an attempt is made to access
-buffer contents that is after the end of the buffer.
-This condition is a subclass of no-such-offset
-@end deftp
-
-@deftp {Error Condition} invalid-motion
-
-This condition is signaled whenever an attempt is made to move a mark
-before the beginning or after the end of the buffer.
-@end deftp
-
-@deftp {Error Condition} motion-before-beginning
-
-This condition is signaled whenever an attempt is made to move a mark
-before the beginning of the buffer.
-This condition is a subclass of invalid-motion.
-@end deftp
-
-@deftp {Error Condition} motion-after-end
-
-This condition is signaled whenever an attempt is made to move a mark
-after the end of the buffer.
-This condition is a subclass of invalid-motion.
-@end deftp
-
-@deffn {Generic Function} {size} buffer
-
-Return the number of objects in the buffer.
-@end deffn
-
-@deffn {Generic Function} {number-of-lines} buffer
-
-Return the number of lines of the buffer, or really the number of
-newline characters.
-@end deffn
-
-@section Operations related to the offset of marks
-
-
-@deffn {Generic Function} {offset} mark
-
-Return the offset of the mark into the buffer.
-@end deffn
-
-@deffn {Generic Function} {(setf offset)} offset mark
-
-Set the offset of the mark into the buffer. A motion-before-beginning
-condition is signaled if the offset is less than zero. A
-motion-after-end condition is signaled if the offset is greater than
-the size of the buffer.
-@end deffn
-
-@deffn {Generic Function} {forward-object} mark &optional (count 1)
-
-Move the mark forward the number of positions indicated by count.
-This function could be implemented by an incf on the offset of the
-mark, but many buffer implementations can implement this function much
-more efficiently in a different way. A motion-before-beginning
-condition is signaled if the resulting offset of the mark is less than
-zero. A motion-after-end condition is signaled if the resulting offset
-of the mark is greater than the size of the buffer.
-@end deffn
-
-@deffn {Generic Function} {backward-object} mark &optional (count 1)
-
-Move the mark backward the number of positions indicated by count.
-This function could be implemented by a decf on the offset of the
-mark, but many buffer implementations can implement this function much
-more efficiently in a different way. A motion-before-beginning
-condition is signaled if the resulting offset of the mark is less than
-zero. A motion-after-end condition is signaled if the resulting offset
-of the mark is greater than the size of the buffer.
-@end deffn
-
-@deffn {Generic Function} {mark<} mark1 mark2
-
-Return t if the offset of mark1 is strictly less than that of mark2.
-An error is signaled if the two marks are not positioned in the same
-buffer. It is acceptable to pass an offset in place of one of the
-marks.
-@end deffn
-
-@deffn {Generic Function} {mark<=} mark1 mark2
-
-Return t if the offset of mark1 is less than or equal to that of
-mark2. An error is signaled if the two marks are not positioned in
-the same buffer. It is acceptable to pass an offset in place of one
-of the marks.
-@end deffn
-
-@deffn {Generic Function} {mark>} mark1 mark2
-
-Return t if the offset of mark1 is strictly greater than that of
-mark2. An error is signaled if the two marks are not positioned in
-the same buffer. It is acceptable to pass an offset in place of one
-of the marks.
-@end deffn
-
-@deffn {Generic Function} {mark>=} mark1 mark2
-
-Return t if the offset of mark1 is greater than or equal to that of
-mark2. An error is signaled if the two marks are not positioned in
-the same buffer. It is acceptable to pass an offset in place of one
-of the marks.
-@end deffn
-
-@deffn {Generic Function} {mark=} mark1 mark2
-
-Return t if the offset of mark1 is equal to that of mark2. An error
-is signaled if the two marks are not positioned in the same buffer.
-It is acceptable to pass an offset in place of one of the marks.
-@end deffn
-
-@deffn {Generic Function} {beginning-of-buffer} mark
-
-Move the mark to the beginning of the buffer. This is equivalent to
-(setf (offset mark) 0)
-@end deffn
-
-@deffn {Generic Function} {end-of-buffer} mark
-
-Move the mark to the end of the buffer.
-@end deffn
-
-@deffn {Generic Function} {beginning-of-buffer-p} mark
-
-Return t if the mark is at the beginning of the buffer, nil
-otherwise.
-@end deffn
-
-@deffn {Generic Function} {end-of-buffer-p} mark
-
-Return t if the mark is at the end of the buffer, nil otherwise.
-@end deffn
-
-@deffn {Generic Function} {beginning-of-line} mark
-
-Move the mark to the beginning of the line. The mark will be
-positioned either immediately after the closest preceding newline
-character, or at the beginning of the buffer if no preceding newline
-character exists.
-@end deffn
-
-@deffn {Generic Function} {end-of-line} mark
-
-Move the mark to the end of the line. The mark will be positioned
-either immediately before the closest following newline character, or
-at the end of the buffer if no following newline character exists.
-@end deffn
-
-@deffn {Generic Function} {beginning-of-line-p} mark
-
-Return t if the mark is at the beginning of the line (i.e., if the
-character preceding the mark is a newline character or if the mark is
-at the beginning of the buffer), nil otherwise.
-@end deffn
-
-@deffn {Generic Function} {end-of-line-p} mark
-
-Return t if the mark is at the end of the line (i.e., if the character
-following the mark is a newline character, or if the mark is at the
-end of the buffer), nil otherwise.
-@end deffn
-
-@deffn {Generic Function} {buffer-line-number} buffer offset
-
-Return the line number of the line at offset. Lines are numbered from
-zero.
-@end deffn
-
-@deffn {Generic Function} {buffer-column-number} buffer offset
-
-Return the column number of the line at offset. It is the number of
-objects between it and the preceding newline, or between it and the
-beginning of the buffer if offset is on the first line of the buffer.
-@end deffn
-
-@deffn {Generic Function} {line-number} mark
-
-Return the line number of the mark. Lines are numbered from zero.
-@end deffn
-
-@deffn {Generic Function} {column-number} mark
-
-Return the column number of the mark. The column number of a mark is
-the number of objects between it and the preceding newline, or
-between it and the beginning of the buffer if the mark is on the
-first line of the buffer.
-@end deffn
-
-@section Inserting and deleting objects
-
-@deffn {Generic Function} {insert-buffer-object} buffer offset object
-
-Insert the object at the offset in the buffer. Any left-sticky marks
-that are placed at the offset will remain positioned before the
-inserted object. Any right-sticky marks that are placed at the
-offset will be positioned after the inserted object.
-@end deffn
-
-@deffn {Generic Function} {insert-buffer-sequence} buffer offset sequence
-
-Like calling insert-buffer-object on each of the objects in the
-sequence.
-@end deffn
-
-@deffn {Generic Function} {insert-object} mark object
-
-Insert the object at the mark. This function simply calls
-insert-buffer-object with the buffer and the position of the mark.
-@end deffn
-
-@deffn {Generic Function} {insert-sequence} mark sequence
-
-Insert the objects in the sequence at the mark. This function simply
-calls insert-buffer-sequence with the buffer and the position of the
-mark.
-@end deffn
-
-@deffn {Generic Function} {delete-buffer-range} buffer offset n
-
-Delete n objects from the buffer starting at the offset. If offset is
-negative, a offset-before-beginning condition is signaled. If
-offset+n is greater than the size of the buffer, a offset-after-end
-condition is signaled.
-@end deffn
-
-@deffn {Generic Function} {delete-range} mark &optional (n 1)
-
-Delete n objects after (if n > 0) or before (if n < 0) the mark.
-This function eventually calls delete-buffer-range, provided that n
-is not zero.
-@end deffn
-
-@deffn {Generic Function} {delete-region} mark1 mark2
-
-Delete the objects in the buffer that are between mark1 and mark2. An
-error is signaled if the two marks are positioned in different
-buffers. It is acceptable to pass an offset in place of one of the
-marks.
-
-This function calls delete-buffer-range with the appropriate arguments.
-@end deffn
-
-@section Getting objects out of the buffer
-
-@deffn {Generic Function} {buffer-object} buffer offset
-
-Return the object at the offset in the buffer. The first object
-has offset 0. If offset is less than zero, an offset-before-beginning
-condition is signaled. If offset is greater than or equal to
-the size of the buffer, an offset-after-end condition is signaled.
-@end deffn
-
-@deffn {Generic Function} {buffer-sequence} buffer offset1 offset2
-
-Return the contents of the buffer starting at offset1 and ending at
-offset2-1 as a sequence. If either of the offsets is less than zero,
-an offset-before-beginning condition is signaled. If either of the
-offsets is greater than or equal to the size of the buffer, an
-offset-after-end condition is signaled. If offset2 is smaller than or
-equal to offset1, an empty sequence will be returned.
-@end deffn
-
-@deffn {Generic Function} {object-before} mark
-
-Return the object that is immediately before the mark. If mark is at
-the beginning of the buffer, an offset-before-beginning condition is
-signaled. If the mark is at the beginning of a line, but not at the
-beginning of the buffer, a newline character is returned.
-@end deffn
-
-@deffn {Generic Function} {object-after} mark
-
-Return the object that is immediately after the mark. If mark is at
-the end of the buffer, an offset-after-end condition is signaled. If
-the mark is at the end of a line, but not at the end of the buffer, a
-newline character is returned.
-@end deffn
-
-@deffn {Generic Function} {region-to-sequence} mark1 mark2
-
-Return a freshly allocated sequence of the objects between mark1 and
-mark2. An error is signaled if the two marks are positioned in
-different buffers. It is acceptable to pass an offset in place of one
-of the marks.
-
-This function calls buffer-sequence with the appropriate arguments.
-@end deffn
-
-@section Implementation hints
-
-The buffer is implemented as lines organized in a 2-3-tree. The
-leaves of the tree contain the lines, and the internal nodes contain
-additional information of the left subtree (if it is a 2-node) or the
-left and the middle subtree (if it is a 3-node). Two pieces of
-information are stored: The number of lines in up to and including
-the subtree and the total number of objects up to an including the
-subtree. This organization allows us to determine, the line number
-and object position of any mark in O(log N) where N is the number of
-lines.
-
[1660 lines skipped]
