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

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 modern minor mode for Emacs that deals with parens pairs and tries to be smart about it. It is a unification and enhancement effort to combine funcitonality of several existing packages in a single, common and straightforward way (and most of all compatible). 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)|).
• 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.
• 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.
• automatically escape strings if wrapped with another string. this "string" turns to "this \"string\"" automaticaly.
• 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.

After you familiarize 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.

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.

• 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. Also set up post insertion hooks to perform custom operations 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.

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