Appendix C — The command-line editor

C.1 Preliminaries

When the GNU readline library is available at the time R is configured for compilation under UNIX, an inbuilt command line editor allowing recall, editing and re-submission of prior commands is used. Note that other versions of readline exist and may be used by the inbuilt command line editor: this is most common on macOS. You can find out which version (if any) is available by running extSoftVersion() in an R session.

It can be disabled (useful for usage with ESS ¹) using the startup option --no-readline.

¹ The ‘Emacs Speaks Statistics’ package; see the URL https://ESS.R-project.org/

Windows versions of R have somewhat simpler command-line editing: see Console under the Help menu of the GUI, and the file README.Rterm for command-line editing under Rterm.exe.

When using R with GNU² readline capabilities, the functions described below are available, as well as others (probably) documented in man readline or info readline on your system.

² It is possible to build R using an emulation of GNU readline, such as one based on NetBSD’s editline (also known as libedit), in which case only a subset of the capabilities may be provided.

³ On a PC keyboard this is usually the Alt key, occasionally the ‘Windows’ key. On a Mac keyboard normally no meta key is available.

Many of these use either Control or Meta characters. Control characters, such as Control-m, are obtained by holding the CTRL down while you press the m key, and are written as C-m below. Meta characters, such as Meta-b, are typed by holding down META³ and pressing b, and written as M-b in the following. If your terminal does not have a META key enabled, you can still type Meta characters using two-character sequences starting with ESC. Thus, to enter M-b, you could type ESCb. The ESC character sequences are also allowed on terminals with real Meta keys. Note that case is significant for Meta characters.

Some but not all versions⁴ of readline will recognize resizing of the terminal window so this is best avoided.

⁴ In particular, not versions 6.3 or later: this is worked around as from R 3.4.0.

C.2 Editing actions

The R program keeps a history of the command lines you type, including the erroneous lines, and commands in your history may be recalled, changed if necessary, and re-submitted as new commands. In Emacs-style command-line editing any straight typing you do while in this editing phase causes the characters to be inserted in the command you are editing, displacing any characters to the right of the cursor. In vi mode character insertion mode is started by M-i or M-a, characters are typed and insertion mode is finished by typing a further ESC. (The default is Emacs-style, and only that is described here: for vi mode see the readline documentation.)

Pressing the RET command at any time causes the command to be re-submitted.

Other editing actions are summarized in the following table.

C.3 Command-line editor summary

C.3.1 Command recall and vertical motion

C-p

Go to the previous command (backwards in the history).

C-n

Go to the next command (forwards in the history).

C-r text

Find the last command with the text string in it. This can be cancelled by C-g (and on some versions of R by C-c).

On most terminals, you can also use the up and down arrow keys instead of C-p and C-n, respectively.

C.3.2 Horizontal motion of the cursor

C-a

Go to the beginning of the command.

C-e

Go to the end of the line.

M-b

Go back one word.

M-f

Go forward one word.

C-b

Go back one character.

C-f

Go forward one character.

On most terminals, you can also use the left and right arrow keys instead of C-b and C-f, respectively.

C.3.3 Editing and re-submission

text

Insert text at the cursor.

C-f text

Append text after the cursor.

DEL

Delete the previous character (left of the cursor).

C-d

Delete the character under the cursor.

M-d

Delete the rest of the word under the cursor, and “save” it.

C-k

Delete from cursor to end of command, and “save” it.

C-y

Insert (yank) the last “saved” text here.

C-t

Transpose the character under the cursor with the next.

M-l

Change the rest of the word to lower case.

M-c

Change the rest of the word to upper case.

RET

Re-submit the command to R.

The final RET terminates the command line editing sequence.

The readline key bindings can be customized in the usual way via a ~/.inputrc file. These customizations can be conditioned on application R, that is by including a section like

$if R
  "\C-xd": "q('no')\n"
$endif

Footnotes