# Auto Surround

Auto Surround places matching characters around selected text.

For example, select `hello` in a Markdown file. Type `*`. *Lx* changes it to:

```md
*hello*
```

The word stays selected. Type `*` again to get:

```md
**hello**
```

You do not need to move the cursor or select the word again.

## Turn Auto Surround on or off

Auto Surround is off by default. Turn it on in your settings:

```lua
config.auto_surround = true
```

Turn it off again with:

```lua
config.auto_surround = false
```

When it is off, typing replaces selected text as usual.

## Characters supported by Markdown

Markdown currently supports these characters:

- `*` can repeat up to three times
- `_` can repeat up to three times
- `~` always uses exactly two on each side
- A backtick can repeat up to four times

For example, select `hello` and type `~`. *Lx* produces valid Markdown strikeout:

```md
~~hello~~
```

It does not produce one or three tildes.

Other file types can offer their own choices. If a character is not supported, normal typing continues.

## What happens at the repeat limit

Each choice can have its own repeat limit.

At the limit, *Lx* can stop, return to the first valid repeat, or remove the surrounding characters. The current file type chooses this when it needs special behavior.

Otherwise, this setting supplies the usual choice:

```lua
config.auto_surround_behavior = "unwrap"
```

You can use:

- `"stop"` to leave the text at its repeat limit
- `"cycle"` to return to the first valid repeat
- `"unwrap"` to remove the surrounding characters

## Using several selections

Auto Surround works with one or several selections.

Every selection must contain text on one line. If one selection is empty, normal typing continues for all of them.

## Surround from the command palette

The `format:surround` command lets you choose the result directly. It has no shortcut by default.

Open the command palette and enter one of the calls below.

These calls work even when Auto Surround is turned off.

Choose one kind of call at a time:

- Use `preset` for a choice supplied by the current file type
- Use `text` when both sides should match
- Use `open` and `close` when the two sides should differ

Do not mix these choices in one call.

### Use a choice from the current file type

```text
format:surround(preset: "*")
```

This uses the `*` choice supplied by the current file type. In Markdown, it follows the same repeat rules as typing `*` around a selection.

The preset decides how repetition works. Do not add `depth` to this call.

If the current file type does not offer that choice, *Lx* leaves the text unchanged.

### Use the same text on both sides

```text
format:surround(text: "*", depth: 3)
```

This turns selected `hello` into:

```md
***hello***
```

`depth` says how many times the text should repeat on each side. If you leave it out, *Lx* uses one.

Use a whole number of one or more.

This call works in any editable text file. It does not need a choice from the current file type.

### Use different text on each side

```text
format:surround(open: "(", close: ")", depth: 2)
```

This turns selected `hello` into:

```text
((hello))
```

`open` is placed on the left. `close` is placed on the right. You need to provide both.

## Ask for an exact result

The `text`, `open`, and `close` calls give you an exact result.

Suppose the word is already surrounded:

```md
*hello*
```

Select only `hello`, then run:

```text
format:surround(text: "*", depth: 3)
```

*Lx* replaces the matching surroundings and produces:

```md
***hello***
```

It does not add three more pairs on top of the existing pair.

## Calls at a glance

Use the current file type's choice:

```text
format:surround(preset: "*")
```

Use the same text on both sides:

```text
format:surround(text: "*", depth: 3)
```

Use different text on each side:

```text
format:surround(open: "(", close: ")", depth: 2)
```
