LispWorks Editor User Guide > 6 Advanced Features > 6.3 Programming the editor

NextPrevUpTopContentsIndex

6.3.4 Points

Locations within a buffer are recorded as editor:point objects. Each point remembers a character position within the buffer and all of the editor functions that manipulate the text of a buffer locate the text using one or more point objects (sometimes the current point).

A point's kind controls what happens to the point when text in the buffer is inserted or deleted.

:temporary points are for cases where you need read-only access to the buffer. They are like GNU Emacs "points". They have a lower overhead than the other kinds of point and do not need to be explicitly deleted, but do not use them in cases where you make a point, insert or delete text and then use the point again, since they do not move when the text is changed. Also, do not use them in cases where more than one thread can modify their buffer without locking the buffer first (see Buffer locking)

:before-insert and :after-insert points are for cases where you need to make a point, insert or delete text and still use the point afterwards. They are like GNU Emacs "markers". The difference between these two kinds is what happens when text is inserted. For a point at position n from the start of the buffer, inserting len characters will leave the point at either position n or n + len according to the following table.

Editor point positions after text insertion

kind

Insert at < n

Insert at = n

Insert at > n

:before-insert

n + len

n

n

:after-insert

n + len

n + len

n

When text is deleted, :before-insert and :after-insert points are treated the same: points <= the start of the deletion remain unchanged, points >= the end of the deletion are moved with the text and points within the deleted region are automatically deleted and cannot be used again.

All points with kind other than :temporary are stored within the data structures of the editor buffer so they can be updated when the text changes. A point can be removed from the buffer by editor:delete-point, and point objects are also destroyed if their buffer is killed.

editor:point-kind

Function

editor:point-kind point

Returns the kind of the point, which is :temporary , :before-insert or :after-insert .

editor:current-point

Function

editor:current-point

Returns the current point. See also editor:buffer-point.

editor:current-mark

Function

editor:current-mark &optional pop-pno-error-p

Returns the current mark. If pop-p is t , the mark ring is rotated so that the previous mark becomes the current mark. If no mark is set and no-error-p is t , nil is returned; otherwise an error is signalled. The default for both of these optional arguments is nil .

editor:set-current-mark

Function

editor:set-current-mark point

Sets the current mark to be point .

editor:point<

Function

editor:point< point1 point2

Returns non-nil if point1 is before point2 in the buffer.

editor:point<=

Function

editor:point<= point1 point2

Returns non-nil if point1 is before or at the same offset as point2 in the buffer.

editor:point>

Function

editor:point> point1 point2

Returns non-nil if point1 is after point2 in the buffer.

editor:point>=

Function

editor:point>= point1 point2

Returns non-nil if point1 is after or at the same offset as point2 in the buffer.

editor:copy-point

Function

editor:copy-point point &optional kind new-point

Makes and returns a copy of point . The argument kind can take the value :before , :after , or :temporary . If new-point is supplied, the copied point is bound to that as well as being returned.

editor:delete-point

Function

editor:delete-point point

Deletes the point point .

This should be done to any non-temporary point which is no longer needed.

editor:move-point

Function

editor:move-point point new-position

Moves point to new-position , which should itself be a point.

editor:start-line-p

Function

editor:start-line-p point

Returns t if point is immediately before the first character in a line, and nil otherwise.

editor:end-line-p

Function

editor:end-line-p point

Returns t if point is immediately after the last character in a line, and nil otherwise.

editor:same-line-p

Function

editor:same-line-p point1 point2

Returns t if point1 and point2 are on the same line, and nil otherwise.

editor:save-excursion

Macro

editor:save-excursion &rest body

Saves the location of the point and the mark and restores them after completion of body . This restoration is accomplished even when there is an abnormal exit from body .

editor:with-point

Macro

editor:with-point point-bindings &rest body

point-bindings is a list of bindings, each of the form ( var point [ kind ]) . Each variable var is bound to a new point which is a copy of the point point though possibly with a different kind, if kind is supplied. If kind is not supplied, then the new point has kind :temporary .

The forms of body are evaluated within the scope of the point bindings, and then the points in each variable var are deleted, as if by editor:delete-point. Each point var is deleted even if there was an error when evaluating body .

The main reason for using with-point to create non-temporary points is to allow body to modify the buffer while keeping these points up to date for later use within body .


LispWorks Editor User Guide (Windows version) - 22 Dec 2009

NextPrevUpTopContentsIndex