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-golo/snippets.toml |
The project's snippets |
$TURBO_GOLO_SNIPPET_DIR/snippets.toml, else <user config>/turbo-golo/snippets.toml |
Your own, shared across projects |
<user config> is os.UserConfigDir(): ~/.config on Linux, ~/Library/Application Support on macOS. TURBO_GOLO_DIR replaces it when set.
| 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: golo, toml, yaml, markdown, javascript, html, xml, dockerfile, bash. See Languages coloured.
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
[[snippet]]
name = "try"
group = "Golo"
languages = ["golo"]
body = '''
try {
throw "boom"
} catch (e) {
println("caught: \"" + e + "\"")
} finally {
println("done")
}'''
TOML's ''' literal strings drop the newline immediately after the opening quotes and keep every backslash as it is written — which is what a Golo body needs, since Golo strings carry \n and \". A """ basic string also drops that first newline, but resolves \t, \n and \" before the editor sees them.
The starter file
Snippets ▸ Create snippets file writes fourteen snippets:
| Group | Names | languages |
|---|---|---|
| Golo | module, main, function, closure, struct, union, augment, match, foreach, for, try, comprehension |
["golo"] |
| General | Hello |
none |
| Markdown | Image |
["markdown"] |
The Golo bodies are indented with two spaces and written as literal strings.
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 |
A .golo file is of language golo; so is a file with no extension whose first line is a shebang naming golo.
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-golo/snippets.toml with the starter snippets above, then opens it. Greyed out once the project has one. |
| Open snippets file | Snippets | Opens .turbo-golo/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-golo/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-golo/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
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 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 |
|