Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Automagically pair braces and quotes in emacs like TextMate

tree: a2d3e89c0a

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 README.org
Octocat-spinner-32 autopair-tests.el
Octocat-spinner-32 autopair.el
Octocat-spinner-32 logo.png * First googlecode commit
README.org

Autopair is an extension to the Emacs text editor that automatically pairs braces and quotes:

  • Opening braces/quotes are autopaired;
  • Closing braces/quotes are autoskipped;
  • Backspacing an opening brace/quote autodeletes its pair.
  • Newline between newly-opened brace pairs open an extra indented line.

Autopair works well across all Emacs major-modes, deduces from the language’s syntax table which characters to pair, skip or delete. It should work even with extensions that redefine such keys.

Installation and basic use:

To try it out, download the latest version and add to your .emacs:

(add-to-list 'load-path "/path/to/autopair") ;; comment if autopair.el is in standard load path 
(require 'autopair)
(autopair-global-mode) ;; enable autopair in all buffers

Rationale

I developed autopair to work just like TextMate or better, be minimally intrusive to my existing hacks and need very little customization. You might prefer it to the following:

It also works with YASnippet, another package I maintain.

Neat tricks

  • autopair-autowrap tells autopair to automatically wrap the selection region with the delimiters you’re trying to insert.
  • autopair-blink makes the cursor quickly blink over matching braces and quotes just inserted or skipped over. If you find this behaviour annoying, set this to nil.
  • autopair-skip-whitespace, when set to non-nil, tells autopair to skip over whitespace when attempting to skip over a closing brace. If you set this to ‘chomp, the whitespace is not only jumped over but also deleted.

Autopair’s idea is to always do-what-you-mean, but since some people are never satisfied, have a look at the following:

Optional tricks

You shouldn’t need this, but to enable autopair in just some types of buffers, comment out the `autopair-global-mode` and turn on `autopair-mode` in some major-mode hook, like:

;; use autopair just in c buffers
 
(add-hook 'c-mode-common-hook 
          #'(lambda () (autopair-mode)))

Alternatively, do use autopair-global-mode and create exceptions using the major mode hooks (watch out for the change in behaviour emacs 24).

;; use autopair everywhere but c buffers
 
(add-hook 'c-mode-common-hook
           #'(lambda () 
               (setq autopair-dont-activate t) ;; for emacsen < 24
               (autopair-mode -1))             ;; for emacsen >= 24
)

More tricks

autopair-dont-pair lets you define special cases of characters you don’t want paired. Its default value skips pairing single-quote characters when inside a comment literal, even if the language syntax tables does pair these characters.

As a further example, to also prevent the { (opening brace) character from being autopaired in C++ comments use this in your .emacs.

(add-hook 'c++-mode-hook
          #'(lambda ()
               (push ?
                     (getf autopair-dont-pair :comment))))

autopair-handle-action-fns lets you write some emacs-lisp that overrides/extends the actions taken by autopair after it decides something must be paired, skipped or deleted. To work with triple quoting in python mode, you can use this for example:

(add-hook 'python-mode-hook
          #'(lambda ()
              (setq autopair-handle-action-fns
                    (list #'autopair-default-handle-action
                          #'autopair-python-triple-quote-action))))

where autopair-python-triple-quote-action is an example of a user-written function (which is bundled in autopair.el).

See this issue for an example of clever use of this variable (thanks alexduller).

autopair-extra-pairs lets you define extra pairing and skipping behaviour for pairs not programmed into the syntax table. Watch out, this is work-in-progress, a little unstable and does not help balancing at all. To have < and > pair in c++-mode buffers, but only in code, use:

(add-hook 'c++-mode-hook
          #'(lambda ()
              (push '(?< . ?>)
                    (getf autopair-extra-pairs :code))))

if you program in emacs-lisp you might also like the following to pair backtick (`) and quote (=’=).

(add-hook 'emacs-lisp-mode-hook
          #'(lambda ()
              (push '(?` . ?')
                    (getf autopair-extra-pairs :comment))
              (push '(?` . ?')
                    (getf autopair-extra-pairs :string))))

Workarounds

Once you set autopair-global-mode everything mostly just works but a few extensions use tricks that interfere with autopair’s own tricks, disabling autopair or some of the extension’s functionality. Using the customization techniques described above, there are plenty of very good workarounds for slime-mode, latex-mode, term-mode and even viper-mode.

See the workaround list.

How it works

The extension works by rebinding the braces and quotes keys, but can still be minimally intrusive, since the original binding is always called as if autopair did not exist.

The decision of which keys to actually rebind is taken at minor-mode activation time, based on the current major mode’s syntax tables. To achieve this kind of behaviour, an Emacs variable emulation-mode-map-alists was used.

If you set autopair-pair-criteria and autopair-skip-criteria to the symbol help-balance (which, by the way, is the default), braces are not autopaired/autoskipped in all situations; the decision to autopair or autoskip a brace is taken according to the following table:

+---------+------------+-----------+-------------------+
| 1234567 | autopair?  | autoskip? | notes             |
+---------+------------+-----------+-------------------+
|  (())   |  yyyyyyy   |  ---yy--  | balanced          |
+---------+------------+-----------+-------------------+
|  (()))  |  ------y   |  ---yyy-  | too many closings |
+---------+------------+-----------+-------------------+
|  ((())  |  yyyyyyy   |  -------  | too many openings |
+---------+------------+-----------+-------------------+

The table is read like this: in a buffer with 7 characters laid out like the first column, an “y” marks points where an opening brace is autopaired and in which places would a closing brace be autoskipped. Quote pairing tries to support similar “intelligence”.

Something went wrong with that request. Please try again.