Bracketed-paste

Bracketed paste (sometimes referred to as paste bracketing ), is a mode of some terminal emulators which allows programs running in the terminal to treat pasted text differently from text typed normally.

History

The bracketed paste feature was introduced by xterm in 2002, as a user-contributed change to improve interaction with Emacs. Later, in 2005, another user documented this as part of another select/paste feature for the JOE editor. Over the course of several years, other developers adapted the feature for terminal emulators and editors which work with this feature.

Motivation

Bracketed paste is used to resolve the following issue, commonly encountered when editing code in a terminal text editor (such as Vim or Emacs). These text editors often include autoindent functionality, which causes indentation to be added automatically when the user presses the enter key at the end of a line. For example, suppose we are editing the following code block in a text editor, with the cursor position marked by the | character.

def f():
    print('foo')|

If the user presses enter, text editors will often advance the cursor to the location marked in the next code block.

def f():
    print('foo')
    |

This can have unintended consequences when pasting code which is already formatted. For example, suppose the user intends to copy the following block of code into a file.

def g():
    print('hello')
    print('world')

In a typical workflow, the user starts by selecting the block of code and copying it to their system clipboard. Then, they select the target location in their file, and issue a paste command. The terminal emulator then send the characters from the clipboard to the text editor, and the text editor may not be able to differentiate between, for example, a d character that came from the clipboard and one which came from the user pressing the D key on her keyboard. The newlines in the code block are treated the same way as would be presses of the enter key by the user. So, when the newline at the end of the first line is sent to the text editor, if autoindent is enabled, the text editor will insert an indent (several spaces or a tab character). Next, the terminal emulator will transmit the space characters corresponding to the spaces at the beginning of the second line of the block of code on the clipboard, resulting in double-indentation. Furthermore, in this context, typical autoindent behavior would be to match the indentation level of the second line when starting the third, which would result in the third line being triple-indented. The final result might look something like the following.

def g():
        print('hello')
            print('world')

Description of bracketed-paste

Terminal emulators (such as xterm and iTerm2) allow programs to configure the terminal emulators' behavior via escape codes, or control sequences.

The usual way this is done is that a user program prints a control sequence to standard out, and the terminal emulator reads standard out, notices the control sequence, and reacts as appropriate. In particular, terminal emulators may provide control sequences that turn bracketed-paste on and off. A text editor may send the control sequence to turn on bracketed-paste at startup, or in response to a user command.

Thereafter, characters typed by the user normally will be forwarded to the text editor by the terminal emulator normally. However, if the user issues a paste command in the terminal emulator, the terminal emulator will insert special control sequences at the beginning and end of the pasted text – it will bracket the pasted contents – enabling the text editor to treat that input differently (for example, to turn autoindentation off temporarily).

Each implementation uses the control sequences documented in xterm's control sequences:

• ESC [ 200 ~ to signify the beginning of pasted text and
• ESC [ 201 ~ to signify the end.