2.1.1 Built-in Units

The following units are provided by the text.editing library by default. Users of the library can define additional units.

The hierarchy of built-in unit classes looks like this:

unit
+-region-unit
| +-edit:region
| `-region-or
|   +-edit:region-or-item
|   `-text.editing.expression:region-or-expression
+-edit:item
+-line-unit
| +-edit:line
| +-edit:semi-line
| `-edit:line-boundary
+-buffer-unit
| +-edit:buffer
| +-edit:semi-buffer
| `-edit:buffer-boundary
+-prose-unit
| +-edit:word
| +-edit:sentence
| +-edit:paragraph
| `-edit::page
`-text.editing.expression:expression
  `-text.editing.expression:toplevel-expression

3.3.1 Insertion Stack Protocol

This protocol allows querying and manipulating the entries of an insertion stack. This protocol is not concerned with buffers, sites or cursors. See Copy and Yank Operations for a higher-level protocol on top of this one.

Class: insertion-stack-empty-error [text.editing] ¶

This error is signaled when an attempt is made to retrieve an entry from an empty insertion stack.

Generic Function: forward [text.editing] insertion-entry ¶

Return the sequence of items that have been added to insertion-entry by forward deletion operations such as cluffer:delete-item and cluffer:join-line.

Generic Function: (setf forward) [text.editing] new-value insertion-entry ¶

Set the sequence of items for forward deletion operations of insertion-entry to new-value.

Generic Function: backward [text.editing] insertion-entry ¶

Return the sequence of items that have been added to insertion-entry by backward deletion operations such as cluffer:erase-item.

Generic Function: (setf backward) [text.editing] new-value insertion-entry ¶

Set the sequence of items for backward deletion operations of insertion-entry to new-value.

Generic Function: insertion [text.editing] insertion-entry ¶

Return a sequence of items that should be inserted into a buffer to conceptually insert insertion-entry into that buffer.

The returned sequence is the concatenation of the items of the “forward” and “backward” sequences of insertion-entry in the appropriate order.

Generic Function: entry-count [text.editing] insertion-stack ¶

Return number of insertion entries in insertion-stack.

Generic Function: top-entry [text.editing] insertion-stack ¶

Return the top entry in insertion-stack or nil.

The forward, backward and insertion functions can be applied to the returned object.

Generic Function: find-entry [text.editing] index insertion-stack ¶

Return the entry at index in insertion-stack.

The forward, backward and insertion functions can be applied to the returned object.

Generic Function: push-entry [text.editing] insertion-stack ¶

Add a new entry to insertion-stack and return the new entry.

Generic Function: pop-entry [text.editing] insertion-stack ¶

Remove the top entry from insertion-stack and return the removed entry.

If insertion-stack is empty, signal an error of type insertion-stack-empty-error.

3.3.2 Preferred Column Protocol

The purpose of this protocol is tracking in which column the point cursor of a site should be placed when the cursor repeatedly moves vertically (between lines) without other movement or operations.

Generic Function: preferred-column [text.editing] site ¶

Return the column number in which the point of site should reside by default or nil.

The point cursor should be placed in that column or the rightmost existing column of the current line when the point cursor moves between lines without moving within any line.

Generic Function: (setf preferred-column [text.editing)] new-value site ¶

Set the column number in which the point of site should reside by default to new-value.

A default implementation of this protocol is provided by the following mixin class:

Class: preferred-column-tracking-mixin [text.editing] ¶

This class is intended to be mixed into site classes that track preferred column of the point cursor.

3.3.3 Operation History Protocol

The purpose of this protocol is recording the sequence of operations that have been applied to a given site. This allows the command processor or certain operations, for example, to take into account the previous operation. Examples:

• Some operations behave differently when repeated such as setting the mark twice to first set the mark then deactivate it.
• The command processor may track runs of deletion operations to collect the deleted items into a single insertion stack entry.
• The command processor may track runs of insertion, deletion or modification operations to create undo groups from multiple primitive operations.

Generic Function: most-recent-operation [text.editing] site ¶

Return the most recent operation of site or nil.

Generic Function: push-operation [text.editing] operation site ¶

Push operation into the operation history of site.

operation should be a list of the form (operation-name . arguments) where operation-name is a symbol that names an operation function.

A default implementation of this protocol is provided by the following mixin class:

Class: operation-history-mixin [text.editing] ¶

This class is intended to be mixed into site classes that track the history of performed operations.

3.3.4 Site Protocol

The site protocol extends the Detach Protocol, that is, sites can be detached.

Generic Function: point [text.editing] site ¶

Return the point cursor of site.

The returned object is a Cluffer cursor

Generic Function: mark [text.editing] site ¶

Return the mark cursor of site.

The returned object is a Cluffer cursor.

Generic Function: mark-active-p [text.editing] site ¶

Indicate whether the mark cursor of site is active.

Generic Function: (setf mark-active-p) [text.editing] new-value site ¶

Change whether the mark cursor of site is active.

new-value is a generalized Boolean.

Generic Function: mark-stack [text.editing] site ¶

Return the mark stack of site.

Generic Function: insertion-stack [text.editing] site ¶

Return the insertion stack of site.

The returned object implements the Insertion Stack Protocol.

3.4.1 Primary Site Protocol

Generic Function: site [text.editing] buffer ¶

Return the primary site of buffer.

The generic functions point and mark defined in the Site Protocol work on buffers as well. The return value is the primary point cursor and the primary mark cursor respectively.

3.4.2 Multiple Sites Protocol

The following condition types are used in the multiple sites protocol:

Class: singular-site-error [text.editing] ¶

This error is signaled if an operation that requires multiple sites is performed on a buffer that contains only a single site.

An implementation of this protocol is provided by the class

Class: multiple-site-mixin [text.editing] ¶

This class is intended to be mixed into buffer classes that can contain zero or more secondary sites in addition to the primary site.

The protocol consists of the following generic functions:

Generic Function: site-count [text.editing] buffer ¶

Return the total number of sites that are attached to buffer.

The returned count includes the primary site.

Generic Function: map-sites [text.editing] function buffer ¶

Call function with each site that is attached to buffer.

Generic Function: sites [text.editing] buffer ¶

Return the sequence of all sites which are attached to buffer.

Generic Function: add-site [text.editing] site buffer ¶

Add site to the sites of buffer.

Return site.

If the point cursor or the mark cursor of site is associated with a buffer other than bar, an error is signaled.

If site is already one of the sites that are attached to buffer, signal an error.

Generic Function: remove-site [text.editing] site buffer ¶

Detach site and remove it from the sites of buffer.

Return site.

If site is not one of the sites that are attached to buffer, signal an error.

If site is the primary site of buffer, signal an error.

Generic Function: push-site-at [text.editing] buffer line position ¶

Create a new site at line and position and attach it to buffer.

line and position control the location of the point cursor of the new site.

Return the new site.

Generic Function: push-site-relative [text.editing] buffer unit direction ¶

Create a new site relative to the primary site and attach it to buffer.

unit and direction control the location of the point cursor of the new site. The new point cursor starts at the location of the primary point cursor, then moves according to unit and direction.

Return the new site.

The attempt to move the new point cursor the specified location may result in an error. In that case, the new site is not attached and the error is signaled.

Generic Function: pop-site [text.editing] buffer ¶

Remove the most recently added site from buffer.

Return the removed site.

If no sites beside the primary site are attached to buffer, signal an error of type singular-site-error.

Generic Function: rotate-sites [text.editing] buffer direction ¶

Swap roles between the primary site and secondary sites in buffer.

direction controls the direction of the rotation.

If direction is :forward, sites are rotated as follows:

primary          ← first secondary
first secondary  ← second secondary
second secondary ← third secondary
…
last secondary   ← primary

direction :backward is not supported at the moment

If no sites beside the primary site are attached to buffer, signal an error of type singular-site-error.

Generic Function: other-sites [text.editing] buffer ¶

Return the sequence of all sites which are attached to buffer except the primary site.

Generic Function: remove-other-sites [text.editing] buffer ¶

Remove all sites from buffer except the primary site.

3.6.1 Motion Operations

Generic Function: move [text.editing] cursor unit direction ¶

Move cursor to the beginning or end of the sub-sequence of buffer items indicated by unit.

cursor is an attached Cluffer cursor.

unit is a unit of movement such as item or word.

If direction is :forward, cursor moves to the end of the sub-sequence. If direction is :backward, cursor moves to the beginning of the sub-sequence.

Generic Function: back-to-indentation [text.editing] cursor ¶

Move cursor to the first column of the current line that contains a non-whitespace item.

3.6.2 Insertion Operations

Generic Function: insert-item [text.editing] cursor item ¶

Insert item at cursor.

Generic Function: insert-newline [text.editing] cursor ¶

Split the current line at the position of cursor.

Generic Function: insert-items [text.editing] cursor items &key start end ¶

Insert the items in items at cursor.

start and end, when supplied, select a sub-sequence of items.

3.6.3 Deletion Operations

Generic Function: delete [text.editing] cursor unit direction ¶

Delete the sub-sequence of buffer items indicated by cursor, unit and direction.

cursor is an attached Cluffer cursor.

unit is a unit of movement such as item or word.

direction is either :forward or :backward.

Generic Function: delete-indentation [text.editing] cursor ¶

Join previous and current line, delete whitespace before and after cursor.

Keep a single space character unless the delete placed cursor on an empty line.

Generic Function: delete-trailing-whitespace [text.editing] cursor ¶

Delete trailing whitespace from buffer lines.

cursor determines the first line to be processed. All subsequent lines to the end of the buffer are processed after that.

Generic Function: fixup-whitespace [text.editing] cursor ¶

Delete consecutive whitespace before and after cursor in the current line.

Keep a single space character unless the deletion placed cursor at the beginning of the line.

3.6.4 Items Functions

The following convenience function allow easy retrieval and mutation of sub-sequences of buffer items:

Generic Function: map-items [text.editing] function cursor unit direction ¶

Call function with each item in the sub-sequence of buffer items indicated by cursor, unit and direction.

Generic Function: items [text.editing] cursor unit direction ¶

Return a cl:sequence containing the sub-sequence of buffer items indicated by cursor, unit and direction.

Generic Function: (setf items) [text.editing] new-value cursor unit direction ¶

Replace the sub-sequence of buffer items indicated by cursor, unit and direction by the items in the cl:sequence new-value.

3.6.5 Marking Operations

The mark protocol contains operations for managing different aspects of the mark cursor of a site:

• The mark cursor can be set or not.
• A set mark cursor can be active or inactive. When the mark is active, the point cursor and mark cursor define the region of the site.
• A mark stack stores previous locations of the mark cursor.

Generic Function: mark-or-error [text.editing] object ¶

Return the mark cursor of object or signal an error.

If the mark cursor of object is not set, signal an error of type mark-not-set-error.

Generic Function: activate-mark [text.editing] site ¶

Set the state of the mark cursor of site to active.

Signal an error of type mark-not-set-error if the mark of site is not set.

Generic Function: deactivate-mark [text.editing] site ¶

Set the state of the mark cursor of site to inactive.

Generic Function: set-mark [text.editing] site ¶

Set the mark cursor of site to the position of the point cursor.

Push the current mark cursor, if any, onto the mark stack, set a new mark cursor and move it to the position of the point cursor. Activate the mark.

Return the new mark cursor.

Generic Function: set-mark-or-toggle-active [text.editing] site ¶

Set the mark cursor of site or toggle its active state.

If the previous command was not set-mark-or-toggle-active, then push the current mark cursor of site onto the mark stack, set a new mark cursor and move it to the position of the point cursor.

If the previous command was set-mark-or-toggle-active, then toggle the active state of the mark cursor of site.

Return two values: a Boolean which indicates whether a new mark cursor was set and another Boolean which indicates whether the mark is active.

Generic Function: pop-mark [text.editing] site ¶

Pop a mark off the mark stack of site and move the point cursor to it.

Destroy the current mark of site, if any.

Return the popped mark cursor.

Signal an error of type mark-stack-empty if the mark stack of site is empty.

Generic Function: exchange-point-and-mark [text.editing] site ¶

Exchange the locations of point and mark of site.

Signal an error of type mark-not-set-error if the mark of site is not set.

Generic Function: mark-object [text.editing] site unit direction ¶

Set region of site according to unit and direction.

Leave the point cursor of site at its current location. Ensure the mark is set and active (see below) and move the mark cursor according to unit and direction.

If the mark of site is not set, set a new mark cursor at the location of the point cursor and activate it. Then apply the motion according to unit and direction.

If the mark of site is set but not active, activate the mark cursor and move it to the location of the point cursor. Then apply the motion according to unit and direction.

If the mark of site is set and active, just apply the motion according to unit and direction. This last case allows extending the region by marking subsequent objects.

3.6.6 Copy and Yank Operations

The copy and yank protocol offers higher-level functions that implement typical copy and yank operations which abstract from the details of the lower-level Insertion Stack Protocol.

Generic Function: yank [text.editing] site direction &key pop ¶

Insert top insertion stack entry of site at the point of site.

Insert the items from the top entry of the insertion stack of site before or after the point cursor of site.

direction controls whether the items are inserted before or after the point cursor, or equivalently, whether the point cursor moves to the beginning or end of the inserted items after the insertion.

pop controls whether the top entry of the insertion stack should be popped off.

Generic Function: copy [text.editing] site unit direction ¶

Copy items according at site according to unit and direction.

The items indicated by the point cursor of site, unit and direction are copied into either the current top entry of the insertion stack of site or a new entry that is first pushed onto the insertion stack.

Whether a new entry should be created is decided according to an internal protocol that may be exported at some later time.

3.6.7 Case Changing Operations

Generic Function: change-case [text.editing] cursor unit direction case ¶

Change the case of the sub-sequence of buffer items indicated by cursor, unit and direction according to case.

cursor is an attached Cluffer cursor.

unit is a unit of movement such as item, word, or expression.

direction is either :forward or :backward.

case has to be one of :down, :up or :capital.

The case of an item is changed by calling cl:char-downcase if case is :down, cl:char-upcase if case is :up and in a fashion analogous to cl:string-capitalize if case is capital.

3.6.8 Transposing Operations

Generic Function: transpose [text.editing] cursor unit direction ¶

Exchange the sequences of items defined by unit before and after cursor.

If cursor is within a unit, it is first moved to the boundary of that unit according to direction.

direction is either :forward or :backward and controls where cursor is positioned after the operation.

3.6.9 Filling Operations

Generic Function: insert-words-fill [text.editing] cursor words &key prefix suffix per-line-prefix fill-column ¶

Insert words at cursor with added line breaks according to fill-column.

words is a sequence of strings.

Each of prefix, suffix and per-line-prefix is a string if supplied.

fill-column, if supplied, is positive integer. If not supplied, fill-column defaults to the value of text.editing:*fill-column* which in turn is bound to 80 by default.

Roughly proceed as follows:

1. If it has been supplied, insert the prefix string.
2. For each string in words
   • If inserting the string at the current location would exceed fill-column, insert a line break and, if it has been supplied, insert the per-line-prefix string.
   • Unless the string is just punctuation, insert a space.
   • Insert the string.
3. If it has been supplied, insert the suffix string.

Generic Function: fill-words [text.editing] start-cursor end-cursor words &key prefix suffix per-line-prefix fill-column ¶

Replace the region between start-cursor and end-cursor by filling with words.

words is a sequence of strings.

prefix, suffix, per-line-prefix and fill-column behave as described for insert-words-fill.

3.6.10 Commenting Operations

Generic Function: comment [text.editing] cursor unit direction &key comment-syntax ¶

Comment buffer items at or around cursor according to unit and direction.

comment-syntax, if supplied, has to be a string which specifies the comment syntax to use. The default is ;; if unit is line and #| otherwise.

Generic Function: uncomment [text.editing] cursor unit direction ¶

Uncomment buffer items at or around cursor according to unit and direction.

3.6.11 Operations on Delimiter Pairs

The operations described in this section together with the operations of the expressions module allow structural editing of buffer contents in the sense that they transform a given buffer text that is syntactically valid to a new buffer text that is also syntactically valid. This is in contrast to general operations such as deleting a single item: Consider deleting a single item in the buffer text (length "hi"). If the deleted item is the (, the ) or either of the ", the resulting buffer text is no longer a syntactically valid s-expression. In this example, deletion operations that preserve the validity can, for example, delete both characters of the () and "" pairs simultaneously once the items in between have been deleted or delete the respective delimiter pair in a single operation, thus “raising” the formerly surrounded items up one level of expression nesting:

(length "hi") ⇒ (length "") ⇒ (length ) ⇒ () ⇒
(length "hi") ⇒ length "hi"

The above examples illustrate two kinds of operations:

• The first kind are operations which are intended as structure-preserving variants of “ordinary” operations, mainly of insertion and deletion operations since those affect the structural validity when applied to delimiter characters. These operations are described in the following section.
• The second kind, of which the “raising” operation is one example, consider the buffer text as an expression tree and perform modifications on that tree. Those operations are described as a part of the expressions module (see Expression Operations).

Class: no-closing-delimiter-error [text.editing] ¶

This error is signaled when an operation that requires a closing delimiter item is performed on a cursor that is not located at or near such an item.

Generic Function: insert-delimiter-pair [text.editing] cursor opening &key closing ¶

Insert the delimiter character opening before cursor and insert the delimiter character closing after cursor.

If closing is not supplied, the closing delimiter character is determined by looking up the pair that has opening as the opening delimiter character in the set of known delimiter pairs.

The return value of this function is unspecified.

This function is intended to be used as a structure-preserving replacement for “ordinary” operations that insert an opening delimiter: When a user performs the operation for inserting the opening delimiter, operations for inserting some content and the operation for inserting the closing delimiter, the first operation has to insert both delimiters to avoid unbalanced delimiters:

| ⇒ (|) ⇒ … ⇒ (foo|) ⇒ (foo)|

With this editing model, it is not allowed to insert an opening delimiter by itself. This is also true for closing delimiters (see move-past-closing-delimiter)

Generic Function: maybe-move-past-closing-delimiter [text.editing] cursor closing &key whitespace ¶

If the item after cursor is equal to the character closing, move cursor forward past the closing delimiter.

whitespace which must be either nil or :move-past or :delete controls the behavior in case there are whitespace items between cursor and the item that is equal to closing. If whitespace is nil and there are such items, cursor does not move. If whitespace is :move-past, cursor moves past the whitespace items and past the closing delimiter. If whitespace is :delete, the whitespace items are deleted, and cursor is moved passed the closing delimiter.

Return true if cursor has moved and false otherwise.

Generic Function: move-past-closing-delimiter [text.editing] cursor closing &key whitespace ¶

If the item after cursor is equal to the character closing, move cursor forward past the closing delimiter.

whitespace controls the behavior in case cursor is separated from the closing delimiter by whitespace. See maybe-move-past-closing-delimiter for details.

The return value of this function is unspecified.

If the item after cursor, either immediately after or the first non-whitespace item after, is not equal to cursor, signal an error of type no-closing-delimiter-error.

This function is intended to be used as a structure-preserving replacement for “ordinary” operations that insert an “heterogeneous” (that is, for example ) but not ") closing delimiter: When a user performs the operation for inserting the opening delimiter, operations for inserting some content and the operation for inserting the closing delimiter, the first operation has to insert both delimiters and the final operation simply has to move past the closing delimiter:

| ⇒ (|) ⇒ … ⇒ (foo|) ⇒ (foo)|

With this editing model, it is never necessary and in fact never allowed to insert a closing delimiter by itself which is why this function signals an error if there is no closing delimiter to move past. This is also true for opening delimiters (see insert-delimiter-pair).

Generic Function: move-past-closing-delimiter-or-insert-delimiter-pair [text.editing] cursor delimiter &key whitespace ¶

If the item after cursor is equal to the character delimiter, move cursor forward past the (assumed to be) closing delimiter. If the item after cursor is not equal to the character delimiter, insert delimiter before cursor and insert delimiter after cursor.

whitespace controls the behavior in case cursor is separated from the closing delimiter by whitespace. See maybe-move-past-closing-delimiter for details.

Return true if a pair of delimiters has been inserted and false otherwise.

This function is intended to be used as a structure-preserving replacement for “ordinary” operations that insert a “homogeneous” (that is, for example " but not )) delimiter: When a user performs the operation for inserting delimiter, operations for inserting some content and the operation for inserting delimiter again, the first operation has to insert delimiter twice and the final operation simply has move past the second delimiter:

| ⇒ "|" ⇒ … ⇒ "foo|" ⇒ "foo"|

With this editing model, it is never necessary and in fact never allowed to insert a single delimiter by itself which is why this function inserts a delimiter pair if there is no closing delimiter to move past.

Examples:

  (move-past-closing-delimiter-or-insert-delimiter-pair cursor #\") in
  "foo|"
⇒ "foo"|

  (move-past-closing-delimiter-or-insert-delimiter-pair cursor #\") in
  (length |)
⇒ (length "|")

Generic Function: delete-delimiter-pair-or-item [text.editing] cursor direction &key if-not-empty ¶

If there is one, delete the pair of delimiter characters which contains cursor. Otherwise delete an item in direction.

In this context, a delimiter pair contains cursor, if either the delimiter characters surround cursor or if direction is :forward and the opening delimiter is the item after cursor or if direction is :backward and the closing delimiter is the item before cursor.

if-not-empty controls the behavior in case the operation is applied to a delimiter pair that is not empty in the sense that the opening and the closing delimiter surround other buffer items:

nil

Do nothing, do not move cursor and do not delete any items.

:move-past

Move cursor past the “obstructing” delimiter and into the delimited content so that subsequent deletion operations will delete the content item by item until the delimited content is empty and the delimiter pair can be deleted.

:delete-inside

Do not move cursor but delete one item from the content that is delimited by the “obstructing” delimiter. This behavior can be repeated until the delimited content is empty and the delimiter pair can be deleted.

a-function

Call the supplied function with two arguments, cursor and an description of the “obstacle” which is either :outside or :inside. The function can delete items near cursor or move cursor as appropriate.

The return value of this function is unspecified.

This function is intended to be used as a structure-preserving replacement for “ordinary” operations that delete a single item: If the to-be-deleted item is a closing delimiter or an opening delimiter, the “opposite” delimiter has to be deleted in the same operation to maintain delimiter balance. If the to-be-deleted item is not a delimiter, the task can be delegated to the “ordinary” deletion operation.

Examples:

(delete-delimiter-pair-or-item cursor :forward) in
  |()
⇒ |

(delete-delimiter-pair-or-item cursor :forward) in
  (|)
⇒ |

(delete-delimiter-pair-or-item cursor :forward :if-not-empty if-not-empty) in
  (foo|)
⇒ (foo|)  when if-not-empty is nil
⇒ (foo)|  when if-not-empty is :move-past
⇒ (fo|)   when if-not-empty is :delete-inside

(delete-delimiter-pair-or-item cursor :forward :if-not-empty if-not-empty) in
  |(foo)
⇒ |(foo)  when if-not-empty is nil
⇒ (|foo)  when if-not-empty is :move-past
⇒ |(oo)   when if-not-empty is :delete-inside

Generic Function: surround-with-delimiter-pair [text.editing] cursor unit direction opening &key closing count ¶

Surround the item sequence between cursor and the location that would result from moving cursor count times by unit in direction with the delimiters opening and closing.

If supplied, closing is a character that should be used as the closing delimiter of the pair. If closing is not supplied, the result of evaluating (closing-delimiter opening) is used.

If supplied, count controls how many units as indicated by unit should be surrounded by the inserted delimiters. If count is not supplied, a single unit is used.

The return value of this function is unspecified.

Examples:

(surround-with-delimiter-pair cursor word :forward #\") in
  |foo bar
⇒ "|foo" bar

(surround-with-delimiter-pair cursor word :forward #\" :count 2) in
  |foo bar
⇒ "|foo bar"

(surround-with-delimiter-pair cursor word :backward #\( :count 2) in
  foo bar| baz
⇒ (foo bar|) baz

4.2.1 Search Conditions

The conditions of the following types are signaled by functions in the search module:

Class: already-in-incremental-search-error [text.editing.search] ¶

An error of this type is signaled when an operation that starts an incremental search is performed when an incremental search is already associated with the buffer.

Class: not-in-incremental-search-error [text.editing.search] ¶

An error of this type is signaled when an operation that works only in the context of an incremental search is performed when no incremental search is associated with the buffer.

Class: no-next-match-error [text.editing.search] ¶

An error of this type is signaled when the next-match operation is performed on a cursor for which there is no following match and wrap-around is false or there are no matches at all.

Class: no-previous-match-error [text.editing.search] ¶

An error of this type is signaled when the previous-match operation is performed on a cursor for which there is no preceding match and wrap-around is false or there are no matches at all.

4.2.2 Search State Protocol

The search state protocol specifies generic functions that operate on a buffer search state while an incremental search is being performed.

The search state protocol extends the Detach Protocol, that is, search states can (and must) be detached. When detached, a search state detaches all its matches.

Generic Function: start [text.editing.search] search-state ¶

Return a cursor that represents the buffer location at which the incremental search represented by search-state started.

Generic Function: query [text.editing.search] search-state ¶

Return the current query sequence for search-state.

The returned sequence must not be modified. extend-query and truncate-query must be used instead.

Generic Function: case-mode [text.editing.search] search-state ¶

Return the case mode, which is either :ignore or :match, of search-state.

Generic Function: (setf case-mode) [text.editing.search] new-value search-state ¶

Set the case mode of search-state to new-value which must be either :ignore or :match.

Calling this function causes search-state to be rebuilt via rebuild-state.

Generic Function: match-count [text.editing.search] search-state ¶

Return the number of matches contained in search-state.

Generic Function: map-matches [text.editing.search] function search-state ¶

Call function with each match in search-state.

Generic Function: matches [text.editing.search] search-state ¶

Return a sequence of the matches in search-state.

Generic Function: add-match [text.editing.search] search-state buffer start end ¶

Add a match in buffer between the cursors start and end to search-state.

Return the newly created match object.

Generic Function: remove-match [text.editing.search] search-state buffer match ¶

Remove match from search-state.

The default method on this generic function detaches match and, if a site search state refers to match, replaces that reference with another match.

Generic Function: initial-matches [text.editing.search] search-state ¶

Compute the initial matches for search-state based on the start cursor and the query sequence.

Call add-match for each computed match.

Generic Function: rebuild-state [text.editing.search] search-state ¶

Rebuild search-state from scratch, that is remove the current matches and use initial-matches to compute new matches.

Generic Function: finish [text.editing.search] search-state ¶

Finish the incremental search represented by search-state leaving all point cursors at their current locations.

Generic Function: abort [text.editing.search] search-state ¶

Abort the incremental search represented by search-state moving all point cursors the locations at which they were positioned before the incremental search started.

Generic Function: description [text.editing.search] search-state &key comment ¶

4.2.3 Match Protocol

The match protocol extends the Detach Protocol, that is matches can (and must) be detached.

Generic Function: next [text.editing.search] match ¶

Return the next match after match or nil if there is no next match.

Generic Function: previous [text.editing.search] match ¶

Return the previous match before match or nil if there is no previous match.

Generic Function: start [text.editing.search] match ¶

Return a cursor which marks the start of match.

Generic Function: end [text.editing.search] match ¶

Return a cursor which marks the end of match.

Generic Function: item-matches-p [text.editing.search] state match query-item ¶

Indicate whether match extended with query-item matches the buffer sub-sequence corresponding to match.

4.2.4 Site Search State Protocol

The site search state protocol extends the Detach Protocol, that is site search states can (and must) be detached.

Generic Function: start [text.editing.search] site-search-state ¶

Return a cursor which indicates the location at which the point cursor of the site associated with site-search-state was positioned before the start of the incremental search.

Generic Function: match [text.editing.search] site-search-state ¶

Return the match associated with site-search-state or nil.

Class: site-search-state [text.editing.search] ¶

Instances of this class store a start cursor and a match that should be associated with a site in the context of an incremental search.

4.2.5 Buffer Search State Protocol

The sole purpose of the buffer search state protocol is retrieving the search state associated with a given buffer:

Generic Function: search-state [text.editing.search] buffer ¶

Return the search state associated with buffer or nil if there is none.

Class: search-state-mixin [text.editing.search] ¶

This class is intended to be mixed into buffer classes that implement the buffer search state protocol.

Methods on add-match and remove-match specialized to this class take care of associating sites (or the site) of the buffer with the nearest match(es) as matches are added and removed.

4.2.6 Ordinary Search Operations

Generic Function: search [text.editing.search] target query direction ¶

Search for occurrences of query in the underlying buffer of target from each site in direction.

target can be a buffer, a site or a cursor. In any of those cases, the search will include all sites of the underlying buffer.

query is the sequence of items to search for.

direction can be either :forward or :backward and controls in which direction point cursors should move towards the nearest occurrence of query in the buffer.

TODO case mode etc.

4.2.7 Incremental Search Operations

Generic Function: incremental-search [ext.editing.search] target direction ¶

Start an incremental search in the underlying buffer of target.

target can be a buffer, a site or a cursor. In any of those cases, the incremental search will include all sites of the underlying buffer.

Create a buffer search state and associate it with the underlying buffer of target. The search state starts out with an empty query sequence and an empty set of matches. For each site in the buffer, create a site search state that is initially not associated with any match (as there are no matches initially). Return the created buffer search state.

If there already is an incremental search associated with target, signal an error of type already-in-incremental-search-error.

Generic Function: finish-incremental-search [text.editing.search] target ¶

Finish the incremental search associated with target

Keep all point cursors at the locations to which they were moved due to search operations.

target can be a buffer, a site or a cursor. In any of those cases, the incremental search will include all sites of the underlying buffer.

If there is no incremental search associated with target, signal an error of type not-in-incremental-search-error.

Generic Function: abort-incremental-search [text.editing.search] target ¶

Abort the incremental search associated with target.

In particular, move all involved point cursors back to the locations at which they resided before the incremental search started.

target can be a buffer, a site or a cursor. In any of those cases, the incremental search will include all sites of the underlying buffer.

If there is no incremental search associated with target, signal an error of type not-in-incremental-search-error.

Generic Function: convert-matches-to-sites [text.editing.search] target ¶

Finish the search involving target, and add a site at the location of each match (except for the match that is associated with the primary site).

target can be a buffer, a site or a cursor. In any of those cases, the operation will affect the incremental search state associated with the underlying buffer.

If there is no incremental search associated with target, signal an error of type not-in-incremental-search-error.

warning: Performing this operation on an incremental search state that already involves more than one site is currently not supported. A suitable behavior for that situation may be specified in the future.

Generic Function: extend-query [text.editing.search] target item ¶

Add item at the end of the query sequence of the incremental search associated with target.

target can be a buffer, a site or a cursor. In any of those cases, the operation will affect the incremental search state associated with the underlying buffer.

Extending the query sequence can lead to matches being modified or removed from the current set of matches. Point cursors can also move to different locations as a result.

If there is no incremental search associated with target, signal an error of type not-in-incremental-search-error.

Generic Function: truncate-query [text.editing.search] target &key count ¶

Remove count items from the end of the query sequence of the incremental search associated with target.

target can be a buffer, a site or a cursor. In any of those cases, the operation will affect the incremental search state associated with the underlying buffer.

count is a positive integer no greater than the length of the query sequence.

Truncating the query sequence can lead to matches being modified and new matches being added to the current set of matches. Point cursors can also move to different locations as a result.

If there is no incremental search associated with target, signal an error of type not-in-incremental-search-error.

Generic Function: next-match [text.editing.search] target &key wrap-around ¶

In the search involving target, move all point cursors to the respective next match.

target can be a buffer, a site or a cursor. In any of those cases, the incremental search will include all sites of the underlying buffer.

wrap-around controls the behavior in case there is no next match when a point cursor should be moved to the next match. If there is no next match and wrap-around is false or there are no matches at all, signal an error of type no-next-match-error.

If there is no incremental search associated with target, signal an error of type not-in-incremental-search-error.

Generic Function: previous-match [text.editing.search] target &key wrap-around ¶

In the search involving target, move all point cursors to the previous match.

target can be a buffer, a site or a cursor. In any of those cases, the incremental search will include all sites of the underlying buffer.

wrap-around controls the behavior in case there is no previous match when a point cursor should be moved to the previous match. If there is no previous match and wrap-around is false or there are no matches at all, signal error of type no-previous-match-error.

If there is no incremental search associated with target, signal an error of type not-in-incremental-search-error.

5.2.1 Expression Conditions

Class: cursor-not-inside-expression-error [text.editing.expression] ¶

This error is signaled when an operation that requires an expression which contains cursor is attempted and no such expression exists.

Class: no-expression-after-cursor-error [text.editing.expression] ¶

This error is signaled when an operation that requires an expression after the cursor is attempted and no such expression exists.

Class: no-expression-before-cursor-error [text.editing.expression] ¶

This error is signaled when an operation that requires an expression before the cursor is attempted and no such expression exists.

Class: expression-at-toplevel-error [text.editing.expression] ¶

This error is signaled when an operation that requires a non-toplevel expression before or after the cursor is attempted and no such expression exists.

Class: expression-does-not-have-children-error [text.editing.expression] ¶

This error is signaled when an operation that requires an expression with children is attempted on an expression that does not have any children.

Class: no-expression-after-expression-error [text.editing.expression] ¶

This error is signaled when an operation that requires an expression after some designated expression is attempted and no such expression exists.

Class: no-expression-before-expression-error [text.editing.expression] ¶

This error is signaled when an operation that requires an expression before some designated expression is attempted and no such expression exists.

5.2.2 Expression Node Protocol

The purpose of the expression node protocol is to allow this library to inspect nodes of an expression tree that is constructed and managed by a client of this library. Accordingly, this library does not define methods on the following generic functions. Instead, clients are expected to define methods that are suitable for the expression representation used by the respective client.

Generic Function: range [text.editing.expression] expression ¶

Return the source range, that is the start and end buffer positions, of expression as four values

1. The start line number of expression
2. The start column number of expression
3. The end line number of expression
4. The end column number of expression

Generic Function: children [text.editing.expression] expression ¶

Return a possibly empty sequence of child expressions of expression. The elements of the returned sequence are ordered according to their respective start locations and do not overlap.

5.2.3 Expression Tree Protocol

The purpose of the expression tree protocol is to allow this library to query an expression tree that is constructed and managed by a client of this library. Accordingly, this library does not define all required methods on the following generic functions. Instead, clients are expected to define methods (or at least one method) that are suitable for the expression tree representation used by the respective client. For this protocol, it is sufficient for each client to define a method that is suitable for the respective expression tree presentation on the generic function map-expressions-containing-cursor-using-buffer.

For the description of the protocol functions in this section, we need the following definition: Let r_s , the start relation, and r_e , the end relation, be either < or ≤ respectively. An expression with start location s and end location e contains a cursor c with respect to r_s and r_e iff r_s(s,c) ∧r_e(c,e) .

Generic Function: map-expressions-containing-cursor [text.editing.expression] function cursor syntax-tree &key start-relation end-relation ¶

Call function for each expression in the buffer of cursor that contains cursor with respect to start-relation and end-relation. The return value of this function is unspecified. For more information about the parameters and behavior, see map-expressions-containing-cursor-using-buffer.

The default method on this generic function calls map-expressions-containing-cursor-using-buffer with the buffer that cursor is associated with.

Generic Function: map-expressions-containing-cursor-using-buffer [text.editing.expression] function buffer cursor syntax-tree &key start-relation end-relation ¶

Call function for each expression in buffer that contains cursor with respect to start-relation and end-relation. If multiple expressions contain cursor, the call for a given expression precedes the calls for the ancestors of that expression in the expression tree, that is innermost or leaf expressions are processed first, outermost or toplevel expressions are processed last.

syntax-tree selects the syntax tree in which expressions should be considered. For example, the buffer of cursor may have an associated concrete syntax tree and also an abstract syntax tree.

Both start-relation and end-relation which must be either the symbol < or the symbol <= select the respective relation.

The return value of this function is unspecified.

Generic Function: expressions-containing-cursor [text.editing.expression] cursor syntax-tree &key start-relation end-relation count ¶

Return a possibly empty sequence of expressions in the buffer of cursor that contain cursor with respect to start-relation and end-relation. If count is supplied, its value must be a non-negative integer. In that case, the number of elements in the returned sequence is limited to that number. For more information about the behavior and the other parameters, see map-expressions-containing-cursor-using-buffer.

The default method on this generic function calls map-expressions-containing-cursor and collects the provided expressions, stopping when count expressions have been collected if applicable.

Function: innermost-expression-containing-cursor [text.editing.expression] cursor syntax-tree &key start-relation end-relation ¶

Return the innermost expression in the buffer of cursor that contains cursor with respect to start-relation and end-relation or nil if there is no such expression. For more information about the behavior and the other parameters, see map-expressions-containing-cursor-using-buffer.

Function: outermost-expression-containing-cursor [text.editing.expresssion] cursor syntax-tree &key start-relation end-relation ¶

Return the outermost expression in the buffer of cursor that contains cursor with respect to start-relation and end-relation or nil if there is no such expression. For more information about the behavior and the other parameters, see map-expressions-containing-cursor-using-buffer.

5.2.4 Expression Operations

The operations described in this section are designed to, in conjunctions with the operations on delimiter pairs, enable structural editing of buffer contents.

Generic Function: raise [text.editing.expression] cursor unit direction ¶

Raise the innermost expression e which contains, follows or precedes cursor by deleting the buffer items that make up the parent of e and the siblings of e but preserving the buffer items that make up e .

unit must be expression at the moment.

direction which must be either :forward or :backward controls whether the expression e should follow or precede cursor.

The return value of this function is unspecified.

After the operation, cursor resides in the same relative location with respect to the preserved buffer item as before the operation.

When there is no such expression, signal no-expression-after-cursor-error or no-expression-before-cursor-error, depending on direction.

Examples:

(raise cursor expression :forward) in
  1 2 (3 4 |5 6) 7 8
⇒ 1 2 |5 7 8

(raise cursor expression :backward) in
  1 2 (3 4 |5 6) 7 8
⇒ 1 2 |5 7 8

Generic Function: splice [text.editing.expression] cursor unit direction ¶

Splice expressions e₁ to e_n that follow or precede cursor by replacing the buffer items that make up the expression which contains cursor with the buffer items that make up e₁ to e_n .

unit must be expression at the moment.

If direction is :forward, expressions that follow cursor are preserved. If direction is :backward, expressions that precede cursor are preserved. If direction is nil, expressions that follow and precede cursor are preserved.

The return value of this function is unspecified.

After the operation, cursor resides in the same relative location with respect to the preserved buffer items as before the operation.

When there is no such expression, signal cursor-not-inside-expression-error.

Examples:

(splice cursor expression nil) in
  1 2 (3 4 |5 6) 7 8
⇒ 1 2 3 4 |5 6 7 8

(splice cursor expression :forward) in
  1 2 (3 4 |5 6) 7 8
⇒ 1 2 |5 6 7 8

(splice cursor expression :backward) in
  1 2 (3 4 |5 6) 7 8
⇒ 1 2 3 4| 7 8

Generic Function: split [text.editing.expression] cursor unit ¶

Split the innermost expression or toplevel expression e that contains cursor by inserting the a copy of the buffer items that make up the closing delimiter of e before cursor and a copy of the buffer items that make up the opening delimiter of e after cursor.

If unit is expression, e is the innermost expression that contains cursor. If unit is toplevel-expression, e is the toplevel expression that contains cursor. Other values of unit are not supported at the moment.

The return value of this function is unspecified.

After the operation, cursor resides between the buffer items that make up the two new expressions.

When there is no such expression, signal cursor-not-inside-expression-error.

Examples:

(split cursor expression) in
  (1 (2 |3) 4)
⇒ (1 (2 )|(3) 4)

(split cursor toplevel-expression) in
  (1 (2 |3) 4)
⇒ (1 (2 ))|((3) 4)

Generic Function: join [text.editing.expression] cursor unit ¶

Join the innermost expressions e₁ and e₂ that precede and follow cursor respectively by deleting the buffer items that make up the closing delimiter of e₁ and the buffer items that make up the opening delimiter of e₂ .

unit must be expression at the moment.

The return value of this function is unspecified.

After the operation, cursor resides between the buffer items that make up the two child expressions of the joined expressions that were the last and first child of e₁ and e₂ respectively.

When there is no expression either following or preceding cursor, signal no-expression-after-cursor-error or no-expression-before-cursor-error, respectively.

Example:

(join cursor expression) in
  (1 2) |(3 4)
⇒ (1 2 |3 4)

Generic Function: eject [text.editing.expression] cursor unit direction ¶

Assuming an expression e (or possibly other unit as specified by unit) contains cursor, depending on direction, move the last child of e after the end of e or move the first child of e before the start of e .

unit must be expression at the moment.

direction must be either :forward or :backward. If direction is :forward, move the last child of e after the end of e . If direction is :backward, move the first child of e before the start of e

After the operation, cursor is still contained in e .

If cursor is not contained in any expression, signal cursor-not-inside-expression-error. If the expression e does not have any children, signal expression-does-not-have-children-error.

Examples:

(eject cursor expression :forward) in
  (1 2 3 4|)
⇒ (1 2 3|) 4

(eject cursor expression :backward) in
  (1 2 |3 4)
⇒ 1 (2 |3 4)

Generic Function: absorb [text.editing.expression] cursor unit direction ¶

Assuming an expression e contains cursor and a “target” expression t follows or precedes e , depending on direction, move t into e .

• If e is a toplevel expression, try to find the target expression before or after e in the sequence of toplevel expressions.
• If e is not toplevel expression, try to find the target expression before or after e in the children of p , the parent of e . If there is no suitable target expression among the children of p , repeat the process with p instead of e . In other words, look for a suitable target expression before or after each ancestor of e proceeding from the innermost expression (which is e ) to the toplevel ancestor of e .

unit must be expression at the moment.

direction must be either :forward or :backward. If direction is :forward, move a “target” expression that follows e into e as the last child. If direction is :backward, move a “target” expression that precedes e into e as the first child.

After the operation, cursor is at the same location relative to the unmodified boundary of e as before.

If cursor is not contained in any expression, signal cursor-not-inside-expression-error. When there is no expression either following or preceding (an ancestor of) e , signal no-expression-after-expression-error or no-expression-before-expression-error, respectively.

Examples:

(absorb cursor expression :forward) in
  (1 2 | 3) 4
⇒ (1 2 | 3 4)

(absorb cursor expression :backward) in
  1 (|2 3 4)
⇒ (1 |2 3 4)

Generic Function: delete-semi-line-or-expressions [text.editing.expression] cursor direction ¶

For cursor located on line l , delete to either the end of l or to the end of some expression which starts on l so that delimiters are kept balanced.

direction controls whether to delete from cursor towards the end of the line or towards the beginning of the line. At the moment, direction has to be :forward.

Examples:

(delete-semi-line-or-expressions cursor :forward) in
  (1 |2 (3 4) 5)
⇒ (1 |)

(delete-semi-line-or-expressions cursor :forward) in
  (1 |2 (3
         4)
        5)
⇒ (1 |
        5)

(delete-semi-line-or-expressions cursor :forward) in
  1 |2 (3
        4)
  5
⇒ 1 |
  5