text.editing User’s Manual
This manual is for text.editing version 0.1.0.
Table of Contents
1 Introduction
The text.editing library provides manipulation functions for the contents of text buffers that are required by, for example, commandline processors, input editors and text editors.
text.editing does not provide
- Data structures for editor buffers (the cluffer library does that)
- Input handling or a command processor
- Presentation/rendering/display functions for the contents of text buffers
2 Concepts
- Buffer
-
A buffer is conceptually a sequence of lines, each of which contains a sequence of items and zero or more attached cursors.
text.editing does not provide an implementation of the buffer concept or associated protocols. Instead, it uses the protocols and classes provided by the cluffer library.
- Cursor
-
A cursor is an object that is attached to a buffer line before this first item, after the last item or between to adjacent items.
text.editing does not provide an implementation of the cursor concept or associated protocols. Instead, it uses the protocols and classes provided by the cluffer library.
- Point
-
The point is a distinguished cursor which specifies the buffer location at which the next editing operation issued by a user will be performed.
- Mark
-
The mark is a distinguished cursor
- Region
-
TODO
- Unit
-
Unit are a way to designate particular sub-sequences of the sequence of all items in a buffer, often relative to the point cursor. For example, the
:wordunit refers to a sequence of non-whitespace, non-punctuation characters that follow (or precede depending on the specified direction) the mark cursor. - Site
-
A “site” ties together pieces of data that are required for performing consecutive editing operations around a specific “location”, or site, in a buffer. The most important piece of data is the point cursor which makes precise the notion of a buffer “location”. Other pieces of data include a mark, a mark stack and an insertion stack.
The main reason for storing this data in a dedicated site object instead of directly in a buffer is the possibility of allowing simultaneous editing at multiple sites in a buffer. From the perspective of an editor user, each site would typically appear as a cursor (with its own point, mark, insertion stack, etc.) which would generally act as if it were the only cursor in the buffer (disregarding effects that arise from sites being too close together or overlapping).
Mention primary site, adding/removing sites, cycling through primary sites
TODO preferred column of a cursor could also be stored in site
- Mark Stack
- Insertion Stack
-
The insertion stack is a stack the elements of which are recently copied or killed sequences of buffer items which can be inserted into a buffer. “Kill” and “yank” operations push and pop this stack.
This concept is similar to the “Kill Ring” in Emacs with the following differences:
- As the name suggests, the Emacs kill ring can grow to a maximum number of items after which it will start discarding the least recent elements. In practice however, Emacs is often configured to keep a practically unlimited number of kill ring elements. The insertion stack is unlimited by default.
- The Emacs kill ring is global by default and has to be restricted to a local context for extended functionality like editing with multiple cursors. In contrast, each insertion stacks is local to a specific site by default.
The following figure illustrates important concepts and their relations:
Figure 2.1: Examples of important concepts and their relations for a single buffer.
2.1 Units
Sites, units and operations are the basic concepts from which most desired behaviors can be constructed. Here are a few examples:
| Operation | Unit | Direction | Equivalent Emacs command |
|---|---|---|---|
| move | item | forward | forward-char (C-f) |
| move | item | backward | backward-char (C-b) |
| move | word | forward | forward-word (M-f) |
| move | word | backward | backward-word (M-b) |
| move | line | forward | next-line (C-n) |
| move | line | backward | previous-line (C-p) |
| delete | item | forward | delete-char (C-d) |
| delete | item | backward | delete-backward-char (<backspace>) |
| delete | word | forward | kill-word (M-d) |
| delete | word | backward | backward-kill-word (M-<backspace>) |
| delete | line | forward | kill-line (C-n) |
| delete | line | backward | kill-line with 0 prefix (C-0 C-n) |
2.1.1 Built-in Units
| Unit | Description |
|---|---|
:word | Word |
:line | Line |
:paragraph | Paragraph |
:expression | Expression |
:buffer-boundary | Start or end of buffer |
:buffer | Whole buffer |
3 External Protocols
This chapter describes the external protocols provided by the text.editing library.
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 Protocol for a higher-level protocol on top of this one.
- 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-itemandcluffer:join-line.
- Generic Function: (setf forward) [text.editing] new-value insertion-entry ¶
- 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 ¶
- 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 ¶
- Generic Function: top-entry [text.editing] insertion-stack ¶
- Generic Function: find-entry [text.editing] index insertion-stack ¶
- Generic Function: push-entry [text.editing] insertion-stack ¶
- Generic Function: pop-entry [text.editing] insertion-stack ¶
3.2 Site Protocol
- Generic Function: point [text.editing] site ¶
Return the point cursor of site.
The returned object is a cluffer cursor
- Generic Function: goal-column [text.editing] site ¶
Return the column number in which the point of site should reside by default.
The point cursor should be placed in that column or the closest existing column of the current line when the point cursor moves between lines without moving within any line.
- Generic Function: mark [text.editing] site ¶
Return the mark cursor of site.
The returned object is a cluffer cursor
- Generic Function: mark-active? [text.editing] site ¶
Indicate whether the mark cursor of site is active.
- Generic Function: (setf mark-active?) [text.editing] new-value site ¶
Change whether the mark cursor of site is active.
new-value is a generalized Boolean.
- Generic Function: set-mark [text.editing] site ¶
Set the mark cursor of site to the position of the point cursor.
TODO describe other effects
- Generic Function: mark-stack [text.editing] site ¶
TODO
- Generic Function: insertion-stack [text.editing] site ¶
Return the insertion stack of site.
The returned object implements the Insertion Stack Protocol.
- Generic Function: detach [text.editing] (object) ¶
Detach object from any buffer or line it is currently attached to
3.3 Buffer Protocol
- Generic Function: site [text.editing] buffer ¶
TODO
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:sequencecontaining 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:sequencenew-value.
3.4 Multiple Cursors Protocol
- Generic Function: other-sites [text.editing] buffer ¶
Return the sequence of all sites which are attached to buffer except the primary site.
- Generic Function: site-count [text.editing] buffer ¶
Return the number of sites that are attached to buffer.
- 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 ¶
TODO
- Generic Function: remove-site [text.editing] site buffer ¶
TODO
- Generic Function: add-site-at [text.editing] buffer line position ¶
TODO
- Generic Function: add-site-relative [text.editing] buffer unit direction ¶
TODO
- Generic Function: rotate-sites [text.editing] buffer direction ¶
TODO
3.5 Operation Protocol
- Generic Function: apply-from-cursor [text.editing] continuation cursor unit direction ¶
TODO
- Generic Function: perform [text.editing] target operation
&restoperation-arguments ¶ TODO
3.6 Movement and Editing Protocol
note: The operations described in this section can be invoked by calling the respective generic function. However, a more flexible way which, for example, handles multiple sites correctly is the Operation Protocol. The following code invokes an operation operation via that protocol
(text.editing:perform buffer 'operation unit direction other-arguments)
- 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.
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.
- Generic Function: delete [text.editing] cursor unit direction ¶
Delete the sub-sequence of buffer items indicated by cursor, unit and direction.
- Generic Function: delete-indentation [text.editing] cursor ¶
TODO
- 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.
case has to be one of
:down,:upor:capitalize.
- Generic Function: transpose [text.editing] cursor unit direction ¶
TODO
TODO fill operation
3.7 Copy and Yank Protocol
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: copy [text.editing] site unit direction ¶
Copy items indicated by the point cursor of site, unit and direction into a new top entry of the insertion stack of site.
- Generic Function: yank [text.editing] site
&keydirection ¶ Insert the items from the top entry of the insertion stack of site at the point cursor of site.
TODO there is no actual generic function at the moment
Concept index
| Jump to: | B C I M P R S U |
|---|
| Index Entry | Section | ||
|---|---|---|---|
| | |||
| B | |||
| buffer: | Concepts | ||
| | |||
| C | |||
| cursor: | Concepts | ||
| | |||
| I | |||
| insertion stack: | Concepts | ||
| insertion stack: | Insertion Stack Protocol | ||
| | |||
| M | |||
| mark: | Concepts | ||
| mark stack: | Concepts | ||
| | |||
| P | |||
| point: | Concepts | ||
| | |||
| R | |||
| region: | Concepts | ||
| | |||
| S | |||
| site: | Concepts | ||
| site: | Site Protocol | ||
| | |||
| U | |||
| unit: | Concepts | ||
| | |||
| Jump to: | B C I M P R S U |
|---|
Function and macro and variable and type index
| Jump to: | (
A B C D E F G I M O P R S T Y |
|---|
| Jump to: | (
A B C D E F G I M O P R S T Y |
|---|
Changelog
No change history yet