Navigate and edit text objects with Emacs
Branch: master
Clone or download

README.asc

GNU ELPA MELPA Stable MELPA

Objed - The text object editor

A global minor-mode to navigate and edit text objects. Objed also enables modal editing and composition of commands. It combines ideas of versor-mode and other Editors like Vim or Kakoune and tries to align them with regular Emacs conventions.

For more information you can read my posts about objed and for changes check the News file.

Introduction

Text objects are textual patterns like a line, a top level definition, a word, a sentence or any other unit of text. When objed-mode is enabled, certain editing commands (configurable) will activate objed and enable its modal editing features. When active, keys which would usually insert a character are mapped to objed commands. Other keys and commands will continue to work as they normally would and exit this editing state again.

By default important editing keys like Space, DEL or Return are not bound to modal commands and will execute the regular command and exit objed. Character movement exits objed, as well. This makes it convenient to move around and continue by adding/deleting text.

With activation objed shows the current object type in the mode-line. The textual content of the object is highlighted visually in the buffer and the cursor color is changed, too. The user can now navigate by units of this object, change the object state or switch to other object types.

The object state is either inner or whole and is indicated in the modeline by (i) or (w) after the object type. With inner state, anything that would be considered delimiters or padding around an object is excluded.

The user can apply operations to objects. By marking objects before applying an operation, s?he can even operate on multiple objects at once. This works similar to the way you interact with files in dired. When marking an object the point moves on to the next object of this type.

The object type used for initialization is determined by the mapping of the entry command (see objed-cmd-alist). For example using beginning-of-defun will activate objed using the defun object as initial object type. With command next-line, objed would initialize with the line object. To activate objed without movement you can use objed-activate, bound to M-SPC by default. It uses the last command and its mapping in objed-command-alist to choose the initial object.

Objeds modal state provides basic movement commands which move by line, sexp or word. Those switch automatically to the corresponding object type. Other commands only activate the part between the initial position and the new position moved to. By repeating commands you can often expand/proceed to other objects. This way you can compose movement and editing operations very efficiently.

The expansion commands distinguish between block objects (objects built out of lines of text) and context objects (programming constructs like strings, brackets or textual components like sentences). This way you can quickly expand to the desired objects.

For example to move to the end of the paragraph, the user would first move to the end of the line with Ctrl - e. This would activate objed using the line object with the text moved over. The user can now continue to the end of the paragraph by pressing e again. Now s?he is able to proceed even further by pressing e again OR to continue by adding new text to the end of the paragraph OR to continue by acting on the text moved over, for example killing it by pressing k.

As often with text editing, the explanation sounds more complicated than using it. To get a better impression of the editing workflow with objed I have added some animated demos below.

To learn more about available features and commands have a look at the descriptions below, the commentary section or the docstrings and bindings defined in objed-map. To define your own operations and text objects see objed-define-op and objed-define-object.

Note that objed is still evolving, some bindings might change in this process. Because of that the following screencasts might not always show up to date key bindings.

Examples of usage

Object navigation
Figure 1. Object navigation

Object expansion
Figure 2. Object expansion

End of block expansion
Figure 3. End of block expansion

Upto context
Figure 4. Upto context

Marking objects and act on them
Figure 5. Marking objects and act on them

Mark objects inside another one
Figure 6. Mark objects inside another one

Select current object type with avy
Figure 7. Select current object type with avy

Navigate and search output object
Figure 8. Navigate and search output object

Keys

Although some features are still experimental the basic user interface will stay the same. The following gives an overview of available keys and commands. If commands allow for numeric arguments you can input them without the use of Ctrl or Meta. 0 can be used as an alternative for the universal argument (C-u).

In addition to the commands configured in objed-cmd-alist you can use the following commands to enter objed (those bindings are only active if you are using objed-mode, if you choose to activate objed always manually you have to bind those commands in you global-map):

[objed-mode-map]

Shortcut

Purpose

C-+/C-.

Move to previous/next identifier and activate identifier object.

M-[

Activate object at point (determined from context) and move to its start.

M-]

Activate object at point (determined from context) and move to its end.

M-SPC

Activate objed, choosing initial object based on last-command and objed-cmd-alist.

Basic movement commands (switch the object type on movement):

[objed-map]

Shortcut Purpose

f/b

Move forward/backward one sexp and activate the sexp object

s/r

Move forward/backward one word and activate the word object.

n/p

Move to the next/previous line and activate the line object.

Commands for block objects (objects built out of lines of text):

[objed-map]

Shortcut Purpose

h

Activate (line based) object at point and move to its start. On repeat proceed to beginning of the indentation block, comment block, paragraph or other block objects.

a

Move to beginning of line and activate the text moved over. On repeat proceed to beginning of blocks like explained above.

e

Move to end of line and activate the text moved over. On repeat proceed to end of blocks like explained above.

Commands for context objects. Those objects are common programming constructs like defuns, strings, parentheses but also sentences inside comments for example. Any whitespace after point is skipped before determining the context:

[objed-map]

Shortcut Purpose

o

Activate the inner part of the object at point and move to the start. This is useful to act on the content of the string, brackets and so on. On repeat expand to other objects around current position.

j

Move point to the other side of the current object.

t

Toggle the state of the current object (inner/whole).

[/]

If coming from basic movement the object at point is guessed based on context. Point is moved to the beginning/end of object at point. This is useful to "jump out" of the current context. On repeat move to the previous/next instance of current object type

(/)

Move to inner beginning/end of the object at point and activate the text moved over.

{/}

Move forward/backward paragraph and switch to paragraph object

</>

Goto first/last instance of current object type (blog).

Commands to switch objects (and move point to its start, repeating an object command mark all instances in current defun/buffer):

[objed-map]

Shortcut

Purpose

.

Switch to identifier object or move to next.

,

Switch to identifier object and move to previous.

_

Switch to symbol object.

c

Prefix to switch to other objects, see objed-object-map for available objects and objed-define-object to add your own (blog).

Indent/Move objects around:

[objed-map]

Shortcut Purpose

C-left/C-right

Move/indent all lines in object right/leftward.

M-left/M-right

Move/indent all lines in object to right/leftward to tab stop.

S-left/S-right/S-up/S-down/F/B

Move current object type forward/backward (blog).

S/R

Switch to word object and move it forward/backward.

N/P

Switch to line object and move it forward/backward.

Commands to edit objects (applying operations to them). When the region is active the operation acts on the current region. To act on multiple objects at once you can mark them first (see the "Misc commands" below):

[objed-map]

Shortcut Purpose

i

Delete current object(s) and switch to insert.

k

Kill current object(s).

d

Delete current object(s).

w

Copy current object(s). On repeat move to next and append it to kill-ring

y

Yank last killed text at point. On repeat, cycle through kill-ring

\

Indent object(s).

;

Un/comment object(s).

%

Query replace narrowed to current object.

!

Replace object(s) with minibuffer input.

&

Pipe object region through shell command.

|

Incrementally construct command chain to replace text (blog).

Ctrl - RET

Evaluate current object in REPL (need eval-in-repl to be installed).

M - RET

Insert new (empty) instance of current object type. This inserts the current object without the inner content.

S - RET

Comment and duplicate object.

$

Spell check textual content of object using flyspell.

~

Undo in current object region.

'

Add surroundings to object(s) with any pair using electric (built-in).

x

Prefix to access other operations, see objed-op-map for available operations and objed-define-op to add your own.

Misc commands:

[objed-map]

Shortcut Purpose

q

Quit window if not the only one.

l

Pop to last state, which restores the last position and any object data.

M-o

Choose an instance of current object type with completion, using the contents of the first line for completion.

`

Choose an instance of current object type on the screen with avy (blog).

m

Add/Remove current object to marked objects and move to next.

M

Add/Remove current object to marked objects and move to previous.

v

Activate region with current object (extend current object).

Ctrl - Space

Set mark.

/

Undo last edit command.

?

Get key binding help (uses which-key if available).

g/Ctrl - g

Exit and deactivate objed.

Dispatch keys (dispatch to any object defined in objed-object-map). You can add your own prefix bindings using objed-define-dispatch.

[objed-map]

Shortcut Purpose

*

Mark more instances of current object inside defun/buffer.

#

Switch to another object using avy.

u

Activate part from point forward until boundary of some object.

z

Activate part from point backward until boundary of some object.

-/+

Extend current object forward/backward by including leading/trailing whitespace.

Installation

Objed is on MELPA and GNU ELPA, for installation use:

M-x package-refresh-contents RET
M-x package-install RET objed RET
;; activate objed-mode in you init
(objed-mode)

For manual installation:

git clone http://github.com/clemera/objed.git

Add this to your init file:

(add-to-list 'load-path "/<path-to>/objed")
(require 'objed)
(objed-mode)
;; activating the mode is optional, you can activate objed
;; always manually using `objed-activate' the other
;; commands bound in `objed-mode-map`, for example:
;; (global-set-key (kbd "M-SPC") 'objed-activate)

Contribute

I’m happy to receive pull requests or ideas to improve this package. Some parts suffer from the bottom up approach of developing it, but this also allowed me to experiment a lot and try ideas while working on them, something that Emacs is especially good at. Most of the features are tested using emacs-lisp-mode but hopefully there aren’t to many problems using modes for other languages. Before submitting a PR please check your code compiles cleanly and all tests are passing:

make test

This package is subject to the same Copyright Assignment policy as Emacs itself, org-mode, CEDET and other packages in GNU ELPA.

Any legally significant contributions can only be accepted after the author has completed their paperwork. Please see the request form if you want to proceed with the assignment.