Home

1. What is this package about?
2. Video presentation
3. Information for new users
   1. Are you casual emacs user?
   2. Are you experienced emacs user?
4. Are you an elisp developer?

Welcome to the smartparens wiki! Here, you can find all the up-to-date documentation for spartparens package.

You should read the important announcements about the latest releases of smartparens if you already are a user. This page includes latest developement and changes that might "break" backward compatibility.

What is this package about?

Smartparens is modern minor mode for Emacs that deals with parens pairs and tries to be smart about it. It is an unification and enhancement effort to combine funcitonality of several existing packages in a single, common and straightforward way. These packages include autopair, textmate, wrap-region, paredit and others with similar philosophies. It also adds support for many more features. Here's a highlight of some features, for a complete list and detailed documentation look in the following section.

• support for pairs of any length (currently up to 10 characters), for example "\{" "\}" pair used in LaTeX to typeset literal braces in math mode. These are fully user definable and customizable. Pairs can have same or different strings for opening and closing part.
• inteligent handling of closing pair. If user types (, (|) is inserted. If he then types word) the result is (word)| not (word)|). This behaviour is cancelled if user moves backwards during editing or move point outside of the pair.
• automatic deletion of complete pairs. With pair ("\{" "\}"), \{|\} and backspace will remove both delimiters. \{\}| and backspace will remove the closing pair, and result in \{|. Hitting backspace again will remove the opening pair.
• when followed by the same opening pair or word, do not insert the whole pair. That is: |() followed by ( will produce (|() instead of (|)(). Similarly, |word followed by ( will produce (|word. (This behaviour can be turned off).
• wraps region in defined pairs or special structured tag pairs for "tag-modes" (xml/html...). Different tags are supported, for example, languages that would use {tag} instead of <tag> or LaTeX's \begin{} \end{} pair. Everything is user definable as usual.
• automatically escape strings if wrapped with another string. this "string" turns to "this \"string\"" automaticaly.
• automatically escape typed quotes inside a string.
• Jumping around the pairs (extending forward-sexp and similar functions to custom user pairs)
• Functions to manipulate s-expressions, delete, wrap and unwrap, extend and contract...

Almost all features are fully customizable via M-x customize-group smartparens. You can turn many behaviours on or off to fit your workflow.

Video presentation

If you like watching screencasts better than reading documentation, there's also a youtube presentation. It's in 2 parts because youtube didn't allow me to upload it in one video. Switch to 480p! Note that this presentation only talks about features up to commit ~40, so many of the newer features are not covered (those will hopefully be covered in future video).

Information for new users

Here, you can find an information about installation, all the features and example configurations.

Are you casual emacs user?

If so, you might want to check out the quick tour to get smartparens installed and operational in a few minutes. Actually, you might want to check it out anyway :)

You should also spend a minute and read about the compatibility issues. We try to code smartparens in a generic enough way to not to interfere with other packages, but sometimes clashes are unavoidable. If you happen to have "weird" problems, chances are you are using a package that is incompatible with smartparens. In that case, please report the issue on the tracker so we may (hopefully) fix it.

Are you experienced emacs user?

The process of installing smartparens is as simple as calling package-install. However, if you want to learn in detail what packages smartparens depend on and what settings it modifies in order to function, read the installation manual.

Here's a list of features smartparens provide, complete with detailed explanation on how to fine-tune it to your very own taste.

• Pair management. How do add and remove pairs, how to overload global pairs locally.

• Auto pairing. How to set permissions for each pair, to restrict in which modes and which contexts it is permitted to automatically insert the closing pair.

• Wrapping. Automatically wrap active regions with pairs or structured tags (for example html tags). Learn how to add or remove tags and how you can customize wrapping to fit your needs.

• Automatic escaping. Were you ever annoyed by quote escaping in strings? Well, no more! Learn how you can let smartparens do the boring for you.

• Navigation. Navigating balanced expressions is a powerful way to move around in buffers and edit code. Learn how you can quickly jump back and forth around the paired expressions.

• Expression manipulation. Extend, contract, split, splice, wrap, unwrap and much more! How to quickly transform your elisp (or any other!) code with powerful manipulation functions.

• Show smartparens mode. Do you want to see where a pair starts and where it ends? Turn on the show-smartparens-mode and let smartparens highlight the pairs.

• Example configuration. Authors current working smartparens configuration. See how the knowledge you've just obtained work in practice.

• Default configuration. Smartparens ships with powerful default configuration. Chances are that you won't even need to configure anything at all! Look at the internals and see how is smartparens configured by default.

Are you an elisp developer?

If you are, check out these articles about the internals of spartparens! There are many interesting functions you can use in your own code that deal with pairs and navigation.

• How to use structural functions in my own code. Create powerful functions that operate on pair delimited structures.
• Hooks and advices smartparens modify, this is mostly for the situations where you would modify pre/post command hooks and want to learn how smartparens modify them.

And of course, if you write some cool plugin or extension for smartparens, or have an idea how to do it, contribute!