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?
   3. Are you paredit user?
4. Are you an elisp developer?

Welcome to the smartparens wiki!

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.

Sometimes, parts of the pages on this wiki are quoted like this:

this is an information about a legacy feature

These parts are notes about legacy features to provide context for old users when a feature or configuration changes.

# What is this package about?

Smartparens is minor mode for Emacs that deals with parens pairs and tries to be smart about it. It started as a unification effort to combine functionality of several existing packages in a single, compatible and extensible way to deal with parentheses, delimiters, tags and the like. Some of these packages include autopair, textmate, wrap-region, electric-pair-mode, paredit and others. With the basic features found in other packages it also brings many improvements as well as completely new 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.
• intelligent handling of closing pairs. If user types (, (|) is inserted. If he then types word) the result is (word)| not (word)|).
• 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. You can also set it to skip over the pairs to keep the structure balanced instead by enabling smartparens-strict-mode (a la paredit).
• wraps active 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.
• 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).

NEW: Presentation number two on navigation commands is up!

# Information for new users

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

After you familiarize yourself with smartparens, make sure to read tips and tricks to get that extra 20% of coolness out of it ;)

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

The quick tour lists the most basic use cases, while here follows 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.

• Permissions. How to set permissions for each pair, to restrict in which modes and which contexts it is permitted to automatically insert the closing pair or wrap the active region.

• Action hooks. How to set up hooks to perform custom operations before or after smartparens actions.

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

• Hybrid S-expressions. Sometimes, S-expressions just aren't going to cut it. Learn how to edit (not only) "line based" languages (C, Java, C#,...) in a way that helps you to keep the delimiters balanced.

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

• User interface. Smartparens provide a few user-interface features, like highlighting currently "active" region between pair delimiters and during wrapping. If the defaults doesn't fit your color scheme, read this section and learn how to customize it.

• Example configuration. Author's current working smartparens configuration. See how the knowledge you've just obtained works 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 paredit user?

Among other features, smartparens also replicate a lot of paredit functionality and extend it to arbitrary pairs and modes. It also provides many improvements like adding numeric or raw prefix arguments to modify the behaviour of these commands. Read the Paredit and smartparens article for comparsion of paredit and smartparens features.

# 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!