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
 94
 95
 96
 97
 98
 99
100
101

# 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 Golo 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-golo/snippets.toml`, filled in with a dozen Golo constructs and a couple of general ones, and opens it — coloured, because Turbo Golo colours TOML:

```toml
[[snippet]]
name = "main"
group = "Golo"
languages = ["golo"]
body = '''
function main = |args| {
  println("Hello, Golo!")
}'''

[[snippet]]
group = "General"
name = "Hello"
body = "Hello!!!"
```

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:

```
function main = |args| {
  |                              ← cursor here
}
```

becomes, after **Golo ▸ foreach**,

```
function main = |args| {
  foreach item in list[1, 2, 3] {
    println(item)
  }
}
```

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

## Keep snippets across every project

Put them in `~/.config/turbo-golo/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 — `golo`, `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.

## Write a Golo body

Two habits, both taken from the starter file:

- **Indent with two spaces.** It is what every example in the GoloScript documentation uses, and Golo has no formatter to disagree with, so it is the only convention there is.
- **Use a literal string** — `'''…'''`, single quotes — for any body with a backslash in it. A Golo string carries `\n` and `\"` the way a Go string does, and in a TOML basic string (`"""…"""`) those escapes are resolved before the editor sees them: `println("caught: \"" + e + "\"")` would arrive with real quotation marks in it and no longer parse. Inside `'''` a backslash is just a backslash.

## Variants

- **You started the editor from a subdirectory.** The project's file is not found: only `./.turbo-golo` 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 a tab in a body.** In a basic string, write `\t` and TOML turns it into a tab when it reads the file. In a literal string, `\t` stays two characters — type the tab itself.

## See also

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