Update of /project/climacs/cvsroot/climacs/Doc In directory common-lisp.net:/tmp/cvs-serv17346/Doc

Modified Files: climacs-internals.texi Log Message: Updated the description of the buffer protocol to reflect recent changes with respect to conditions and clone-mark.

Date: Sat Feb 26 06:33:39 2005 Author: rstrandh

Index: climacs/Doc/climacs-internals.texi diff -u climacs/Doc/climacs-internals.texi:1.12 climacs/Doc/climacs-internals.texi:1.13 --- climacs/Doc/climacs-internals.texi:1.12 Sat Feb 5 14:49:22 2005 +++ climacs/Doc/climacs-internals.texi Sat Feb 26 06:33:37 2005 @@ -113,11 +113,12 @@ mark will be positioned to the right of the object. @end deftp

-@deffn {Generic Function} {clone-mark} (mark &key type) +@deffn {Generic Function} {clone-mark} (mark &optional stick-to)

-Clone a mark. By default (when type is NIL) the same type of mark is -returned. Otherwise type is the name of a class (subclass of the mark -class) to be used as a class of the clone. +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 @@ -127,8 +128,42 @@

@deftp {Error Condition} no-such-offset

-This condition is signaled whenever an attempt is made at an operation -that is before the beginning or after the end of the buffer. +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 @@ -152,25 +187,32 @@

@deffn {Generic Function} {(setf offset)} offset mark

-Set the offset of the mark into the buffer. A no-such-offset -condition is signaled if the offset is less than zero or greater than -the size of the buffer. +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. +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. +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. +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. +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 @@ -309,9 +351,10 @@

@deffn {Generic Function} {delete-buffer-range} buffer offset n

-Delete n objects from the buffer starting at the offset. If offset -is negative or offset+n is greater than the size of the buffer, a -no-such-offset condition is signaled. +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) @@ -336,31 +379,33 @@ @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 or greater than or equal to -the size of the buffer, a no-such-offset condition is signaled. +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 -or greater than or equal to the size of the buffer, a no-such-offset -condition is signaled. If offset2 is smaller than or equal to -offset1, an empty sequence will be returned. +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, a no-such-offset 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. +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, a no-such-offset condition is signaled. If +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 @@ -371,6 +416,8 @@ 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