How to insert snippets from a menu

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

# How to insert snippets from a menu

This guide shows how to set up reusable pieces of text and put them into a file at the cursor. It assumes Turbo Python is already installed.

## Get a starter file

Start the editor **from the project's own directory**, then choose **Snippets ▸ Create snippets file** (`Alt-N`, then `C`).

That writes `.turbo-python/snippets.toml`, filled in with a few worked examples, and opens it — coloured, because Turbo Python colours TOML:

```toml
[[snippet]]
name = "if err != nil"
group = "Python"
languages = ["python"]
body = """
if err != nil {
	return err
}"""

[[snippet]]
name = "TODO"
body = "TODO: "
```

Each `[[snippet]]` becomes one line of the menu. The file is read every time the menu opens, so editing it takes effect immediately — no restart.

## Insert one

Open **Snippets** (`Alt-N`). Snippets sharing a `group` appear together in a submenu of that name; one with no group goes into **General**.

| Key | Effect |
| --- | --- |
| `Alt-N`, or `F10` then `→` to Snippets | Open the menu |
| `↑` `↓` | Move down the groups |
| `→`, or `Enter` | Open the highlighted group |
| `↑` `↓` then `Enter` | Insert the highlighted snippet |
| `←` | Back out of a group |
| `Escape` | Put the whole menu away |

The snippet goes in at the cursor. **Lines after the first are indented to match the line you inserted it on**, so a multi-line snippet dropped into a nested block lands where you would have typed it:

```
func f() {
	|                              ← cursor here
}
```

becomes

```
func f() {
	if err != nil {
		return err
	}
}
```

It is one undo step: `Ctrl-Z` takes the whole snippet back out.

## Keep snippets across every project

Put them in `~/.config/turbo-python/snippets.toml` — the same directory your own themes go in. Those appear in every project, and a project's own file adds to them rather than replacing them.

Where a project and you use the same `name` in the same `group`, **the project's wins**: it is the more specific statement of the two.

## Show a snippet only where it makes sense

Add `languages`, using the names the editor uses — `python`, `toml`, `markdown`, `javascript`, `html`, `bash`:

```toml
[[snippet]]
name = "strict mode"
group = "Shell"
languages = ["bash"]
body = "set -euo pipefail"
```

That snippet then appears only when a shell script is the front window. Leave `languages` out and the snippet is offered everywhere, which is what you want for a licence header or a `TODO`.

A group left with nothing after filtering does not appear at all.

## Variants

- **You started the editor from a subdirectory.** The project's file is not found: only `./.turbo-python` is looked at, the same rule `settings.toml` follows. Your own snippets still appear.
- **The file has a mistake in it.** The menu shows a greyed-out `Cannot read snippets` where the groups would be, and **Create snippets file** is still there. Open the file and fix it.
- **You want tabs in a body.** Write `\t`, as the starter file does — TOML turns it into a tab when it reads the file.

## See also

- Every key of the file and every rule: [Snippets reference](../reference/snippets.md)
- Why the menu is rebuilt each time it opens, and why insertion re-indents: [Snippets](../explanation/snippets.md)
- The other file in `.turbo-python`: [Project settings](../reference/project-settings.md)