# -*- mode: 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 [[http://autopair.googlecode.com/git/autopair.el][latest version]] and add to your =.emacs=:

#+BEGIN_EXAMPLE
(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
#+END_EXAMPLE

* Rationale

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

  - http://www.emacswiki.org/emacs/ParEdit
  - http://code.google.com/p/emacs-textmate/
  - http://github.com/ramblex/emacs-textmate
  - http://svn.ruby-lang.org/repos/ruby/trunk/misc/ruby-electric.el (most of it)
  - the options listed in http://www.emacswiki.org/emacs/AutoPairs

  It also works with [[http://github.com/capitaomorte/yasnippet/][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:

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

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

#+BEGIN_EXAMPLE
;; 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
)
#+END_EXAMPLE

* 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.

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


  =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:

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

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

  See [[http://code.google.com/p/autopair/issues/detail?id=13][this issue]] for an example of clever use of this variable (thanks
  [[http://code.google.com/u/alexduller/][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:

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

  if you program in emacs-lisp you might also like the following to
  pair backtick (=`=) and quote (='=).
  
#+BEGIN_EXAMPLE
(add-hook 'emacs-lisp-mode-hook
          #'(lambda ()
              (push '(?` . ?')
                    (getf autopair-extra-pairs :comment))
              (push '(?` . ?')
                    (getf autopair-extra-pairs :string))))
#+END_EXAMPLE

* 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 [[http://code.google.com/p/autopair/issues/detail?id=20&can=1&q=status:Workaround][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:

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

  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".
