Wrapping

1. Repeated wrapping
2. Wrapping with tags

(This feature is only partially implemented. Permission system is not supported yet. This means auto wrapping works everywhere if it is turned on. However, this isn't such a big deal as auto-insertion of pairs, since it only activates with active region)

If you select a region and start typing any of the pairs, the active region will be wrapped with the pair. For multi-character pairs, a special insertion mode is entered, where point jumps to the beginning of the region. If you insert a complete pair, the region is wrapped and point returns to the original position.

If you insert a character that can't possibly complete a pair, the wrapping is cancelled, the point returns to the original position and the typed text is inserted. If you use delete-selection-mode or cua-delete-selection, the content of the region is removed first.

At any time in the insertion mode you can use C-g to cancel the insertion. In this case, both the opening and closing pairs are removed and the point returns to the original position. The region is not deleted even if some "delete-selection" mode is active.

If sp-autodelete-wrap is t (by default on) the most recent wrap can be removed if you invoke delete-backward-char (usually bound to backspace key) immediately after the wrapping is done.

You can use functions sp-select-next-thing and sp-select-previous-thing to activate a region around next or previous expression for convenient wrapping. Read tips and tricks for more suggestions.

# Repeated wrapping

After wraping a region and immediately afterward inserting another basic pair (that is, defined by sp-add-pair), it is often desired to apply this pair as another wrap around the just wrapped region. Imagine, in LaTeX mode, wrapping "word" with quotes to produce `word'. Now, hitting another backtick should produce double-quoted word ``word''. The same can apply to markdown-mode and * character to mark italics/bold text.

You can now variable sp-wrap-repeat-last to "No repeat", "Repeat only if same", "Re-wrap region with any pair". Read the built-in description for more info. By default, wrap is only repeated if you use the same pair as the last wrapping.

Note that this behaviour is only active if you type in the pair immediately after the wrapping without invoking any additional command, such as backspace or navigation command. However, since this is mostly intended for single character pairs, this does not impose any real limitation.

# Wrapping with tags

Wrapping with more structured tags is also supported. For example, in html-mode you might want to automatically wrap a region some code and change it into <span class="code">some code</span>. For this purpose, you can define tag pairs. These allow you to enter special tag wrapping insertion mode, where you can enter arbitrary text. It also automatically mirror the opening tag text into the closing tag. Furthermore, the closing tag can be automatically transformed with any function to a different string. For example, the opening tag's content span class="code" can be transformed to just span.

The tag wrapping pairs have higher priority than regular tags, that is, if it is possible to start tag-wrapping, the regular wrap mode is exited and the tag insertion mode is entered even if there is possible continuation of the currently inserted opening wrap pair. For example, if tag insertion trigger is < and there is a regular pair << >>, this is ignored and the tag insertion mode is entered immediately after < is inserted.

Tags are defined by following function:

;; this pair is already present by default. `sp-match-sgml-tags' cuts
;; off everything after the first space: "span class='x'" -> "span".
(sp-add-tag-pair "<" "<_>" "</_>" 'sp-match-sgml-tags '(sgml-mode html-mode))

;; this pair is already present by default.
(sp-add-tag-pair "\\b" "\\begin{_}" "\\end{_}" 'identity '(tex-mode latex-mode))

where the arguments are:

1. Tag trigger
2. Opening tag format
3. Closing tag format
4. Transformation function for closing tag. You can use built-in function identity to return the tag unchanged
5. Modes where this is allowed. Tag pairs can't be defined globally. The rationale is that they are highly specialized and the idea of specific tags for specific modes makes more sense.

The character _ in the format strings is replaced with the inserted text and mirrored to the closing pair. Before inserting text in the closing pair, content of the opening pair is transformed with transformation function. Only one _ per pair is allowed. The closing tag does not have to contain _ (then no text is inserted there). If the opening pair doesn't have _ either, the tag is simply inserted as text and tag insertion mode is not entered. This can be used to form "shortcuts" for commonly used wrappings, such as:

(sp-add-tag-pair "2" "**" "**" nil 'markdown-mode)

to mark selected text as bold.

If the transformation function is nil, it automatically defaults to identity. Otherwise, it should be a one-argument function that accepts the content of the opening pair and as output gives the content of the closing pair.

Note that you always have to supply something for transformation function. The last argument is a "vararg" of modes where the tag should apply. If you do not supply a transformation function, the first entered mode will be assumed to be a transformation function, and that's not what you want.

You can add different tags for the same trigger in different modes. The mode sets must not overlap, otherwise random one is picked (the behaviour is undefined).

Tags can be removed with sp-remove-tag-pair function, which takes as arguments the trigger and the mode where you want to remove it.

(sp-remove-tag-pair "<" 'sgml-mode) ;; modes can also be list of modes

When in tag insertion mode, special key-bindings are active. These are:

• C-a, C-e jumps to the beginning/end of the tag section.
• C-g terminate the tag insertion mode.

Tag insertion mode is also terminated if you leave the area of the opening tag pair overlay, for example with search function or previous-line command.