Update of /project/mcclim/cvsroot/mcclim/Drei In directory clnet:/tmp/cvs-serv3308

Modified Files: buffer.lisp Log Message: More docstring fixes and additions.

--- /project/mcclim/cvsroot/mcclim/Drei/buffer.lisp 2006/11/16 19:22:38 1.2 +++ /project/mcclim/cvsroot/mcclim/Drei/buffer.lisp 2006/11/18 15:42:43 1.3 @@ -31,22 +31,31 @@ (in-package :drei-buffer)

(defclass buffer () () - (:documentation "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.")) - -(defgeneric low-mark (buffer)) - -(defgeneric high-mark (buffer)) - -(defgeneric modified-p (buffer)) + (:documentation "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.")) + +(defgeneric low-mark (buffer) + (:documentation "Return the low mark of the buffer.")) + +(defgeneric high-mark (buffer) + (:documentation "Return the high mark of the buffer.")) + +(defgeneric modified-p (buffer) + (:documentation "Return true if and only if the buffer has been +modified."))

(defclass standard-buffer (buffer) ((contents :initform (make-instance 'standard-cursorchain)) - (low-mark :reader low-mark) - (high-mark :reader high-mark) - (modified :initform nil :reader modified-p)) + (low-mark :reader low-mark + :documentation "The low mark of the buffer.") + (high-mark :reader high-mark + :documentation "The high mark of the buffer.") + (modified :initform nil + :reader modified-p + :documentation "True if and only if the buffer has +been modified.")) (:documentation "The standard instantiable class for buffers."))

(defgeneric buffer (mark) @@ -72,11 +81,14 @@

(defgeneric (setf offset) (new-offset mark) (:documentation "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.")) +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."))

(defclass mark-mixin () - ((buffer :initarg :buffer :reader buffer) + ((buffer :initarg :buffer + :reader buffer + :documentation "The buffer that the mark is in.") (cursor :reader cursor)) (:documentation "A mixin class used in the initialization of a mark."))

@@ -135,12 +147,26 @@ (setf (cursor-pos (cursor mark)) new-offset))

(defgeneric backward-object (mark &optional count) - (:documentation "Move `mark' `count' objects backwards. Returns - `mark'.")) + (:documentation "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. Returns +`mark'."))

(defgeneric forward-object (mark &optional count) - (:documentation "Move `mark' `count' objects forwards. Returns - `mark'")) + (:documentation "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. Returns +`mark'."))

(defmethod forward-object ((mark mark-mixin) &optional (count 1)) (incf (offset mark) count) @@ -226,10 +252,10 @@ count (eql (buffer-object buffer offset) #\Newline)))

(defgeneric mark< (mark1 mark2) - (:documentation "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")) + (:documentation "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."))

(defmethod mark< ((mark1 mark-mixin) (mark2 mark-mixin)) (assert (eq (buffer mark1) (buffer mark2))) @@ -242,10 +268,10 @@ (< mark1 (offset mark2)))

(defgeneric mark<= (mark1 mark2) - (:documentation "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.")) + (:documentation "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."))

(defmethod mark<= ((mark1 mark-mixin) (mark2 mark-mixin)) (assert (eq (buffer mark1) (buffer mark2))) @@ -258,9 +284,10 @@ (<= mark1 (offset mark2)))

(defgeneric mark= (mark1 mark2) - (:documentation "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.")) + (:documentation "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."))

(defmethod mark= ((mark1 mark-mixin) (mark2 mark-mixin)) (assert (eq (buffer mark1) (buffer mark2))) @@ -273,10 +300,10 @@ (= mark1 (offset mark2)))

(defgeneric mark> (mark1 mark2) - (:documentation "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.")) + (:documentation "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."))

(defmethod mark> ((mark1 mark-mixin) (mark2 mark-mixin)) (assert (eq (buffer mark1) (buffer mark2))) @@ -289,10 +316,10 @@ (> mark1 (offset mark2)))

(defgeneric mark>= (mark1 mark2) - (:documentation "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.")) + (:documentation "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."))

(defmethod mark>= ((mark1 mark-mixin) (mark2 mark-mixin)) (assert (eq (buffer mark1) (buffer mark2))) @@ -306,8 +333,8 @@

(defgeneric beginning-of-buffer (mark) (:documentation "Move the mark to the beginning of the buffer. - This is equivalent to (setf (offset mark) 0), but returns - mark.")) +This is equivalent to `(setf (offset mark) 0)', but returns +mark."))

;; Easy way to make sure mark is always returned. (defmethod beginning-of-buffer :around (mark) @@ -319,7 +346,7 @@

(defgeneric end-of-buffer (mark) (:documentation "Move the mark to the end of the buffer and - return mark.")) +return mark."))

(defmethod end-of-buffer :around (mark) (call-next-method) @@ -329,41 +356,44 @@ (setf (offset mark) (size (buffer mark))))

(defgeneric beginning-of-buffer-p (mark) - (:documentation "Return t if the mark is at the beginning of - the buffer, nil otherwise.")) + (:documentation "Return T if the mark is at the beginning of +the buffer, nil otherwise."))

(defmethod beginning-of-buffer-p ((mark mark-mixin)) (zerop (offset mark)))

(defgeneric end-of-buffer-p (mark) - (:documentation "Return t if the mark is at the end of the buffer, nil otherwise.")) + (:documentation "Return T if the mark is at the end of the +buffer, NIL otherwise."))

(defmethod end-of-buffer-p ((mark mark-mixin)) (= (offset mark) (size (buffer mark))))

(defgeneric beginning-of-line-p (mark) - (:documentation "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.")) + (:documentation "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."))

(defmethod beginning-of-line-p ((mark mark-mixin)) (or (beginning-of-buffer-p mark) (eql (object-before mark) #\Newline)))

(defgeneric end-of-line-p (mark) - (:documentation "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.")) + (:documentation "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."))

(defmethod end-of-line-p ((mark mark-mixin)) (or (end-of-buffer-p mark) (eql (object-after mark) #\Newline)))

(defgeneric beginning-of-line (mark) - (:documentation "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. Returns mark.")) + (:documentation "Move the mark to the beginning of the line. +The mark will be positioned either immediately after the closest +receding newline character, or at the beginning of the buffer if +no preceding newline character exists. Returns `mark'."))

(defmethod beginning-of-line :around (mark) (call-next-method) @@ -374,9 +404,10 @@ do (backward-object mark)))

(defgeneric end-of-line (mark) - (:documentation "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. Returns mark.")) + (:documentation "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. Returns `mark'."))

(defmethod end-of-line :around (mark) (call-next-method) @@ -393,17 +424,18 @@ (setf (offset mark) offset)))

(defgeneric buffer-line-number (buffer offset) - (:documentation "Return the line number of the offset. Lines are numbered from zero.")) + (:documentation "Return the line number of the offset. Lines +are numbered from zero."))

(defmethod buffer-line-number ((buffer standard-buffer) (offset integer)) (loop for i from 0 below offset count (eql (buffer-object buffer i) #\Newline)))

(defgeneric buffer-column-number (buffer offset) - (:documentation "Return the column number of the offset. The column number of an offset is - the number of objects between it and the preceding newline, or - between it and the beginning of the buffer if the offset is on the - first line of the buffer.")) + (:documentation "Return the column number of the offset. The +column number of an offset is the number of objects between it +and the preceding newline, or between it and the beginning of the +buffer if the offset is on the first line of the buffer."))

(defmethod buffer-column-number ((buffer standard-buffer) (offset integer)) (loop for i downfrom offset @@ -412,16 +444,17 @@ count t))

(defgeneric line-number (mark) - (:documentation "Return the line number of the mark. Lines are numbered from zero.")) + (:documentation "Return the line number of the mark. Lines are +numbered from zero."))

(defmethod line-number ((mark mark-mixin)) (buffer-line-number (buffer mark) (offset mark)))

(defgeneric column-number (mark) - (:documentation "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.")) + (:documentation "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."))

(defmethod column-number ((mark mark-mixin)) (buffer-column-number (buffer mark) (offset mark))) @@ -440,10 +473,11 @@ finally (return (column-number mark))))

(defgeneric insert-buffer-object (buffer offset object) - (:documentation "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.")) + (:documentation "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."))

(defmethod insert-buffer-object ((buffer standard-buffer) offset object) (assert (<= 0 offset) () @@ -453,31 +487,33 @@ (insert* (slot-value buffer 'contents) offset object))

(defgeneric insert-buffer-sequence (buffer offset sequence) - (:documentation "Like calling insert-buffer-object on each of the objects in the -sequence.")) + (:documentation "Like calling insert-buffer-object on each of +the objects in the sequence."))

(defmethod insert-buffer-sequence ((buffer standard-buffer) offset sequence) (insert-vector* (slot-value buffer 'contents) offset sequence))

(defgeneric insert-object (mark object) - (:documentation "Insert the object at the mark. This function simply calls -insert-buffer-object with the buffer and the position of the mark.")) + (:documentation "Insert the object at the mark. This function +simply calls insert-buffer-object with the buffer and the +position of the mark."))

(defmethod insert-object ((mark mark-mixin) object) (insert-buffer-object (buffer mark) (offset mark) object))

(defgeneric insert-sequence (mark sequence) - (:documentation "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.")) + (:documentation "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."))

(defmethod insert-sequence ((mark mark-mixin) sequence) (insert-buffer-sequence (buffer mark) (offset mark) sequence))

(defgeneric delete-buffer-range (buffer offset n) - (:documentation "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.")) + (:documentation "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."))

(defmethod delete-buffer-range ((buffer standard-buffer) offset n) (assert (<= 0 offset) () @@ -488,9 +524,9 @@ do (delete* (slot-value buffer 'contents) offset)))

(defgeneric delete-range (mark &optional n) - (:documentation "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.")) + (:documentation "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."))

(defmethod delete-range ((mark mark-mixin) &optional (n 1)) (cond ((plusp n) (delete-buffer-range (buffer mark) (offset mark) n)) @@ -499,9 +535,10 @@

(defgeneric delete-region (mark1 mark2) (:documentation "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.")) +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."))

(defmethod delete-region ((mark1 mark-mixin) (mark2 mark-mixin)) (assert (eq (buffer mark1) (buffer mark2))) @@ -524,9 +561,10 @@ (delete-buffer-range (buffer mark2) offset1 (- offset2 offset1))))

(defgeneric buffer-object (buffer offset)

[103 lines skipped]