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.

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

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

editor:current-point

Function

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

editor:current-mark

Function

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

Sets the current mark to be point .

editor:point<

Function

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

editor:point<=

Function

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

editor:point>

Function

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

editor:point>=

Function

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

editor:copy-point

Function

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

Deletes the point point .

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

editor:move-point

Function

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

editor:start-line-p

Function

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

editor:end-line-p

Function

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

editor:same-line-p

Function

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

editor:save-excursion

Macro

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

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 .