Reference: snippets

  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
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

# Reference: snippets

> Neutral description of the snippets files, the Snippets menu, and how a snippet is inserted.

## Files

Both are read, and both are optional.

| File | Holds |
| --- | --- |
| `./.turbo-python/snippets.toml` | The project's snippets |
| `$TURBO_PYTHON_SNIPPET_DIR/snippets.toml`, else `<user config>/turbo-python/snippets.toml` | Your own, shared across projects |

`<user config>` is `os.UserConfigDir()`: `~/.config` on Linux, `~/Library/Application Support` on macOS.

| Property | Value |
| --- | --- |
| Project search | The working directory only. Parent directories are **not** searched. |
| Read | Every time the Snippets menu opens |
| Order | Your own first, then the project's |
| Name clash | Same `group` **and** `name` → the project's replaces yours |
| Missing file | Not an error |
| Unreadable file | An error, shown in the menu |

## File format

One `[[snippet]]` table per snippet.

| Key | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | What the menu shows |
| `body` | string | yes | The text inserted at the cursor |
| `group` | string | no | The submenu it goes in; absent means `General` |
| `languages` | array of strings | no | Restricts the snippet to those languages; absent means every file |

`languages` uses the editor's own language names: `python`, `toml`, `yaml`, `markdown`, `javascript`, `html`, `xml`, `dockerfile`, `bash`. See [Languages coloured](languages.md).

A snippet with no `name` or no `body` makes the whole file an error — it could not be shown or could not be inserted.

### Example

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

TOML's `"""` strings drop the newline immediately after the opening quotes, and interpret `\t` as a tab.

## The menu

| Item | Condition |
| --- | --- |
| One submenu per group, in the order the groups first appear in the files | A group with at least one snippet applying to the front window |
| `Cannot read snippets`, greyed out | A file is present but unreadable |
| `Create snippets file` | The project has no snippets file |
| `Open snippets file` | The project has one |

The menu's hot key is `Alt-N`, not `Alt-S`: Search already answers to S.

Groups, and the snippets inside them, come out in the order they were read, so the menu matches the files.

A snippet item is greyed out when there is no file open to insert into — a terminal or the project tree in front counts as no file.

### Filtering

| Front window | Snippets offered |
| --- | --- |
| A file of a recognised language | Those naming that language, plus those naming none |
| A file of no recognised language | Those naming none |
| A terminal, the project tree, or nothing | Those naming none |

## Insertion

| Behaviour | Detail |
| --- | --- |
| Position | At the cursor |
| First line | Inserted where the cursor is |
| Later lines | Prefixed with the leading whitespace of the line the cursor was on |
| Blank lines in the body | Left blank, not padded with whitespace |
| Undo | One step for the whole snippet |
| Cursor after | At the end of the inserted text |
| Report | `Snippet inserted` on the status bar |

The indent copied is the **whitespace prefix of the current line**, tabs or spaces as they were, so a snippet follows whatever the file already uses.

## Menu items

| Item | Menu | Effect |
| --- | --- | --- |
| Create snippets file | Snippets | Writes `.turbo-python/snippets.toml` with worked examples, then opens it. Greyed out once the project has one. |
| Open snippets file | Snippets | Opens `.turbo-python/snippets.toml`. Greyed out until the project has one. Always the project's file, never your own — it is the file the item above it writes. |

The file is written through a temporary file in the same directory, renamed into place, so an interrupted write leaves the previous file intact.

## Errors

| Message | Cause |
| --- | --- |
| `Cannot read snippets` in the menu | A snippets file is present but not valid TOML, or holds a snippet with no name or no body |
| `Already there: .turbo-python/snippets.toml` | Creating in a project that already has one. Unreachable from the menu, which greys the item out; still possible for a caller that is not a menu. |
| `This project has no .turbo-python/snippets.toml yet.` | Opening in a project that has none, likewise |
| `Cannot tell which directory this is: …` | The working directory could not be read |

## See also

- [How to insert snippets from a menu](../how-to/use-snippets.md)
- [Snippets](../explanation/snippets.md)
- [Keyboard](keyboard.md)