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]