Permalink
Fetching contributors…
Cannot retrieve contributors at this time
153 lines (129 sloc) 6.71 KB

Welcome to Smartparens's documentation!

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. 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 Getting Started below.

  • support for pairs of any length, for example "\{" "\}" pair used in LaTeX to typeset literal braces in math mode. These are fully :ref:`user definable and customizable<pair-management>`. Pairs can have same or different strings for opening and closing part.
  • intelligent handling of closing pairs. If user types (, (|) is inserted. If then the user 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.
  • :ref:`Jumping around<working-with-expressions>` the pairs (extending forward-sexp and similar functions to custom user pairs)
  • Functions to :ref:`manipulate<working-with-expressions>` 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.

Getting Started

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 :ref:`installation` manual.

The :ref:`quick tour<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.

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

Migrating from paredit

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 :ref:`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.

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

Contributing

We love contributions. It is most awesome if they come with tests. Read about our :ref:`testing<testing>` infrastructure.

Contents

.. toctree::
   :maxdepth: 2

   automatic-escaping
   pair-management
   permissions
   example-configuration


Indices and tables