[climacs-cvs] CVS update: climacs/Doc/climacs-internals.texi

[Elliott Johnson]

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

Modified Files:
	climacs-internals.texi 
Log Message:
protocol update for kill ring
Date: Thu Jan  6 18:56:43 2005
Author: ejohnson

Index: climacs/Doc/climacs-internals.texi
diff -u climacs/Doc/climacs-internals.texi:1.5 climacs/Doc/climacs-internals.texi:1.6
--- climacs/Doc/climacs-internals.texi:1.5	Wed Dec 29 07:58:55 2004
+++ climacs/Doc/climacs-internals.texi	Thu Jan  6 18:56:42 2005
@@ -1649,6 +1649,85 @@
 @deftp {initarg} :records
 @end deftp
 
+ at chapter Kill Ring Protocol
+
+ at section Overview
+
+During the process of text editing it may become necessary for regions of text
+to be manipulated non-sequentially.  The kill ring and its surrounding protocol
+offers both a temporary location for data to be stored, as well as methods for 
+stored data to be accessed.
+
+Conceptually, the kill ring is a stack of bounded depth, so that when elements 
+are pushed beyond that depth, the oldest element is removed.  All newly added 
+data is attached to a single point at the ``start of ring position'' or SORP.
+
+This protocol provides two methods which govern how data is to be attached to the 
+SORP.  The first method moves the current SORP to a new position, on to which a new 
+object is attached.  The second conserves the current position and replaces its 
+contents with a sequence constructed of new and pre-existing SORP objects.  This 
+latter method is refered to as a ``concatenating push''.
+
+For data retrievial the kill ring class provides a ``yank point'' which
+allows focus to be shifted from the SORP to other positions within the kill ring. 
+The yank point is limited to two types of motition, one being a rotation away from the SORP 
+and the other being an immediate return or ``reset'' to the start position.
+
+ at section General
+
+ at deftp {class} kill-ring
+A class for all kill rings. 
+ at end deftp
+
+ at deftp {init-arg} :max-size
+A limitation placed upon the number of elements held by a kill ring.  Once the maximum size 
+has been reached, older entries must first be removed before new ones can be added.
+ at end deftp
+
+ at deffn {generic function} kill-ring-max-size kill-ring
+Returns the value of a kill ring's maximum size.
+ at end deffn
+
+ at deffn {generic function} {(setf kill-ring-max-size)} kill-ring size
+Alters the maximum size of a kill ring even if it means dropping
+elements to do so.
+ at end deffn
+
+ at deffn {generic function} kill-ring-length kill-ring
+Returns the current length of a kill-ring.  Note this is different than
+kill-ring-max-size.
+ at end deffn
+
+ at deffn {generic function} kill-ring-standard-push kill-ring vector
+Pushes a vector of objects onto a given kill ring creating a new start of ring 
+position.  This function is much like an everyday lisp push with size considerations.  
+If the length of the kill ring is greater than its maximum size, ``older'' elements 
+will be removed from the ring until the maximum size is reached.
+ at end deffn
+
+ at deffn {generic function} kill-ring-concatenating-push kill-ring vector
+Concatenates the contents of vector onto the end of the contents of
+the current top of the kill-ring.  If the kill-ring is empty, a new
+entry is pushed..
+ at end deffn
+
+ at deffn {generic function} rotate-yank-position kill-ring &optional times
+Moves the yank point associated with a kill-ring one or times many positions
+away from the start of ring position.  If times is greater than the current length 
+then the cursor will wrap to the start of ring position and continue rotating.
+ at end deffn
+
+ at deffn {generic function} reset-yank-position kill-ring
+Moves the current position of the yank point associated with a kill ring back to
+the start of ring position.
+ at end deffn
+
+ at deffn {generic function} kill-ring-yank kill-ring &optional reset
+Returns the vector of objects currently pointed to by the cursor.  If reset is T, then a 
+call to reset-yank-position is called before the object is yanked.  The default for reset 
+is NIL.
+ at end deffn
+
 @node Index
 @unnumbered Index